chore: add TSDocs to the API Key Module (#6785)

Add TSDocs to the API Key Module's resources

packages/types/src/api-key/common/api-key.ts

@@ -1,23 +1,91 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ *
+ * An API key's type.
+ */
 export type ApiKeyType = "secret" | "publishable"
+
+/**
+ * The API key details.
+ */
 export interface ApiKeyDTO {
+  /**
+   * The ID of the API key.
+   */
   id: string
+
+  /**
+   * The token of the API key.
+   */
   token: string
+
+  /**
+   * The redacted form of the API key's token. This is useful
+   * when showing portion of the token. For example `sk_...123`.
+   */
   redacted: string
+
+  /**
+   * The title of the API key.
+   */
   title: string
+
+  /**
+   * The type of the API key.
+   */
   type: ApiKeyType
+
+  /**
+   * The date the API key was last used.
+   */
   last_used_at: Date | null
+
+  /**
+   * Who created the API key.
+   */
   created_by: string
+
+  /**
+   * The date the API key was created.
+   */
   created_at: Date
+
+  /**
+   * Who revoked the API key. For example,
+   * the ID of the user that revoked it.
+   */
   revoked_by: string | null
+
+  /**
+   * The date the API key was revoked.
+   */
   revoked_at: Date | null
 }
 
+/**
+ * The filters to apply on the retrieved API keys.
+ */
 export interface FilterableApiKeyProps
   extends BaseFilterable<FilterableApiKeyProps> {
+  /**
+   * The IDs to filter the API keys by.
+   */
   id?: string | string[]
+
+  /**
+   * The tokens to filter the API keys by.
+   */
   token?: string | string[]
+
+  /**
+   * The titles to filter the API keys by.
+   */
   title?: string | string[]
+
+  /**
+   * Filter the API keys by their type.
+   */
   type?: ApiKeyType
 }

packages/types/src/api-key/mutations/api-key.ts

@@ -1,24 +1,73 @@
 import { ApiKeyType } from "../common"
 
+/**
+ * The API key to be created.
+ */
 export interface CreateApiKeyDTO {
+  /**
+   * The title of the API key.
+   */
   title: string
+
+  /**
+   * The type of the API key.
+   */
   type: ApiKeyType
+
+  /**
+   * Who created the API key.
+   */
   created_by: string
   // We could add revoked_at as a parameter (or expires_at that gets mapped to revoked_at internally) in order to support expiring tokens
 }
 
+/**
+ * The attributes in the API key to be created or updated.
+ */
 export interface UpsertApiKeyDTO {
+  /**
+   * The ID of the API key.
+   */
   id?: string
+
+  /**
+   * The title of the API key.
+   */
   title?: string
+
+  /**
+   * The type of the API key. Required only when creating an API key.
+   */
   type?: ApiKeyType
+
+  /**
+   * Who created the API key. It's only
+   * usable and required when creating an API key.
+   */
   created_by?: string
 }
 
+/**
+ * The attributes to update in the API key.
+ */
 export interface UpdateApiKeyDTO {
+  /**
+   * The title of the API key.
+   */
   title?: string
 }
 
+/**
+ * The details of revoking an API key.
+ */
 export interface RevokeApiKeyDTO {
+  /**
+   * Who revoked the API key.
+   */
   revoked_by: string
-  revoke_in?: number // Seconds after which the token should be considered revoked
+
+  /**
+   * When to revoke the API key (time in seconds).
+   */
+  revoke_in?: number
 }

packages/types/src/api-key/service.ts

@@ -9,44 +9,91 @@ import {
   UpsertApiKeyDTO,
 } from "./mutations"
 
+/**
+ * The main service interface for the Api Key Module.
+ */
 export interface IApiKeyModuleService extends IModuleService {
   /**
-   * Create a new api key
+   * This method creates API keys.
-   * @param data
+   *
-   * @param sharedContext
+   * @param {CreateApiKeyDTO[]} data - The API keys to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO[]>} The created API keys.
+   *
+   * @example
+   * const apiKey = await apiKeyModuleService.create([{
+   *   title: "Development API key",
+   *   type: "publishable",
+   *   created_by: "user_123"
+   * }])
    */
   create(data: CreateApiKeyDTO[], sharedContext?: Context): Promise<ApiKeyDTO[]>
+
+  /**
+   * This method creates an API key.
+   *
+   * @param {CreateApiKeyDTO} data - The API key to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO>} The created API key.
+   *
+   * @example
+   * const apiKey = await apiKeyModuleService.create({
+   *   title: "Development API key",
+   *   type: "publishable",
+   *   created_by: "user_123"
+   * })
+   */
   create(data: CreateApiKeyDTO, sharedContext?: Context): Promise<ApiKeyDTO>
 
   /**
-   * This method updates existing API keys, or creates new ones if they don't exist.
+   * This method updates or creates API keys if they don't exist.
    *
-   * @param {UpsertApiKeyDTO[]} data - The attributes to update or create for each API key.
+   * @param {UpsertApiKeyDTO[]} data - The attributes in the API keys that are created or updated.
-   * @returns {Promise<ApiKeyDTO[]>} The updated and created API keys.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO[]>} The created or updated API keys.
    *
    * @example
-   * {example-code}
+   * const apiKey = await apiKeyModuleService.upsert([
+   *   {
+   *     id: "apk_123",
+   *     title: "My development key",
+   *   },
+   *   {
+   *     title: "New development key",
+   *     type: "secret",
+   *     created_by: "user_123",
+   *   },
+   * ])
    */
   upsert(data: UpsertApiKeyDTO[], sharedContext?: Context): Promise<ApiKeyDTO[]>
 
   /**
-   * This method updates an existing API key, or creates a new one if it doesn't exist.
+   * This method updates or creates an API key if it doesn't exist.
    *
-   * @param {UpsertApiKeyDTO} data - The attributes to update or create for the API key.
+   * @param {UpsertApiKeyDTO} data - The attributes in the API key that's created or updated.
-   * @returns {Promise<ApiKeyDTO>} The updated or created API key.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO>} The created or updated API key.
    *
    * @example
-   * {example-code}
+   * const apiKey = await apiKeyModuleService.upsert({
+   *   id: "apk_123",
+   *   title: "My development key"
+   * })
    */
   upsert(data: UpsertApiKeyDTO, sharedContext?: Context): Promise<ApiKeyDTO>
 
   /**
    * This method updates an existing API key.
    *
-   * @param {string} id - The API key's ID.
+   * @param {string} id - The ID of the API key.
-   * @param {UpdateApiKeyDTO} data - The details to update in the API key.
+   * @param {UpdateApiKeyDTO} data - The attributes to update in the API key.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<ApiKeyDTO>} The updated API key.
+   *
+   * @example
+   * const apiKey = await apiKeyModuleService.update("apk_123", {
+   *   title: "My development key"
+   * })
    */
   update(
     id: string,
@@ -57,13 +104,20 @@ export interface IApiKeyModuleService extends IModuleService {
   /**
    * This method updates existing API keys.
    *
-   * @param {FilterableApiKeyProps} selector - The filters to specify which API keys should be updated.
+   * @param {FilterableApiKeyProps} selector - The filters that specify which API keys should be updated.
-   * @param {UpdateApiKeyDTO} data - The details to update in the API keys.
+   * @param {UpdateApiKeyDTO} data - The attributes to update in the API keys.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<ApiKeyDTO[]>} The updated API keys.
    *
    * @example
-   * {example-code}
+   * const apiKey = await apiKeyModuleService.update(
+   *   {
+   *     title: "Development key",
+   *   },
+   *   {
+   *     title: "My development key",
+   *   }
+   * )
    */
   update(
     selector: FilterableApiKeyProps,
@@ -72,18 +126,40 @@ export interface IApiKeyModuleService extends IModuleService {
   ): Promise<ApiKeyDTO[]>
 
   /**
-   * Delete an api key
+   * This method deletes API keys by their IDs.
-   * @param ids
+   *
-   * @param sharedContext
+   * @param {string[]} ids - The IDs of the API keys.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the API keys are deleted successfully.
+   *
+   * @example
+   * await apiKeyModuleService.delete(["apk_123"])
    */
   delete(ids: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes an API key by its ID.
+   *
+   * @param {string} id - The ID of the API key.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the API key is deleted successfully.
+   *
+   * @example
+   * await apiKeyModuleService.delete("apk_123")
+   */
   delete(id: string, sharedContext?: Context): Promise<void>
 
   /**
-   * Retrieve an api key
+   * This method retrieves an API key by its ID.
-   * @param id
+   *
-   * @param config
+   * @param {string} id - The ID of the API key.
-   * @param sharedContext
+   * @param {FindConfig<ApiKeyDTO>} config - The configurations determining how the API key is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a api key.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO>} The retrieved API key.
+   *
+   * @example
+   * const apiKey = await apiKeyModuleService.retrieve("apk_123")
    */
   retrieve(
     id: string,
@@ -92,10 +168,36 @@ export interface IApiKeyModuleService extends IModuleService {
   ): Promise<ApiKeyDTO>
 
   /**
-   * List api keys
+   * This method retrieves a paginated list of API keys based on optional filters and configuration.
-   * @param filters
+   *
-   * @param config
+   * @param {FilterableApiKeyProps} filters - The filters to apply on the retrieved API keys.
-   * @param sharedContext
+   * @param {FindConfig<ApiKeyDTO>} config - The configurations determining how the API key is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a API key.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO[]>} The list of API keys.
+   *
+   * @example
+   * To retrieve a list of API keys using their IDs:
+   *
+   * ```ts
+   * const apiKeys = await apiKeyModuleService.list({
+   *   id: ["apk_123", "apk_321"]
+   * })
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const apiKeys = await apiKeyModuleService.list(
+   *   {
+   *     id: ["apk_123", "apk_321"],
+   *   },
+   *   {
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
    */
   list(
     filters?: FilterableApiKeyProps,
@@ -104,10 +206,38 @@ export interface IApiKeyModuleService extends IModuleService {
   ): Promise<ApiKeyDTO[]>
 
   /**
-   * List and count api keys
+   * This method retrieves a paginated list of API keys along with the total count of available API keys satisfying the provided filters.
-   * @param filters
+   *
-   * @param config
+   * @param {FilterableApiKeyProps} filters - The filters to apply on the retrieved API keys.
-   * @param sharedContext
+   * @param {FindConfig<ApiKeyDTO>} config - The configurations determining how the api API is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a API key.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[ApiKeyDTO[], number]>} The list of API keys along with their total count.
+   *
+   * @example
+   * To retrieve a list of API keys using their IDs:
+   *
+   * ```ts
+   * const [apiKeys, count] =
+   * await apiKeyModuleService.listAndCount({
+   *   id: ["apk_123", "apk_321"],
+   * })
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const [apiKeys, count] =
+   *   await apiKeyModuleService.listAndCount(
+   *     {
+   *       id: ["apk_123", "apk_321"],
+   *     },
+   *     {
+   *       take: 15,
+   *       skip: 2,
+   *     }
+   *   )
+   * ```
    */
   listAndCount(
     filters?: FilterableApiKeyProps,
@@ -116,21 +246,45 @@ export interface IApiKeyModuleService extends IModuleService {
   ): Promise<[ApiKeyDTO[], number]>
 
   /**
-   * Revokes an api key
+   * This method revokes API keys based on the filters provided.
-   * @param selector
+   *
-   * @param data
+   * @param {FilterableApiKeyProps} selector - The filters to specify which API keys should be revoked.
-   * @param sharedContext
+   * @param {RevokeApiKeyDTO} data - The details of revoking the API keys.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO[]>} The revoked API keys.
+   *
+   * @example
+   * const apiKey = await apiKeyModuleService.revoke(
+   *   {
+   *     id: "apk_123",
+   *   },
+   *   {
+   *     revoked_by: "user_123",
+   *     // 1 minute
+   *     revoke_in: 60,
+   *   }
+   * )
    */
   revoke(
     selector: FilterableApiKeyProps,
     data: RevokeApiKeyDTO,
     sharedContext?: Context
   ): Promise<ApiKeyDTO[]>
+
   /**
-   * Revokes an api key
+   * This method revokes an API key based on the ID provided.
-   * @param id
+   *
-   * @param data
+   * @param {string} id - The ID of the API key to revoke.
-   * @param sharedContext
+   * @param {RevokeApiKeyDTO} data - The details of revoking the API key.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<ApiKeyDTO>} The revoked API key.
+   *
+   * @example
+   * const apiKey = await apiKeyModuleService.revoke("apk_123", {
+   *   revoked_by: "user_123",
+   *   // 1 minute
+   *   revoke_in: 60,
+   * })
    */
   revoke(
     id: string,
@@ -139,9 +293,19 @@ export interface IApiKeyModuleService extends IModuleService {
   ): Promise<ApiKeyDTO>
 
   /**
-   * Check the validity of an api key
+   * This method verifies whether a token is valid, considering it authenticated.
-   * @param token
+   *
-   * @param sharedContext
+   * @param {string} token - The token to verify.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<false | ApiKeyDTO>} If the token is verified successfully, the API key associated with the token is returned. Otherwise, `false` is returned.
+   *
+   * @example
+   * const apiKey =
+   *   await apiKeyModuleService.authenticate("AbCD123987")
+   *
+   * if (!apiKey) {
+   *   // authentication failed
+   * }
    */
   authenticate(
     token: string,