asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

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

Browse Source 
Add TSDocs to the API Key Module's resources
This commit is contained in:
Shahed Nasser
2024-03-22 14:23:44 +02:00
committed by GitHub
parent 4c98545ab3
commit bb3cace0cd
3 changed files with 324 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
packages/types/src/api-key/common/api-key.ts
View File

@@ -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
}

51
packages/types/src/api-key/mutations/api-key.ts
View File

@@ -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
}

248
packages/types/src/api-key/service.ts
View File

@@ -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<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.
* @returns {Promise<ApiKeyDTO[]>} 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<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.
* @returns {Promise<ApiKeyDTO>} 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<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 {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<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 {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<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
* @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<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
* @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<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
* @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<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
* @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<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
* @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<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
* @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<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
* @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<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,