chore(core-flows,types): improve TSDocs of user-related workflows (#11017)

Author: shahednasser

packages/core/core-flows/src/auth/steps/set-auth-app-metadata.ts

@@ -11,7 +11,36 @@ export type SetAuthAppMetadataStepInput = {
 
 export const setAuthAppMetadataStepId = "set-auth-app-metadata"
 /**
- * This step sets the `app_metadata` property of an auth identity.
+ * This step sets the `app_metadata` property of an auth identity. This is useful to
+ * associate a user (whether it's an admin user or customer) with an auth identity
+ * that allows them to authenticate into Medusa.
+ * 
+ * You can learn more about auth identites in 
+ * [this documentation](https://docs.medusajs.com/resources/commerce-modules/auth/auth-identity-and-actor-types).
+ * 
+ * To use this for a custom actor type, check out [this guide](https://docs.medusajs.com/resources/commerce-modules/auth/create-actor-type)
+ * that explains how to create a custom `manager` actor type and manage its users.
+ * 
+ * @example
+ * To associate an auth identity with an actor type (user, customer, or other actor types):
+ * 
+ * ```ts
+ * const data = setAuthAppMetadataStep({
+ *   authIdentityId: "au_1234",
+ *   actorType: "user", // or `customer`, or custom type
+ *   value: "user_123"
+ * })
+ * ```
+ * 
+ * To remove the association with an actor type, such as when deleting the user:
+ * 
+ * ```ts
+ * const data = setAuthAppMetadataStep({
+ *   authIdentityId: "au_1234",
+ *   actorType: "user", // or `customer`, or custom type
+ *   value: null
+ * })
+ * ```
  */
 export const setAuthAppMetadataStep = createStep(
   setAuthAppMetadataStepId,

packages/core/core-flows/src/auth/workflows/generate-reset-password-token.ts

@@ -10,6 +10,35 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { emitEventStep, useRemoteQueryStep } from "../../common"
 
+/**
+ * This workflow generates a reset password token for a user. It's used by the
+ * [Generate Reset Password Token for Admin](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerresetpassword)
+ * and [Generate Reset Password Token for Customer](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerresetpassword)
+ * API Routes.
+ * 
+ * The workflow emits the `auth.password_reset` event, which you can listen to in
+ * a [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers). Follow
+ * [this guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password) to learn
+ * how to handle this event.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * generate reset password tokens within your custom flows.
+ * 
+ * @example
+ * const { result } = await generateResetPasswordTokenWorkflow(container)
+ * .run({
+ *   input: {
+ *     entityId: "example@gmail.com",
+ *     actorType: "customer",
+ *     provider: "emailpass",
+ *     secret: "jwt_123" // jwt secret
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Generate a reset password token for a user or customer.
+ */
 export const generateResetPasswordTokenWorkflow = createWorkflow(
   "generate-reset-password-token",
   (input: {

packages/core/core-flows/src/invite/steps/create-invites.ts

@@ -5,6 +5,13 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createInviteStepId = "create-invite-step"
 /**
  * This step creates one or more invites.
+ * 
+ * @example
+ * const data = createInviteStep([
+ *   {
+ *     email: "example@gmail.com"
+ *   }
+ * ])
  */
 export const createInviteStep = createStep(
   createInviteStepId,

packages/core/core-flows/src/invite/steps/delete-invites.ts

@@ -2,13 +2,18 @@ import { IUserModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the invites to delete.
+ */
+export type DeleteInvitesStepInput = string[]
+
 export const deleteInvitesStepId = "delete-invites-step"
 /**
  * This step deletes one or more invites.
  */
 export const deleteInvitesStep = createStep(
   deleteInvitesStepId,
-  async (input: string[], { container }) => {
+  async (input: DeleteInvitesStepInput, { container }) => {
     const service: IUserModuleService = container.resolve(Modules.USER)
 
     await service.softDeleteInvites(input)

packages/core/core-flows/src/invite/steps/refresh-invite-tokens.ts

@@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The IDs of the invites to refresh.
+ */
+export type RefreshInviteTokensStepInput = string[]
+
 export const refreshInviteTokensStepId = "refresh-invite-tokens-step"
 /**
  * This step refreshes the tokens of one or more invites.
  */
 export const refreshInviteTokensStep = createStep(
   refreshInviteTokensStepId,
-  async (input: string[], { container }) => {
+  async (input: RefreshInviteTokensStepInput, { container }) => {
     const service: IUserModuleService = container.resolve(Modules.USER)
 
     const invites = await service.refreshInviteTokens(input)

packages/core/core-flows/src/invite/steps/validate-token.ts

@@ -2,13 +2,19 @@ import { IUserModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The token to validate.
+ */
+export type ValidateTokenStepInput = string
+
 export const validateTokenStepId = "validate-invite-token-step"
 /**
  * This step validates a specified token and returns its associated invite.
+ * If not valid, the step throws an error.
  */
 export const validateTokenStep = createStep(
   validateTokenStepId,
-  async (input: string, { container }) => {
+  async (input: ValidateTokenStepInput, { container }) => {
     const userModuleService: IUserModuleService = container.resolve(
       Modules.USER
     )

packages/core/core-flows/src/invite/workflows/accept-invite.ts

@@ -15,7 +15,33 @@ import { validateTokenStep } from "../steps/validate-token"
 
 export const acceptInviteWorkflowId = "accept-invite-workflow"
 /**
- * This workflow accepts an invite and creates a user.
+ * This workflow accepts an invite and creates a user. It's used by the
+ * [Accept Invite Admin API Route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept).
+ * 
+ * The workflow throws an error if the specified token is not valid. Also, the workflow
+ * requires an auth identity to be created previously. You can create an auth identity
+ * using the [Retrieve Registration JWT Token API Route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_provider_register).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * accept invites within your custom flows.
+ * 
+ * @example
+ * const { result } = await acceptInviteWorkflow(container)
+ * .run({
+ *   input: {
+ *     invite_token: "sk_123",
+ *     auth_identity_id: "au_123",
+ *     user: {
+ *       email: "example@gmail.com",
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Accept invite and create user.
  */
 export const acceptInviteWorkflow = createWorkflow(
   acceptInviteWorkflowId,

packages/core/core-flows/src/invite/workflows/create-invites.ts

@@ -10,7 +10,27 @@ import { emitEventStep } from "../../common/steps/emit-event"
 import { createInviteStep } from "../steps"
 export const createInvitesWorkflowId = "create-invite-step"
 /**
- * This workflow creates one or more invites.
+ * This workflow creates one or more user invites. It's used by the
+ * [Create Invite Admin API Route](https://docs.medusajs.com/api/admin#invites_postinvites).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * create invites within your custom flows.
+ * 
+ * @example
+ * const { result } = await createInvitesWorkflow(container)
+ * .run({
+ *   input: {
+ *     invites: [
+ *       {
+ *         email: "example@gmail.com"
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more user invites.
  */
 export const createInvitesWorkflow = createWorkflow(
   createInvitesWorkflowId,

packages/core/core-flows/src/invite/workflows/delete-invites.ts

@@ -10,7 +10,23 @@ import { deleteInvitesStep } from "../steps"
 
 export const deleteInvitesWorkflowId = "delete-invites-workflow"
 /**
- * This workflow deletes one or more invites.
+ * This workflow deletes one or more user invites. It's used by the
+ * [Delete Invites Admin API Route](https://docs.medusajs.com/api/admin#invites_deleteinvitesid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * delete invites within your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteInvitesWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["invite_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more user invites.
  */
 export const deleteInvitesWorkflow = createWorkflow(
   deleteInvitesWorkflowId,

packages/core/core-flows/src/invite/workflows/refresh-invite-tokens.ts

@@ -12,7 +12,27 @@ import { refreshInviteTokensStep } from "../steps/refresh-invite-tokens"
 
 export const refreshInviteTokensWorkflowId = "refresh-invite-tokens-workflow"
 /**
- * This workflow refreshes the token of one or more invites.
+ * This workflow refreshes the token of one or more user invites, updating the
+ * token and the expiry date. It's used by the
+ * [Refresh Invite Token Admin API Route](https://docs.medusajs.com/api/admin#invites_postinvitesidresend).
+ * 
+ * This workflow is useful to trigger resending invite tokens. It emits the `invite.resent` event,
+ * which you can listen to in a [Subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * refresh invite tokens within your custom flows.
+ * 
+ * @example
+ * const { result } = await refreshInviteTokensWorkflow(container)
+ * .run({
+ *   input: {
+ *     invite_ids: ["invite_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Refresh user invite tokens.
  */
 export const refreshInviteTokensWorkflow = createWorkflow(
   refreshInviteTokensWorkflowId,