From bb3cace0cdf4a9d2ba146f8a3b72f5162dd0ba86 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 22 Mar 2024 14:23:44 +0200 Subject: [PATCH] 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 | 68 +++++ .../types/src/api-key/mutations/api-key.ts | 51 +++- packages/types/src/api-key/service.ts | 248 +++++++++++++++--- 3 files changed, 324 insertions(+), 43 deletions(-) diff --git a/packages/types/src/api-key/common/api-key.ts b/packages/types/src/api-key/common/api-key.ts index 00601586f2..9ecf041092 100644 --- a/packages/types/src/api-key/common/api-key.ts +++ b/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 { + /** + * 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 } diff --git a/packages/types/src/api-key/mutations/api-key.ts b/packages/types/src/api-key/mutations/api-key.ts index 168f9bf166..8b098a2749 100644 --- a/packages/types/src/api-key/mutations/api-key.ts +++ b/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 } diff --git a/packages/types/src/api-key/service.ts b/packages/types/src/api-key/service.ts index ee9df48df8..da478ad6ed 100644 --- a/packages/types/src/api-key/service.ts +++ b/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 - * @param data - * @param sharedContext + * This method creates API keys. + * + * @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} 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 + + /** + * 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} 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 /** - * 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. - * @returns {Promise} The updated and created API keys. + * @param {UpsertApiKeyDTO[]} data - The attributes in the API keys that are created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} 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 /** - * 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. - * @returns {Promise} The updated or created API key. + * @param {UpsertApiKeyDTO} data - The attributes in the API key that's created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} 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 /** * This method updates an existing API key. * - * @param {string} id - The API key's ID. - * @param {UpdateApiKeyDTO} data - The details to update in the API key. + * @param {string} id - The ID of 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} 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 {UpdateApiKeyDTO} data - The details to update in the API keys. + * @param {FilterableApiKeyProps} selector - The filters that specify which API keys should be updated. + * @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} 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 /** - * Delete an api key - * @param ids - * @param sharedContext + * This method deletes API keys by their IDs. + * + * @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} Resolves when the API keys are deleted successfully. + * + * @example + * await apiKeyModuleService.delete(["apk_123"]) */ delete(ids: string[], sharedContext?: Context): Promise + + /** + * 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} Resolves when the API key is deleted successfully. + * + * @example + * await apiKeyModuleService.delete("apk_123") + */ delete(id: string, sharedContext?: Context): Promise /** - * Retrieve an api key - * @param id - * @param config - * @param sharedContext + * This method retrieves an API key by its ID. + * + * @param {string} id - The ID of the API key. + * @param {FindConfig} 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} 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 /** - * List api keys - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of API keys based on optional filters and configuration. + * + * @param {FilterableApiKeyProps} filters - The filters to apply on the retrieved API keys. + * @param {FindConfig} 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} 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 /** - * List and count api keys - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of API keys along with the total count of available API keys satisfying the provided filters. + * + * @param {FilterableApiKeyProps} filters - The filters to apply on the retrieved API keys. + * @param {FindConfig} 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 - * @param selector - * @param data - * @param sharedContext + * This method revokes API keys based on the filters provided. + * + * @param {FilterableApiKeyProps} selector - The filters to specify which API keys should be revoked. + * @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} 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 + /** - * Revokes an api key - * @param id - * @param data - * @param sharedContext + * This method revokes an API key based on the ID provided. + * + * @param {string} id - The ID of the API key to revoke. + * @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} 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 /** - * Check the validity of an api key - * @param token - * @param sharedContext + * This method verifies whether a token is valid, considering it authenticated. + * + * @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} 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,