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

chore: added tsdocs for the Auth Module (#6863)

Browse Source
This commit is contained in:
Shahed Nasser
2024-04-05 13:01:08 +03:00
committed by GitHub
parent f65e1dedbc
commit d345496dbc
3 changed files with 187 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
packages/types/src/auth/common/auth-user.ts
View File

@@ -12,32 +12,34 @@ export type AuthUserDTO = {
id: string
/**
* The provider of the auth user.
* The ID of the provider used to authenticate the user.
*/
provider: string
/**
* The associated providers entity's ID.
* The user's identifier. For example, when using the `emailpass`
* provider, the `entity_id` would be the user's email.
*/
entity_id: string
/**
* The scope of the auth user.
* The scope of the auth user. For example,
* `admin` or `store`.
*/
scope: string
/**
* The provider metadata of the auth user.
* Holds custom data related to the provider in key-value pairs.
*/
provider_metadata?: Record<string, unknown>
/**
* The user metadata of the auth user.
* Holds custom data related to the user in key-value pairs.
*/
user_metadata: Record<string, unknown>
/**
* The app metadata of the auth user.
* Holds custom data related to the third-party app in key-value pairs.
*/
app_metadata: Record<string, unknown>
}
@@ -54,32 +56,35 @@ export type CreateAuthUserDTO = {
id?: string
/**
* The provider of the auth user.
* The ID of the provider used to authenticate
* the user.
*/
provider: string
/**
* The associated entity's ID.
* The user's identifier. For example, when using the `emailpass`
* provider, the `entity_id` would be the user's email.
*/
entity_id: string
/**
* The scope of the auth user.
* The scope of the auth user. For example,
* `admin` or `store`.
*/
scope: string
/**
* The provider metadata of the auth user.
* Holds custom data related to the provider in key-value pairs.
*/
provider_metadata?: Record<string, unknown>
/**
* The user metadata of the auth user.
* Holds custom data related to the user in key-value pairs.
*/
user_metadata?: Record<string, unknown>
/**
* The app metadata of the auth user.
* Holds custom data related to the third-party app in key-value pairs.
*/
app_metadata?: Record<string, unknown>
}
@@ -96,17 +101,17 @@ export type UpdateAuthUserDTO = {
id: string
/**
* The provider metadata of the auth user.
* Holds custom data related to the provider in key-value pairs.
*/
provider_metadata?: Record<string, unknown>
/**
* The user metadata of the auth user.
* Holds custom data related to the user in key-value pairs.
*/
user_metadata?: Record<string, unknown>
/**
* The app metadata of the auth user.
* Holds custom data related to the third-party app in key-value pairs.
*/
app_metadata?: Record<string, unknown>
}
@@ -122,7 +127,7 @@ export interface FilterableAuthUserProps
id?: string[]
/**
* Filter the auth auth user by the associated provider(s).
* Filter the auth users by the ID of their auth provider.
*/
provider?: string[] | string
}

43
packages/types/src/auth/common/provider.ts
View File

@@ -10,23 +10,34 @@ export type AuthenticationResponse = {
success: boolean
/**
* The authenticated user's details. The details shape
* depends on the used provider ID.
* The authenticated user's details.
*/
authUser?: any
/**
* The error message, if an error occurs.
* If an error occurs during the authentication process,
* whether within the Auth Module or a third-party provider,
* the error message is set in this field.
*/
error?: string
/**
* Redirect location. Location takes precedence over success.
* The URL to redirect to for further authentication action
* with a third-party provider. This takes precedence before
* the `success` field.
*
* So, after checking that authentication is successful,
* you should check whether this field is defined and, if so, redirect to the
* specified location.
*/
location?: string
/**
* Redirect url for successful authentication.
* Some authentication providers support redirecting to a specified URL on
* success. In those cases, the URL to redirect to is set in this field.
*
* So, if `success` is true, there's no `location` set, and this field
* is set, you can redirect to this URL.
*/
successRedirectUrl?: string
}
@@ -34,16 +45,17 @@ export type AuthenticationResponse = {
/**
* @interface
*
* Provider configuration for the Medusa auth module.
* The configurations of the `providers` option
* passed to the Auth Module.
*/
export type AuthModuleProviderConfig = {
/**
* Provider name
* The provider's name.
*/
name: string
/**
* Scope configurations for the provider
* The scopes configuration of that provider.
*/
scopes: Record<string, AuthProviderScope>
}
@@ -51,18 +63,19 @@ export type AuthModuleProviderConfig = {
/**
* @interface
*
* Configuration of a single provider scope
* The scope configurations of an auth provider.
*/
export type AuthProviderScope = Record<string, unknown>
/**
* @interface
*
* Input for authentication and callback validation methods.
* The data passed to the auth provider when authenticating a user
* or validating a callback.
*/
export type AuthenticationInput = {
/**
* url of incoming authentication request.
* URL of the incoming authentication request.
*/
url: string
@@ -72,22 +85,22 @@ export type AuthenticationInput = {
headers: Record<string, string>
/**
* Query params of incoming authentication request.
* Query params of the incoming authentication request.
*/
query: Record<string, string>
/**
* Body of incoming authentication request.
* Body of the incoming authentication request.
*/
body: Record<string, string>
/**
* Scope for authentication request.
* Scope for the authentication request.
*/
authScope: string
/**
* Protocol of incoming authentication request (For example, `https`).
* Protocol of the incoming authentication request (For example, `https`).
*/
protocol: string
}

214
packages/types/src/auth/service.ts
View File

@@ -6,7 +6,6 @@ import {
FilterableAuthUserProps,
UpdateAuthUserDTO,
} from "./common"
import { Context } from "../shared-context"
import { FindConfig } from "../common"
import { IModuleService } from "../modules-sdk"
@@ -17,19 +16,37 @@ import { IModuleService } from "../modules-sdk"
export type JWTGenerationOptions = {
expiresIn?: string | number
}
/**
* The main service interface for the authentication module.
* The main service interface for the Auth Module.
*/
export interface IAuthModuleService extends IModuleService {
/**
* This method is the first invoked method of the authentication flow. It handles the incoming authentication request.
* This method is used to authenticate a user using a provider. The `authenticate` method of the
* underlying provider is called, passing it the `providerData` parameter as a parameter. The method
* returns the data returned by the provider.
*
* @param {string} provider - The provider to use for authentication.
* @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider
* @returns {Promise<AuthenticationResponse>} The authentication's result.
* Refer to [this guide](https://docs.medusajs.com/experimental/auth/auth-flows) to learn more about the authentication flows.
*
* @param {string} provider - The ID of the provider to authenticate the user with.
* @param {AuthenticationInput} providerData - The data to pass to the provider to authenticate the user.
* @returns {Promise<AuthenticationResponse>} The details of the authentication result.
*
* @example
* {example-code}
* The following example is in the context of an API route, where
* `req` is an instance of the `MedusaRequest` object:
*
* ```ts
* const { success, authUser, location, error } =
* await authModuleService.authenticate("emailpass", {
* url: req.url,
* headers: req.headers,
* query: req.query,
* body: req.body,
* authScope: "admin",
* protocol: req.protocol,
* } as AuthenticationInput)
* ```
*/
authenticate(
provider: string,
@@ -37,14 +54,38 @@ export interface IAuthModuleService extends IModuleService {
): Promise<AuthenticationResponse>
/**
* This method handles the callback from an authentication provider when an authentication has been initialized and the user is redirected.
* When authenticating users with a third-party provider, such as Google, the user performs an
* action to finish the authentication, such as enter their credentials in Google's sign-in
* form.
*
* @param {string} provider - The provider to use for callback validation.
* @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider
* @returns {Promise<AuthenticationResponse>} The authentication's result.
* In those cases, you must create an API route or endpoint that's called by the third-party
* provider when the user finishes performing the required action.
*
* In that API route, you can call this method to validate the third-party provider's
* callback and authenticate the user.
*
* Learn more about this authentication flow in [this guide](https://docs.medusajs.com/experimental/auth/auth-flows#authentication-with-third-party-service).
*
* @param {string} provider - The ID of the provider to use to validate the callback.
* @param {AuthenticationInput} providerData - The data to pass to the provider to validate the callback.
* @returns {Promise<AuthenticationResponse>} The details of the authentication result.
*
* @example
* {example-code}
* The following example is in the context of an API route, where
* `req` is an instance of the `MedusaRequest` object:
*
* ```ts
* const { success, authUser, error, successRedirectUrl } =
* await authModuleService.validateCallback("google", {
* url: req.url,
* headers: req.headers,
* query: req.query,
* body: req.body,
* authScope: "admin",
* protocol: req.protocol,
* } as AuthenticationInput)
* ```
*
*/
validateCallback(
provider: string,
@@ -52,28 +93,16 @@ export interface IAuthModuleService extends IModuleService {
): Promise<AuthenticationResponse>
/**
* This method retrieves the user by its ID.
* This method retrieves an auth user by its ID.
*
* @param {string} id - The ID of the retrieve.
* @param {string} id - The ID of the auth user.
* @param {FindConfig<AuthUserDTO>} config - The configurations determining how the auth user is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a auth user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<AuthUserDTO>} The retrieved user.
* @returns {Promise<AuthUserDTO>} The retrieved auth user.
*
* @example
* A simple example that retrieves a {type name} by its ID:
*
* ```ts
* {example-code}
* ```
*
* To specify relations that should be retrieved:
*
* ```ts
* {example-code}
* ```
*
*
* const authUser = await authModuleService.retrieve("authusr_1")
*/
retrieve(
id: string,
@@ -82,34 +111,36 @@ export interface IAuthModuleService extends IModuleService {
): Promise<AuthUserDTO>
/**
* This method retrieves a paginated list of users based on optional filters and configuration.
* This method retrieves a paginated list of auth users based on optional filters and configuration.
*
* @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth user.
* @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth users.
* @param {FindConfig<AuthUserDTO>} config - The configurations determining how the auth user is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a auth user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<AuthUserDTO[]>} The list of users.
* @returns {Promise<AuthUserDTO[]>} The list of auth users.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of auth users using their IDs:
*
* ```ts
* {example-code}
* const authUsers = await authModuleService.list({
* id: ["authusr_123", "authusr_321"],
* })
* ```
*
* To specify relations that should be retrieved within the {type name}:
* 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
* {example-code}
* const authUsers = await authModuleService.list(
* {
* id: ["authusr_123", "authusr_321"],
* },
* {
* take: 20,
* skip: 2,
* }
* )
* ```
*
* By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* ```
*
*
*/
list(
filters?: FilterableAuthUserProps,
@@ -118,34 +149,38 @@ export interface IAuthModuleService extends IModuleService {
): Promise<AuthUserDTO[]>
/**
* This method retrieves a paginated list of user along with the total count of available users satisfying the provided filters.
* This method retrieves a paginated list of auth users along with the total count of available auth users satisfying the provided filters.
*
* @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth user.
* @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth users.
* @param {FindConfig<AuthUserDTO>} config - The configurations determining how the auth user is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a auth user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<[AuthUserDTO[], number]>} The list of users along with their total count.
* @returns {Promise<[AuthUserDTO[], number]>} The list of auth users along with their total count.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of auth users using their IDs:
*
* ```ts
* {example-code}
* const [authUsers, count] =
* await authModuleService.listAndCount({
* id: ["authusr_123", "authusr_321"],
* })
* ```
*
* To specify relations that should be retrieved within the {type name}:
* 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
* {example-code}
* const [authUsers, count] =
* await authModuleService.listAndCount(
* {
* id: ["authusr_123", "authusr_321"],
* },
* {
* take: 20,
* skip: 2,
* }
* )
* ```
*
* By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* ```
*
*
*/
listAndCount(
filters?: FilterableAuthUserProps,
@@ -154,14 +189,25 @@ export interface IAuthModuleService extends IModuleService {
): Promise<[AuthUserDTO[], number]>
/**
* This method creates users
* This method creates auth users.
*
* @param {CreateAuthUserDTO[]} data - The auth user to be created.
* @param {CreateAuthUserDTO[]} data - The auth users to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<AuthUserDTO[]>} The created users.
* @returns {Promise<AuthUserDTO[]>} The created auth users.
*
* @example
* {example-code}
* const authUsers = await authModuleService.create([
* {
* provider: "emailpass",
* entity_id: "user@example.com",
* scope: "admin",
* },
* {
* provider: "google",
* entity_id: "user@gmail.com",
* scope: "email profile",
* },
* ])
*/
create(
data: CreateAuthUserDTO[],
@@ -169,26 +215,37 @@ export interface IAuthModuleService extends IModuleService {
): Promise<AuthUserDTO[]>
/**
* This method creates a user
* This method creates an auth user.
*
* @param {CreateAuthUserDTO} data - The auth user to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<AuthUserDTO>} The created user.
* @returns {Promise<AuthUserDTO>} The created auth user.
*
* @example
* {example-code}
* const authUser = await authModuleService.create({
* provider: "emailpass",
* entity_id: "user@example.com",
* scope: "admin",
* })
*/
create(data: CreateAuthUserDTO, sharedContext?: Context): Promise<AuthUserDTO>
/**
* This method updates existing users.
* This method updates existing auths.
*
* @param {UpdateAuthUserDTO[]} data - The attributes to update in the auth user.
* @param {UpdateAuthUserDTO[]} data - The attributes to update in the auth users.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<AuthUserDTO[]>} The updated users.
* @returns {Promise<AuthUserDTO[]>} The updated auths.
*
* @example
* {example-code}
* const authUsers = await authModuleService.update([
* {
* id: "authusr_123",
* app_metadata: {
* test: true,
* },
* },
* ])
*/
update(
data: UpdateAuthUserDTO[],
@@ -196,26 +253,31 @@ export interface IAuthModuleService extends IModuleService {
): Promise<AuthUserDTO[]>
/**
* This method updates existing user.
* This method updates an existing auth.
*
* @param {UpdateAuthUserDTO} data - The attributes to update in the auth user.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<AuthUserDTO>} The updated user.
* @returns {Promise<AuthUserDTO>} The updated auth.
*
* @example
* {example-code}
* const authUser = await authModuleService.update({
* id: "authusr_123",
* app_metadata: {
* test: true,
* },
* })
*/
update(data: UpdateAuthUserDTO, sharedContext?: Context): Promise<AuthUserDTO>
/**
* This method deletes users by their IDs.
* This method deletes a auth by its ID.
*
* @param {string[]} ids - The list of IDs of users to delete.
* @param {string[]} ids - The IDs of the auth.
* @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 users are deleted.
* @returns {Promise<void>} Resolves when {summary}
*
* @example
* {example-code}
* await authModuleService.delete(["authusr_123", "authusr_321"])
*/
delete(ids: string[], sharedContext?: Context): Promise<void>
}