From 544580e6a5afce51398670f0529c8352ede700fe Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 17 Jan 2025 16:13:00 +0200 Subject: [PATCH] chore(core-flows,types): improve TSDocs for remaining workflows (#11021) --- .../src/api-key/steps/create-api-keys.ts | 17 +++ .../src/api-key/steps/delete-api-keys.ts | 7 +- .../link-sales-channels-to-publishable-key.ts | 20 +++- .../src/api-key/steps/revoke-api-keys.ts | 19 ++++ .../src/api-key/steps/update-api-keys.ts | 19 ++++ .../steps/validate-sales-channel-exists.ts | 7 ++ .../src/api-key/workflows/create-api-keys.ts | 41 ++++++- .../src/api-key/workflows/delete-api-keys.ts | 28 ++++- .../link-sales-channels-to-publishable-key.ts | 27 ++++- .../src/api-key/workflows/revoke-api-keys.ts | 41 ++++++- .../src/api-key/workflows/update-api-keys.ts | 39 ++++++- .../src/common/steps/create-remote-links.ts | 31 ++---- .../src/common/steps/dismiss-remote-links.ts | 31 ++---- .../core-flows/src/common/steps/emit-event.ts | 22 +--- .../src/common/steps/remove-remote-links.ts | 25 +---- .../src/common/steps/update-remote-links.ts | 22 ++++ .../src/common/steps/use-query-graph.ts | 26 ++--- .../src/common/steps/use-remote-query.ts | 104 ++++++------------ .../src/common/workflows/batch-links.ts | 51 +++++++++ .../src/common/workflows/create-links.ts | 25 +++++ .../src/common/workflows/dismiss-links.ts | 25 +++++ .../src/common/workflows/update-links.ts | 30 +++++ .../defaults/steps/create-default-store.ts | 22 +++- .../src/defaults/workflows/create-defaults.ts | 15 ++- .../core-flows/src/file/steps/delete-files.ts | 16 ++- .../core-flows/src/file/steps/upload-files.ts | 41 ++++++- .../src/file/workflows/delete-files.ts | 21 +++- .../src/file/workflows/upload-files.ts | 52 ++++++++- packages/core/core-flows/src/index.ts | 1 + .../src/line-item/steps/delete-line-items.ts | 7 +- .../src/line-item/steps/list-line-items.ts | 43 ++++++++ .../src/line-item/steps/update-line-items.ts | 10 ++ .../line-item/workflows/delete-line-items.ts | 33 +++++- .../notification/steps/notify-on-failure.ts | 54 ++++++++- .../notification/steps/send-notifications.ts | 38 +++++++ .../steps/create-product-categories.ts | 15 +++ .../steps/delete-product-categories.ts | 7 +- .../steps/update-product-categories.ts | 19 ++++ .../workflows/create-product-categories.ts | 31 +++++- .../workflows/delete-product-categories.ts | 23 +++- .../workflows/update-product-categories.ts | 32 +++++- .../steps/create-return-reasons.ts | 8 ++ .../steps/delete-return-reasons.ts | 10 +- .../steps/update-return-reasons.ts | 19 ++++ .../workflows/create-return-reasons.ts | 36 +++++- .../workflows/delete-return-reasons.ts | 28 ++++- .../workflows/update-return-reasons.ts | 39 ++++++- .../associate-locations-with-channels.ts | 24 +++- .../steps/associate-products-with-channels.ts | 22 ++++ .../steps/can-delete-sales-channels.ts | 24 +++- .../steps/create-default-sales-channel.ts | 16 ++- .../steps/create-sales-channels.ts | 13 +++ .../steps/delete-sales-channels.ts | 7 +- .../steps/detach-locations-from-channels.ts | 24 +++- .../detach-products-from-sales-channels.ts | 22 ++++ .../steps/update-sales-channels.ts | 19 ++++ .../workflows/create-sales-channels.ts | 35 +++++- .../workflows/delete-sales-channels.ts | 28 ++++- .../link-products-to-sales-channel.ts | 31 +++++- .../workflows/update-sales-channels.ts | 39 ++++++- .../list-shipping-options-for-context.ts | 47 +++++++- .../steps/delete-shipping-profile.ts | 7 +- .../workflows/delete-shipping-profile.ts | 30 ++++- .../src/store/steps/create-stores.ts | 5 + .../src/store/steps/delete-stores.ts | 7 +- .../src/store/steps/update-stores.ts | 19 ++++ .../src/store/workflows/create-stores.ts | 41 ++++++- .../src/store/workflows/delete-stores.ts | 29 ++++- .../src/store/workflows/update-stores.ts | 30 ++++- .../types/src/api-key/mutations/api-key.ts | 2 + .../types/src/http/store/admin/payloads.ts | 40 ++++++- .../src/workflow/product-category/index.ts | 15 +++ .../core/types/src/workflow/store/index.ts | 29 +++++ 73 files changed, 1642 insertions(+), 240 deletions(-) diff --git a/packages/core/core-flows/src/api-key/steps/create-api-keys.ts b/packages/core/core-flows/src/api-key/steps/create-api-keys.ts index 6bb3765846..0b6ed31e34 100644 --- a/packages/core/core-flows/src/api-key/steps/create-api-keys.ts +++ b/packages/core/core-flows/src/api-key/steps/create-api-keys.ts @@ -5,13 +5,30 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create API keys. + */ export type CreateApiKeysStepInput = { + /** + * The API keys to create. + */ api_keys: CreateApiKeyDTO[] } export const createApiKeysStepId = "create-api-keys" /** * This step creates one or more API keys. + * + * @example + * const data = createApiKeysStep({ + * api_keys: [ + * { + * type: "publishable", + * title: "Storefront", + * created_by: "user_123" + * } + * ] + * }) */ export const createApiKeysStep = createStep( createApiKeysStepId, diff --git a/packages/core/core-flows/src/api-key/steps/delete-api-keys.ts b/packages/core/core-flows/src/api-key/steps/delete-api-keys.ts index f0cc2213f5..4a52247f93 100644 --- a/packages/core/core-flows/src/api-key/steps/delete-api-keys.ts +++ b/packages/core/core-flows/src/api-key/steps/delete-api-keys.ts @@ -2,13 +2,18 @@ import { IApiKeyModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the API keys to delete. + */ +export type DeleteApiKeysStepInput = string[] + export const deleteApiKeysStepId = "delete-api-keys" /** * This step deletes one or more API keys. */ export const deleteApiKeysStep = createStep( { name: deleteApiKeysStepId, noCompensation: true }, - async (ids: string[], { container }) => { + async (ids: DeleteApiKeysStepInput, { container }) => { const service = container.resolve(Modules.API_KEY) await service.deleteApiKeys(ids) diff --git a/packages/core/core-flows/src/api-key/steps/link-sales-channels-to-publishable-key.ts b/packages/core/core-flows/src/api-key/steps/link-sales-channels-to-publishable-key.ts index e91d5d1673..d86b6a5902 100644 --- a/packages/core/core-flows/src/api-key/steps/link-sales-channels-to-publishable-key.ts +++ b/packages/core/core-flows/src/api-key/steps/link-sales-channels-to-publishable-key.ts @@ -6,13 +6,29 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to manage the sales channels of a publishable API key. + * + * @property id - The ID of the publishable API key. + * @property add - The sales channel IDs to add to the publishable API key. + * @property remove - The sales channel IDs to remove from the publishable API key. + */ +export type LinkSalesChannelsToApiKeyStepInput = LinkWorkflowInput + export const linkSalesChannelsToApiKeyStepId = "link-sales-channels-to-api-key" /** - * This step links sales channels to API keys. + * This step manages the sales channels of a publishable API key. + * + * @example + * const data = linkSalesChannelsToApiKeyStep({ + * id: "apk_123", + * add: ["sc_123"], + * remove: ["sc_456"] + * }) */ export const linkSalesChannelsToApiKeyStep = createStep( linkSalesChannelsToApiKeyStepId, - async (input: LinkWorkflowInput, { container }) => { + async (input: LinkSalesChannelsToApiKeyStepInput, { container }) => { const remoteLink = container.resolve(ContainerRegistrationKeys.LINK) if (!input || (!input.add?.length && !input.remove?.length)) { return diff --git a/packages/core/core-flows/src/api-key/steps/revoke-api-keys.ts b/packages/core/core-flows/src/api-key/steps/revoke-api-keys.ts index 1f87fe4867..180fea857e 100644 --- a/packages/core/core-flows/src/api-key/steps/revoke-api-keys.ts +++ b/packages/core/core-flows/src/api-key/steps/revoke-api-keys.ts @@ -6,14 +6,33 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to revoke API keys. + */ export type RevokeApiKeysStepInput = { + /** + * The filters to select the API keys to revoke. + */ selector: FilterableApiKeyProps + /** + * The data to revoke the API keys. + */ revoke: RevokeApiKeyDTO } export const revokeApiKeysStepId = "revoke-api-keys" /** * This step revokes one or more API keys. + * + * @example + * const data = revokeApiKeysStep({ + * selector: { + * id: "apk_123" + * }, + * revoke: { + * revoked_by: "user_123" + * } + * }) */ export const revokeApiKeysStep = createStep( { name: revokeApiKeysStepId, noCompensation: true }, diff --git a/packages/core/core-flows/src/api-key/steps/update-api-keys.ts b/packages/core/core-flows/src/api-key/steps/update-api-keys.ts index 6adaa558e7..c09f92282d 100644 --- a/packages/core/core-flows/src/api-key/steps/update-api-keys.ts +++ b/packages/core/core-flows/src/api-key/steps/update-api-keys.ts @@ -9,14 +9,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update API keys. + */ export type UpdateApiKeysStepInput = { + /** + * The filters to select the API keys to update. + */ selector: FilterableApiKeyProps + /** + * The data to update the API keys. + */ update: UpdateApiKeyDTO } export const updateApiKeysStepId = "update-api-keys" /** * This step updates one or more API keys. + * + * @example + * const data = updateApiKeysStep({ + * selector: { + * id: "apk_123" + * }, + * update: { + * title: "Storefront" + * } + * }) */ export const updateApiKeysStep = createStep( updateApiKeysStepId, diff --git a/packages/core/core-flows/src/api-key/steps/validate-sales-channel-exists.ts b/packages/core/core-flows/src/api-key/steps/validate-sales-channel-exists.ts index 6cda3cec1a..d5f41df018 100644 --- a/packages/core/core-flows/src/api-key/steps/validate-sales-channel-exists.ts +++ b/packages/core/core-flows/src/api-key/steps/validate-sales-channel-exists.ts @@ -6,13 +6,20 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to validate that the sales channels exist. + */ export interface ValidateSalesChannelsExistStepInput { + /** + * The IDs of the sales channels to validate. + */ sales_channel_ids: string[] } export const validateSalesChannelsExistStepId = "validate-sales-channels-exist" /** * This step validates that a sales channel exists before linking it to an API key. + * If the sales channel does not exist, the step throws an error. */ export const validateSalesChannelsExistStep = createStep( validateSalesChannelsExistStepId, diff --git a/packages/core/core-flows/src/api-key/workflows/create-api-keys.ts b/packages/core/core-flows/src/api-key/workflows/create-api-keys.ts index 1981dca627..9efb2ef593 100644 --- a/packages/core/core-flows/src/api-key/workflows/create-api-keys.ts +++ b/packages/core/core-flows/src/api-key/workflows/create-api-keys.ts @@ -6,17 +6,52 @@ import { } from "@medusajs/framework/workflows-sdk" import { createApiKeysStep } from "../steps" -export type CreateApiKeysWorkflowInput = { api_keys: CreateApiKeyDTO[] } +/** + * The data to create API keys. + */ +export type CreateApiKeysWorkflowInput = { + /** + * The API keys to create. + */ + api_keys: CreateApiKeyDTO[] +} + +/** + * The created API keys. + */ +export type CreateApiKeysWorkflowOutput = ApiKeyDTO[] export const createApiKeysWorkflowId = "create-api-keys" /** - * This workflow creates one or more API keys. + * This workflow creates one or more API keys, which can be secret or publishable. It's used by the + * [Create API Key Admin API Route](https://docs.medusajs.com/api/admin#api-keys_postapikeys). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create API keys within your custom flows. + * + * @example + * const { result } = await createApiKeysWorkflow(container) + * .run({ + * input: { + * api_keys: [ + * { + * type: "publishable", + * title: "Storefront", + * created_by: "user_123" + * } + * ] + * } + * }) + * + * @summary + * + * Create secret or publishable API keys. */ export const createApiKeysWorkflow = createWorkflow( createApiKeysWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(createApiKeysStep(input)) } ) diff --git a/packages/core/core-flows/src/api-key/workflows/delete-api-keys.ts b/packages/core/core-flows/src/api-key/workflows/delete-api-keys.ts index fdbd17b4ba..b333b60161 100644 --- a/packages/core/core-flows/src/api-key/workflows/delete-api-keys.ts +++ b/packages/core/core-flows/src/api-key/workflows/delete-api-keys.ts @@ -3,11 +3,35 @@ import { removeRemoteLinkStep } from "../../common/steps/remove-remote-links" import { deleteApiKeysStep } from "../steps" import { Modules } from "@medusajs/framework/utils" -export type DeleteApiKeysWorkflowInput = { ids: string[] } +/** + * The data to delete API keys. + */ +export type DeleteApiKeysWorkflowInput = { + /** + * The IDs of the API keys to delete. + */ + ids: string[] +} export const deleteApiKeysWorkflowId = "delete-api-keys" /** - * This workflow deletes one or more API keys. + * This workflow deletes one or more secret or publishable API keys. It's used by the + * [Delete API Key Admin API Route](https://docs.medusajs.com/api/admin#api-keys_deleteapikeysid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete API keys within your custom flows. + * + * @example + * const { result } = await deleteApiKeysWorkflow(container) + * .run({ + * input: { + * ids: ["apk_123"] + * } + * }) + * + * @summary + * + * Delete secret or publishable API keys. */ export const deleteApiKeysWorkflow = createWorkflow( deleteApiKeysWorkflowId, diff --git a/packages/core/core-flows/src/api-key/workflows/link-sales-channels-to-publishable-key.ts b/packages/core/core-flows/src/api-key/workflows/link-sales-channels-to-publishable-key.ts index 761ec3feab..33ebaaee17 100644 --- a/packages/core/core-flows/src/api-key/workflows/link-sales-channels-to-publishable-key.ts +++ b/packages/core/core-flows/src/api-key/workflows/link-sales-channels-to-publishable-key.ts @@ -5,14 +5,37 @@ import { validateSalesChannelsExistStep, } from "../steps" +/** + * The data to manage the sales channels of a publishable API key. + * + * @property id - The ID of the publishable API key. + * @property add - The sales channel IDs to add to the publishable API key. + * @property remove - The sales channel IDs to remove from the publishable API key. + */ +export type LinkSalesChannelsToApiKeyWorkflowInput = LinkWorkflowInput + export const linkSalesChannelsToApiKeyWorkflowId = "link-sales-channels-to-api-key" /** - * This workflow links sales channels to API keys. + * This workflow manages the sales channels of a publishable API key. It's used by the + * [Manage Sales Channels API Route](https://docs.medusajs.com/api/admin#api-keys_postapikeysidsaleschannels). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * manage the sales channels of a publishable API key within your custom flows. + * + * @example + * const { result } = await linkSalesChannelsToApiKeyWorkflow(container) + * .run({ + * input: { + * id: "apk_132", + * add: ["sc_123"], + * remove: ["sc_321"] + * } + * }) */ export const linkSalesChannelsToApiKeyWorkflow = createWorkflow( linkSalesChannelsToApiKeyWorkflowId, - (input: WorkflowData) => { + (input: WorkflowData) => { validateSalesChannelsExistStep({ sales_channel_ids: input.add ?? [], }) diff --git a/packages/core/core-flows/src/api-key/workflows/revoke-api-keys.ts b/packages/core/core-flows/src/api-key/workflows/revoke-api-keys.ts index d323b1d021..f05dc17ef3 100644 --- a/packages/core/core-flows/src/api-key/workflows/revoke-api-keys.ts +++ b/packages/core/core-flows/src/api-key/workflows/revoke-api-keys.ts @@ -10,20 +10,57 @@ import { } from "@medusajs/framework/workflows-sdk" import { revokeApiKeysStep } from "../steps" +/** + * The data to revoke API keys. + */ export type RevokeApiKeysWorkflowInput = { + /** + * The filters to select the API keys to revoke. + */ selector: FilterableApiKeyProps + /** + * The data to revoke the API keys. + */ revoke: RevokeApiKeyDTO } +/** + * The revoked API keys. + */ +export type RevokeApiKeysWorkflowOutput = ApiKeyDTO[] + export const revokeApiKeysWorkflowId = "revoke-api-keys" /** - * This workflow revokes one or more API keys. + * This workflow revokes one or more API keys. If the API key is a secret, + * it can't be used for authentication anymore. If it's publishable, it can't be used by client applications. + * + * This workflow is used by the [Revoke API Key API Route](https://docs.medusajs.com/api/admin#api-keys_postapikeysidrevoke). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * revoke API keys within your custom flows. + * + * @example + * const { result } = await revokeApiKeysWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "apk_123" + * }, + * revoke: { + * revoked_by: "user_123" + * } + * } + * }) + * + * @summary + * + * Revoke secret or publishable API keys. */ export const revokeApiKeysWorkflow = createWorkflow( revokeApiKeysWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(revokeApiKeysStep(input)) } ) diff --git a/packages/core/core-flows/src/api-key/workflows/update-api-keys.ts b/packages/core/core-flows/src/api-key/workflows/update-api-keys.ts index d465c4d72d..890765ac4b 100644 --- a/packages/core/core-flows/src/api-key/workflows/update-api-keys.ts +++ b/packages/core/core-flows/src/api-key/workflows/update-api-keys.ts @@ -10,20 +10,55 @@ import { } from "@medusajs/framework/workflows-sdk" import { updateApiKeysStep } from "../steps" +/** + * The data to update API keys. + */ export type UpdateApiKeysWorkflowInput = { + /** + * The filters to select the API keys to update. + */ selector: FilterableApiKeyProps + /** + * The data to update the API keys. + */ update: UpdateApiKeyDTO } +/** + * The updated API keys. + */ +export type UpdateApiKeysWorkflowOutput = ApiKeyDTO[] + export const updateApiKeysWorkflowId = "update-api-keys" /** - * This workflow creates one or more API keys. + * This workflow updates one or more secret or publishable API keys. It's used by the + * [Update API Key Admin API Route](https://docs.medusajs.com/api/admin#api-keys_postapikeysid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * update API keys within your custom flows. + * + * @example + * const { result } = await updateApiKeysWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "apk_123" + * }, + * update: { + * title: "Storefront" + * } + * } + * }) + * + * @summary + * + * Update secret or publishable API keys. */ export const updateApiKeysWorkflow = createWorkflow( updateApiKeysWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateApiKeysStep(input)) } ) diff --git a/packages/core/core-flows/src/common/steps/create-remote-links.ts b/packages/core/core-flows/src/common/steps/create-remote-links.ts index e7e4bfba26..52dfe012de 100644 --- a/packages/core/core-flows/src/common/steps/create-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/create-remote-links.ts @@ -10,29 +10,14 @@ export const createLinksStepId = "create-remote-links" * Learn more in the [Remote Link documentation.](https://docs.medusajs.com/learn/fundamentals/module-links/remote-link#create-link). * * @example - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * createRemoteLinkStep - * } from "@medusajs/medusa/core-flows" - * import { - * Modules - * } from "@medusajs/framework/utils" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * createRemoteLinkStep([{ - * [Modules.PRODUCT]: { - * product_id: "prod_123", - * }, - * "helloModuleService": { - * my_custom_id: "mc_123", - * }, - * }]) - * } - * ) + * createRemoteLinkStep([{ + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * }]) */ export const createRemoteLinkStep = createStep( createLinksStepId, diff --git a/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts b/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts index c19b8add0e..2fbfa4ae3a 100644 --- a/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts @@ -14,29 +14,14 @@ export const dismissRemoteLinkStepId = "dismiss-remote-links" * Learn more in the [Remote Link documentation.](https://docs.medusajs.com/learn/fundamentals/module-links/remote-link#dismiss-link). * * @example - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * dismissRemoteLinkStep - * } from "@medusajs/medusa/core-flows" - * import { - * Modules - * } from "@medusajs/framework/utils" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * dismissRemoteLinkStep([{ - * [Modules.PRODUCT]: { - * product_id: "prod_123", - * }, - * "helloModuleService": { - * my_custom_id: "mc_123", - * }, - * }]) - * } - * ) + * dismissRemoteLinkStep([{ + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * }]) */ export const dismissRemoteLinkStep = createStep( dismissRemoteLinkStepId, diff --git a/packages/core/core-flows/src/common/steps/emit-event.ts b/packages/core/core-flows/src/common/steps/emit-event.ts index 63448568eb..8f4571c7dd 100644 --- a/packages/core/core-flows/src/common/steps/emit-event.ts +++ b/packages/core/core-flows/src/common/steps/emit-event.ts @@ -41,24 +41,12 @@ export const emitEventStepId = "emit-event-step" * Emit an event. * * @example - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * emitEventStep - * } from "@medusajs/medusa/core-flows" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * emitEventStep({ - * eventName: "custom.created", - * data: { - * id: "123" - * } - * }) + * emitEventStep({ + * eventName: "custom.created", + * data: { + * id: "123" * } - * ) + * }) */ export const emitEventStep = createStep( emitEventStepId, diff --git a/packages/core/core-flows/src/common/steps/remove-remote-links.ts b/packages/core/core-flows/src/common/steps/remove-remote-links.ts index 1482ad735f..b191f79b2e 100644 --- a/packages/core/core-flows/src/common/steps/remove-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/remove-remote-links.ts @@ -12,26 +12,11 @@ export const removeRemoteLinkStepId = "remove-remote-links" * Learn more in the [Remote Link documentation](https://docs.medusajs.com/learn/fundamentals/module-links/remote-link#cascade-delete-linked-records) * * @example - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * removeRemoteLinkStep - * } from "@medusajs/medusa/core-flows" - * import { - * Modules - * } from "@medusajs/framework/utils" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * removeRemoteLinkStep([{ - * [Modules.PRODUCT]: { - * product_id: "prod_123", - * }, - * }]) - * } - * ) + * removeRemoteLinkStep([{ + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * }]) */ export const removeRemoteLinkStep = createStep( removeRemoteLinkStepId, diff --git a/packages/core/core-flows/src/common/steps/update-remote-links.ts b/packages/core/core-flows/src/common/steps/update-remote-links.ts index a59b13861e..10286a2af3 100644 --- a/packages/core/core-flows/src/common/steps/update-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/update-remote-links.ts @@ -7,6 +7,28 @@ import { import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const updateRemoteLinksStepId = "update-remote-links-step" +/** + * This step updates remote links between two records of linked data models. + * + * Learn more in the [Remote Link documentation.](https://docs.medusajs.com/learn/fundamentals/module-links/remote-link#create-link). + * + * @example + * const data = updateRemoteLinksStep([ + * { + * [Modules.PRODUCT]: { + * product_id: "prod_321", + * }, + * "helloModuleService": { + * my_custom_id: "mc_321", + * }, + * data: { + * metadata: { + * test: false + * } + * } + * } + * ]) + */ export const updateRemoteLinksStep = createStep( updateRemoteLinksStepId, async (data: LinkDefinition[], { container }) => { diff --git a/packages/core/core-flows/src/common/steps/use-query-graph.ts b/packages/core/core-flows/src/common/steps/use-query-graph.ts index 109a5a9837..6324d755b9 100644 --- a/packages/core/core-flows/src/common/steps/use-query-graph.ts +++ b/packages/core/core-flows/src/common/steps/use-query-graph.ts @@ -35,25 +35,13 @@ const step = createStep( * To retrieve a list of records of a data model: * * ```ts - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * useQueryGraphStep - * } from "@medusajs/medusa/core-flows" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * const { data: products } = useQueryGraphStep({ - * entity: "product", - * fields: [ - * "*", - * "variants.*" - * ] - * }) - * } - * ) + * const { data: products } = useQueryGraphStep({ + * entity: "product", + * fields: [ + * "*", + * "variants.*" + * ] + * }) * ``` * * To retrieve a single item instead of a an array: diff --git a/packages/core/core-flows/src/common/steps/use-remote-query.ts b/packages/core/core-flows/src/common/steps/use-remote-query.ts index 6392745c31..9db9c09781 100644 --- a/packages/core/core-flows/src/common/steps/use-remote-query.ts +++ b/packages/core/core-flows/src/common/steps/use-remote-query.ts @@ -63,86 +63,50 @@ export const useRemoteQueryStepId = "use-remote-query" * To retrieve a list of records of a data model: * * ```ts - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * useRemoteQueryStep - * } from "@medusajs/medusa/core-flows" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * const products = useRemoteQueryStep({ - * entry_point: "product", - * fields: [ - * "*", - * "variants.*" - * ] - * }) - * } - * ) + * const products = useRemoteQueryStep({ + * entry_point: "product", + * fields: [ + * "*", + * "variants.*" + * ] + * }) * ``` * * To retrieve a single item instead of a an array: * * ```ts - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * useRemoteQueryStep - * } from "@medusajs/core-flows" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * const product = useRemoteQueryStep({ - * entry_point: "product", - * fields: [ - * "*", - * "variants.*" - * ], - * variables: { - * filters: { - * id: "123" - * } - * }, - * list: false - * }) - * } - * ) + * const product = useRemoteQueryStep({ + * entry_point: "product", + * fields: [ + * "*", + * "variants.*" + * ], + * variables: { + * filters: { + * id: "123" + * } + * }, + * list: false + * }) * ``` * * To throw an error if a record isn't found matching the specified ID: * * ```ts - * import { - * createWorkflow - * } from "@medusajs/framework/workflows-sdk" - * import { - * useRemoteQueryStep - * } from "@medusajs/core-flows" - * - * const helloWorldWorkflow = createWorkflow( - * "hello-world", - * () => { - * const product = useRemoteQueryStep({ - * entry_point: "product", - * fields: [ - * "*", - * "variants.*" - * ], - * variables: { - * filters: { - * id: "123" - * } - * }, - * list: false, - * throw_if_key_not_found: true - * }) - * } - * ) + * const product = useRemoteQueryStep({ + * entry_point: "product", + * fields: [ + * "*", + * "variants.*" + * ], + * variables: { + * filters: { + * id: "123" + * } + * }, + * list: false, + * throw_if_key_not_found: true + * }) * ``` */ export const useRemoteQueryStep = createStep( diff --git a/packages/core/core-flows/src/common/workflows/batch-links.ts b/packages/core/core-flows/src/common/workflows/batch-links.ts index 08df027b55..d2ba3b8b7e 100644 --- a/packages/core/core-flows/src/common/workflows/batch-links.ts +++ b/packages/core/core-flows/src/common/workflows/batch-links.ts @@ -12,6 +12,57 @@ import { updateRemoteLinksStep } from "../steps/update-remote-links" export const batchLinksWorkflowId = "batch-links" /** * This workflow manages one or more links to create, update, or dismiss them. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * manage links within your custom flows. + * + * Learn more about links in [this documentation](https://docs.medusajs.com/learn/fundamentals/module-links/link). + * + * @example + * const { result } = await batchLinksWorkflow(container) + * .run({ + * input: { + * create: [ + * { + * // import { Modules } from "@medusajs/framework/utils" + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * } + * ], + * update: [ + * { + * // import { Modules } from "@medusajs/framework/utils" + * [Modules.PRODUCT]: { + * product_id: "prod_321", + * }, + * "helloModuleService": { + * my_custom_id: "mc_321", + * }, + * data: { + * metadata: { + * test: false + * } + * } + * } + * ], + * delete: [ + * { + * // import { Modules } from "@medusajs/framework/utils" + * [Modules.PRODUCT]: { + * product_id: "prod_321", + * }, + * } + * ] + * } + * }) + * + * @summary + * + * Manage links between two records of linked data models. */ export const batchLinksWorkflow = createWorkflow( batchLinksWorkflowId, diff --git a/packages/core/core-flows/src/common/workflows/create-links.ts b/packages/core/core-flows/src/common/workflows/create-links.ts index f63e8189c1..d7a465992e 100644 --- a/packages/core/core-flows/src/common/workflows/create-links.ts +++ b/packages/core/core-flows/src/common/workflows/create-links.ts @@ -9,6 +9,31 @@ import { createRemoteLinkStep } from "../steps/create-remote-links" export const createLinksWorkflowId = "create-link" /** * This workflow creates one or more links between records. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create links within your custom flows. + * + * Learn more about links in [this documentation](https://docs.medusajs.com/learn/fundamentals/module-links/link). + * + * @example + * const { result } = await createLinksWorkflow(container) + * .run({ + * input: [ + * { + * // import { Modules } from "@medusajs/framework/utils" + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * } + * ] + * }) + * + * @summary + * + * Create links between two records of linked data models. */ export const createLinksWorkflow = createWorkflow( createLinksWorkflowId, diff --git a/packages/core/core-flows/src/common/workflows/dismiss-links.ts b/packages/core/core-flows/src/common/workflows/dismiss-links.ts index b16f0fc678..58f2e5a79e 100644 --- a/packages/core/core-flows/src/common/workflows/dismiss-links.ts +++ b/packages/core/core-flows/src/common/workflows/dismiss-links.ts @@ -9,6 +9,31 @@ import { dismissRemoteLinkStep } from "../steps/dismiss-remote-links" export const dismissLinksWorkflowId = "dismiss-link" /** * This workflow dismisses one or more links between records. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * dismiss links within your custom flows. + * + * Learn more about links in [this documentation](https://docs.medusajs.com/learn/fundamentals/module-links/link). + * + * @example + * const { result } = await dismissLinksWorkflow(container) + * .run({ + * input: [ + * { + * // import { Modules } from "@medusajs/framework/utils" + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * } + * ] + * }) + * + * @summary + * + * Dismiss links between two records of linked data models. */ export const dismissLinksWorkflow = createWorkflow( dismissLinksWorkflowId, diff --git a/packages/core/core-flows/src/common/workflows/update-links.ts b/packages/core/core-flows/src/common/workflows/update-links.ts index 96aa6532d5..787d9d71e2 100644 --- a/packages/core/core-flows/src/common/workflows/update-links.ts +++ b/packages/core/core-flows/src/common/workflows/update-links.ts @@ -9,6 +9,36 @@ import { updateRemoteLinksStep } from "../steps/update-remote-links" export const updateLinksWorkflowId = "update-link" /** * This workflow updates one or more links between records. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * update links within your custom flows. + * + * Learn more about links in [this documentation](https://docs.medusajs.com/learn/fundamentals/module-links/link). + * + * @example + * const { result } = await updateLinksWorkflow(container) + * .run({ + * input: [ + * { + * // import { Modules } from "@medusajs/framework/utils" + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * data: { + * metadata: { + * test: false, + * }, + * } + * } + * ] + * }) + * + * @summary + * + * Update links between two records of linked data models. */ export const updateLinksWorkflow = createWorkflow( updateLinksWorkflowId, diff --git a/packages/core/core-flows/src/defaults/steps/create-default-store.ts b/packages/core/core-flows/src/defaults/steps/create-default-store.ts index a8f8a42246..ca957f72e5 100644 --- a/packages/core/core-flows/src/defaults/steps/create-default-store.ts +++ b/packages/core/core-flows/src/defaults/steps/create-default-store.ts @@ -7,13 +7,33 @@ import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { createStoresWorkflow } from "../../store" +/** + * The data to create a default store. + */ type CreateDefaultStoreStepInput = { + /** + * The store to create. + */ store: CreateStoreDTO } export const createDefaultStoreStepId = "create-default-store" /** - * This step creates a default store. + * This step creates a default store. Useful if creating a workflow + * that seeds data into Medusa. + * + * @example + * const data = createDefaultStoreStep({ + * store: { + * name: "Acme", + * supported_currencies: [ + * { + * currency_code: "usd", + * is_default: true + * } + * ], + * } + * }) */ export const createDefaultStoreStep = createStep( createDefaultStoreStepId, diff --git a/packages/core/core-flows/src/defaults/workflows/create-defaults.ts b/packages/core/core-flows/src/defaults/workflows/create-defaults.ts index 8f103fc4c4..8103ac84a6 100644 --- a/packages/core/core-flows/src/defaults/workflows/create-defaults.ts +++ b/packages/core/core-flows/src/defaults/workflows/create-defaults.ts @@ -7,7 +7,20 @@ import { createDefaultStoreStep } from "../steps/create-default-store" export const createDefaultsWorkflowID = "create-defaults" /** - * This workflow creates default data for a Medusa application. + * This workflow creates default data for a Medusa application, including + * a default sales channel and store. The Medusa application uses this workflow + * to create the default data, if not existing, when the application is first started. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create default data within your custom flows, such as seed scripts. + * + * @example + * const { result } = await createDefaultsWorkflow(container) + * .run() + * + * @summary + * + * Create default data for a Medusa application. */ export const createDefaultsWorkflow = createWorkflow( createDefaultsWorkflowID, diff --git a/packages/core/core-flows/src/file/steps/delete-files.ts b/packages/core/core-flows/src/file/steps/delete-files.ts index 085540efdc..da4f1e31a2 100644 --- a/packages/core/core-flows/src/file/steps/delete-files.ts +++ b/packages/core/core-flows/src/file/steps/delete-files.ts @@ -2,13 +2,25 @@ import { IFileModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the files to delete. + */ +export type DeleteFilesStepInput = string[] + export const deleteFilesStepId = "delete-files" /** - * This step deletes one or more files. + * This step deletes one or more files using the installed + * [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file). The files + * will be removed from the database and the storage. + * + * @example + * const data = deleteFilesStep([ + * "id_123" + * ]) */ export const deleteFilesStep = createStep( { name: deleteFilesStepId, noCompensation: true }, - async (ids: string[], { container }) => { + async (ids: DeleteFilesStepInput, { container }) => { const service = container.resolve(Modules.FILE) await service.deleteFiles(ids) diff --git a/packages/core/core-flows/src/file/steps/upload-files.ts b/packages/core/core-flows/src/file/steps/upload-files.ts index 8730b47696..e290ee697e 100644 --- a/packages/core/core-flows/src/file/steps/upload-files.ts +++ b/packages/core/core-flows/src/file/steps/upload-files.ts @@ -2,18 +2,57 @@ import { IFileModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to upload files. + */ export type UploadFilesStepInput = { + /** + * The files to upload. + */ files: { + /** + * The name of the file. + */ filename: string + /** + * The MIME type of the file. + * + * @example + * img/jpg + */ mimeType: string + /** + * The content of the file. For images, for example, + * use base64 encoding. For CSV files, use the CSV content. + */ content: string + /** + * The access level of the file. Use `public` for the file that + * can be accessed by anyone. For example, for images that are displayed + * on the storefront. Use `private` for files that are only accessible + * by authenticated users. For example, for CSV files used to + * import data. + */ access: "public" | "private" }[] } export const uploadFilesStepId = "upload-files" /** - * This step uploads one or more files. + * This step uploads one or more files using the installed + * [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file). + * + * @example + * const data = uploadFilesStep({ + * files: [ + * { + * filename: "test.jpg", + * mimeType: "img/jpg", + * content: "base64Content", + * access: "public" + * } + * ] + * }) */ export const uploadFilesStep = createStep( uploadFilesStepId, diff --git a/packages/core/core-flows/src/file/workflows/delete-files.ts b/packages/core/core-flows/src/file/workflows/delete-files.ts index 2338b457e8..d78a73aba2 100644 --- a/packages/core/core-flows/src/file/workflows/delete-files.ts +++ b/packages/core/core-flows/src/file/workflows/delete-files.ts @@ -5,7 +5,26 @@ export type DeleteFilesWorkflowInput = { ids: string[] } export const deleteFilesWorkflowId = "delete-files" /** - * This workflow deletes one or more files. + * This workflow deletes one or more files. It's used by the + * [Delete File Upload Admin API Route](https://docs.medusajs.com/api/admin#uploads_deleteuploadsid). + * + * The [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file) installed + * in your application will be used to delete the file from storage. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete files within your custom flows. + * + * @example + * const { result } = await deleteFilesWorkflow(container) + * .run({ + * input: { + * ids: ["123"] + * } + * }) + * + * @summary + * + * Delete files from the database and storage. */ export const deleteFilesWorkflow = createWorkflow( deleteFilesWorkflowId, diff --git a/packages/core/core-flows/src/file/workflows/upload-files.ts b/packages/core/core-flows/src/file/workflows/upload-files.ts index 28ba0e567a..085d6081d8 100644 --- a/packages/core/core-flows/src/file/workflows/upload-files.ts +++ b/packages/core/core-flows/src/file/workflows/upload-files.ts @@ -6,18 +6,68 @@ import { } from "@medusajs/framework/workflows-sdk" import { uploadFilesStep } from "../steps" +/** + * The data to upload files. + */ export type UploadFilesWorkflowInput = { + /** + * The files to upload. + */ files: { + /** + * The name of the file. + */ filename: string + /** + * The MIME type of the file. + * + * @example + * img/jpg + */ mimeType: string + /** + * The content of the file. For images, for example, + * use base64 encoding. For CSV files, use the CSV content. + */ content: string + /** + * The access level of the file. Use `public` for the file that + * can be accessed by anyone. For example, for images that are displayed + * on the storefront. Use `private` for files that are only accessible + * by authenticated users. For example, for CSV files used to + * import data. + */ access: "public" | "private" }[] } export const uploadFilesWorkflowId = "upload-files" /** - * This workflow uploads one or more files. + * This workflow uploads one or more files using the installed + * [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file). The workflow is used by the + * [Upload Files Admin API Route](https://docs.medusajs.com/api/admin#uploads_postuploads). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * upload files within your custom flows. + * + * @example + * const { result } = await uploadFilesWorkflow(container) + * .run({ + * input: { + * files: [ + * { + * filename: "test.jpg", + * mimeType: "img/jpg", + * content: "base64Content", + * access: "public" + * } + * ] + * } + * }) + * + * @summary + * + * Upload files using the installed File Module Provider. */ export const uploadFilesWorkflow = createWorkflow( uploadFilesWorkflowId, diff --git a/packages/core/core-flows/src/index.ts b/packages/core/core-flows/src/index.ts index a6d6c5bcb0..91f8726db3 100644 --- a/packages/core/core-flows/src/index.ts +++ b/packages/core/core-flows/src/index.ts @@ -28,3 +28,4 @@ export * from "./stock-location" export * from "./store" export * from "./tax" export * from "./user" +export * from "./notification" \ No newline at end of file diff --git a/packages/core/core-flows/src/line-item/steps/delete-line-items.ts b/packages/core/core-flows/src/line-item/steps/delete-line-items.ts index 2126b4dfa8..757db26cb3 100644 --- a/packages/core/core-flows/src/line-item/steps/delete-line-items.ts +++ b/packages/core/core-flows/src/line-item/steps/delete-line-items.ts @@ -2,13 +2,18 @@ import { ICartModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the line items to delete. + */ +export type DeleteLineItemsStepInput = string[] + export const deleteLineItemsStepId = "delete-line-items" /** * This step deletes line items. */ export const deleteLineItemsStep = createStep( deleteLineItemsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteLineItemsStepInput, { container }) => { const service = container.resolve(Modules.CART) await service.softDeleteLineItems(ids) diff --git a/packages/core/core-flows/src/line-item/steps/list-line-items.ts b/packages/core/core-flows/src/line-item/steps/list-line-items.ts index b1e77ff7c2..a450c2b8f7 100644 --- a/packages/core/core-flows/src/line-item/steps/list-line-items.ts +++ b/packages/core/core-flows/src/line-item/steps/list-line-items.ts @@ -7,8 +7,20 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to list line items. + */ export interface ListLineItemsStepInput { + /** + * The filters to select the line items. + */ filters: FilterableLineItemProps + /** + * Configurations to select the line items' fields + * and relations, and to paginate the results. + * + * Learn more in the [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list). + */ config?: FindConfig } @@ -16,6 +28,37 @@ export const listLineItemsStepId = "list-line-items" /** * This step retrieves a list of a cart's line items * matching the specified filters. + * + * @example + * To retrieve the line items of a cart: + * + * ```ts + * const data = listLineItemsStep({ + * filters: { + * cart_id: "cart_123" + * }, + * config: { + * select: ["*"] + * } + * }) + * ``` + * + * To retrieve the line items of a cart with pagination: + * + * ```ts + * const data = listLineItemsStep({ + * filters: { + * cart_id: "cart_123" + * }, + * config: { + * select: ["*"], + * skip: 0, + * take: 15 + * } + * }) + * ``` + * + * Learn more about listing items in [this service factory reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list). */ export const listLineItemsStep = createStep( listLineItemsStepId, diff --git a/packages/core/core-flows/src/line-item/steps/update-line-items.ts b/packages/core/core-flows/src/line-item/steps/update-line-items.ts index 0209222075..73c0ee8550 100644 --- a/packages/core/core-flows/src/line-item/steps/update-line-items.ts +++ b/packages/core/core-flows/src/line-item/steps/update-line-items.ts @@ -14,6 +14,16 @@ export const updateLineItemsStepWithSelectorId = "update-line-items-with-selector" /** * This step updates line items. + * + * @example + * const data = updateLineItemsStepWithSelector({ + * selector: { + * cart_id: "cart_123" + * }, + * data: { + * quantity: 1 + * } + * }) */ export const updateLineItemsStepWithSelector = createStep( updateLineItemsStepWithSelectorId, diff --git a/packages/core/core-flows/src/line-item/workflows/delete-line-items.ts b/packages/core/core-flows/src/line-item/workflows/delete-line-items.ts index d20d36dfaa..c749a4a43f 100644 --- a/packages/core/core-flows/src/line-item/workflows/delete-line-items.ts +++ b/packages/core/core-flows/src/line-item/workflows/delete-line-items.ts @@ -2,11 +2,40 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { refreshCartItemsWorkflow } from "../../cart/workflows/refresh-cart-items" import { deleteLineItemsStep } from "../steps/delete-line-items" -export type DeleteLineItemsWorkflowInput = { cart_id: string; ids: string[] } +/** + * The data to delete line items from a cart. + */ +export type DeleteLineItemsWorkflowInput = { + /** + * The cart's ID. + */ + cart_id: string + /** + * The IDs of the line items to delete. + */ + ids: string[] +} export const deleteLineItemsWorkflowId = "delete-line-items" /** - * This workflow deletes line items from a cart. + * This workflow deletes line items from a cart. It's used by the + * [Delete Line Item Store API Route](https://docs.medusajs.com/api/store#carts_deletecartsidlineitemsline_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete line items from a cart within your custom flows. + * + * @example + * const { result } = await deleteLineItemsWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * ids: ["li_123"] + * } + * }) + * + * @summary + * + * Delete line items from a cart. */ export const deleteLineItemsWorkflow = createWorkflow( deleteLineItemsWorkflowId, diff --git a/packages/core/core-flows/src/notification/steps/notify-on-failure.ts b/packages/core/core-flows/src/notification/steps/notify-on-failure.ts index a1b262a02e..e760425985 100644 --- a/packages/core/core-flows/src/notification/steps/notify-on-failure.ts +++ b/packages/core/core-flows/src/notification/steps/notify-on-failure.ts @@ -2,24 +2,74 @@ import { INotificationModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The notifications to send. + */ export type NotifyOnFailureStepInput = { + /** + * The address to send the notification to, depending on + * the channel. For example, the email address for the email channel. + */ to: string + /** + * The channel to send the notification through. For example, `email`. + * A [Notification Module Provider](https://docs.medusajs.com/resources/architectural-modules/notification) + * must be installed and configured for the specified channel. + */ channel: string + /** + * The ID of the template to use for the notification. This template ID may be defined + * in a third-party service used to send the notification. + */ template: string + /** + * The data to use in the notification template. This data may be used to personalize + * the notification, such as the user's name or the order number. + */ data?: Record | null + /** + * The type of trigger that caused the notification to be sent. For example, `order_created`. + */ trigger_type?: string | null + /** + * The ID of the resource that triggered the notification. For example, the ID of the order + * that triggered the notification. + */ resource_id?: string | null + /** + * The type of the resource that triggered the notification. For example, `order`. + */ resource_type?: string | null + /** + * The ID of the user receiving the notification. + */ receiver_id?: string | null + /** + * The ID of the original notification if it's being resent. + */ original_notification_id?: string | null + /** + * A key to ensure that the notification is sent only once. If the notification + * is sent multiple times, the key ensures that the notification is sent only once. + */ idempotency_key?: string | null }[] export const notifyOnFailureStepId = "notify-on-failure" /** * This step sends one or more notification when a workflow fails. This - * step can be used in a workflow for its compensation function. When the workflow fails, - * its compensation function is triggered to send the notification. + * step can be used in the beginning of a workflow so that, when the workflow fails, + * the step's compensation function is triggered to send the notification. + * + * @example + * const data = notifyOnFailureStep([{ + * to: "example@gmail.com", + * channel: "email", + * template: "order-failed", + * data: { + * order_id: "order_123", + * } + * }]) */ export const notifyOnFailureStep = createStep( notifyOnFailureStepId, diff --git a/packages/core/core-flows/src/notification/steps/send-notifications.ts b/packages/core/core-flows/src/notification/steps/send-notifications.ts index aea9ee4343..cfc824f4f5 100644 --- a/packages/core/core-flows/src/notification/steps/send-notifications.ts +++ b/packages/core/core-flows/src/notification/steps/send-notifications.ts @@ -2,16 +2,54 @@ import { INotificationModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The notifications to send. + */ export type SendNotificationsStepInput = { + /** + * The address to send the notification to, depending on + * the channel. For example, the email address for the email channel. + */ to: string + /** + * The channel to send the notification through. For example, `email`. + */ channel: string + /** + * The ID of the template to use for the notification. This template ID may be defined + * in a third-party service used to send the notification. + */ template: string + /** + * The data to use in the notification template. This data may be used to personalize + * the notification, such as the user's name or the order number. + */ data?: Record | null + /** + * The type of trigger that caused the notification to be sent. For example, `order_created`. + */ trigger_type?: string | null + /** + * The ID of the resource that triggered the notification. For example, the ID of the order + * that triggered the notification. + */ resource_id?: string | null + /** + * The type of the resource that triggered the notification. For example, `order`. + */ resource_type?: string | null + /** + * The ID of the user receiving the notification. + */ receiver_id?: string | null + /** + * The ID of the original notification if it's being resent. + */ original_notification_id?: string | null + /** + * A key to ensure that the notification is sent only once. If the notification + * is sent multiple times, the key ensures that the notification is sent only once. + */ idempotency_key?: string | null }[] diff --git a/packages/core/core-flows/src/product-category/steps/create-product-categories.ts b/packages/core/core-flows/src/product-category/steps/create-product-categories.ts index 141c0ed696..18cdad3081 100644 --- a/packages/core/core-flows/src/product-category/steps/create-product-categories.ts +++ b/packages/core/core-flows/src/product-category/steps/create-product-categories.ts @@ -5,13 +5,28 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create product categories. + */ export type CreateProductCategoriesStepInput = { + /** + * The product categories to create. + */ product_categories: CreateProductCategoryDTO[] } export const createProductCategoriesStepId = "create-product-categories" /** * This step creates one or more product categories. + * + * @example + * const data = createProductCategoriesStep({ + * product_categories: [ + * { + * name: "Shoes", + * } + * ] + * }) */ export const createProductCategoriesStep = createStep( createProductCategoriesStepId, diff --git a/packages/core/core-flows/src/product-category/steps/delete-product-categories.ts b/packages/core/core-flows/src/product-category/steps/delete-product-categories.ts index 86d03fc292..9dce718f69 100644 --- a/packages/core/core-flows/src/product-category/steps/delete-product-categories.ts +++ b/packages/core/core-flows/src/product-category/steps/delete-product-categories.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the product categories to delete. + */ +export type DeleteProductCategoriesStepInput = string[] + export const deleteProductCategoriesStepId = "delete-product-categories" /** * This step deletes one or more product categories. */ export const deleteProductCategoriesStep = createStep( deleteProductCategoriesStepId, - async (ids: string[], { container }) => { + async (ids: DeleteProductCategoriesStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProductCategories(ids) diff --git a/packages/core/core-flows/src/product-category/steps/update-product-categories.ts b/packages/core/core-flows/src/product-category/steps/update-product-categories.ts index 61369a02ec..72e671e45c 100644 --- a/packages/core/core-flows/src/product-category/steps/update-product-categories.ts +++ b/packages/core/core-flows/src/product-category/steps/update-product-categories.ts @@ -9,14 +9,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update the product categories. + */ export type UpdateProductCategoriesStepInput = { + /** + * The filters to select the product categories to update. + */ selector: FilterableProductCategoryProps + /** + * The data to update in the product categories. + */ update: UpdateProductCategoryDTO } export const updateProductCategoriesStepId = "update-product-categories" /** * This step updates product categories matching specified filters. + * + * @example + * const data = updateProductCategoriesStep({ + * selector: { + * id: "pcat_123", + * }, + * update: { + * name: "Shoes", + * } + * }) */ export const updateProductCategoriesStep = createStep( updateProductCategoriesStepId, diff --git a/packages/core/core-flows/src/product-category/workflows/create-product-categories.ts b/packages/core/core-flows/src/product-category/workflows/create-product-categories.ts index 0feb66d107..42fe507116 100644 --- a/packages/core/core-flows/src/product-category/workflows/create-product-categories.ts +++ b/packages/core/core-flows/src/product-category/workflows/create-product-categories.ts @@ -1,4 +1,4 @@ -import { ProductCategoryWorkflow } from "@medusajs/framework/types" +import { ProductCategoryDTO, ProductCategoryWorkflow } from "@medusajs/framework/types" import { ProductCategoryWorkflowEvents } from "@medusajs/framework/utils" import { WorkflowData, @@ -9,15 +9,40 @@ import { import { emitEventStep } from "../../common" import { createProductCategoriesStep } from "../steps" +/** + * The created product categories. + */ +export type CreateProductCategoriesWorkflowOutput = ProductCategoryDTO[] + export const createProductCategoriesWorkflowId = "create-product-categories" /** - * This workflow creates one or more product categories. + * This workflow creates one or more product categories. It's used by the + * [Create Product Category Admin API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategories). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create product categories within your custom flows. + * + * @example + * const { result } = await createProductCategoriesWorkflow(container) + * .run({ + * input: { + * product_categories: [ + * { + * name: "Shoes", + * } + * ] + * } + * }) + * + * @summary + * + * Create product categories. */ export const createProductCategoriesWorkflow = createWorkflow( createProductCategoriesWorkflowId, ( input: WorkflowData - ) => { + ): WorkflowResponse => { const createdProducts = createProductCategoriesStep(input) const productCategoryIdEvents = transform( diff --git a/packages/core/core-flows/src/product-category/workflows/delete-product-categories.ts b/packages/core/core-flows/src/product-category/workflows/delete-product-categories.ts index 1be6f378c5..d29c0e3dc4 100644 --- a/packages/core/core-flows/src/product-category/workflows/delete-product-categories.ts +++ b/packages/core/core-flows/src/product-category/workflows/delete-product-categories.ts @@ -8,13 +8,32 @@ import { import { emitEventStep } from "../../common" import { deleteProductCategoriesStep } from "../steps" +/** + * The IDs of product categories to delete. + */ +export type DeleteProductCategoriesWorkflowInput = string[] + export const deleteProductCategoriesWorkflowId = "delete-product-categories" /** - * This workflow deletes one or more product categories. + * This workflow deletes one or more product categories. It's used by the + * [Delete Product Category Admin API Route](https://docs.medusajs.com/api/admin#product-categories_deleteproductcategoriesid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete product categories within your custom flows. + * + * @example + * const { result } = await deleteProductCategoriesWorkflow(container) + * .run({ + * input: ["pcat_123"] + * }) + * + * @summary + * + * Delete product categories. */ export const deleteProductCategoriesWorkflow = createWorkflow( deleteProductCategoriesWorkflowId, - (input: WorkflowData) => { + (input: WorkflowData) => { const deleted = deleteProductCategoriesStep(input) const productCategoryIdEvents = transform({ input }, ({ input }) => { diff --git a/packages/core/core-flows/src/product-category/workflows/update-product-categories.ts b/packages/core/core-flows/src/product-category/workflows/update-product-categories.ts index 2d445f47c9..f99ed0019e 100644 --- a/packages/core/core-flows/src/product-category/workflows/update-product-categories.ts +++ b/packages/core/core-flows/src/product-category/workflows/update-product-categories.ts @@ -1,4 +1,4 @@ -import { ProductCategoryWorkflow } from "@medusajs/framework/types" +import { ProductCategoryDTO, ProductCategoryWorkflow } from "@medusajs/framework/types" import { ProductCategoryWorkflowEvents } from "@medusajs/framework/utils" import { WorkflowData, @@ -9,15 +9,41 @@ import { import { emitEventStep } from "../../common" import { updateProductCategoriesStep } from "../steps" +/** + * The updated product categories. + */ +export type UpdateProductCategoriesWorkflowOutput = ProductCategoryDTO[] + export const updateProductCategoriesWorkflowId = "update-product-categories" /** - * This workflow updates product categories matching specified filters. + * This workflow updates product categories matching specified filters. It's used by the + * [Update Product Category Admin API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriesid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * update product categories within your custom flows. + * + * @example + * const { result } = await updateProductCategoriesWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "pcat_123", + * }, + * update: { + * name: "Shoes", + * } + * } + * }) + * + * @summary + * + * Update product categories. */ export const updateProductCategoriesWorkflow = createWorkflow( updateProductCategoriesWorkflowId, ( input: WorkflowData - ) => { + ): WorkflowResponse => { const updatedCategories = updateProductCategoriesStep(input) const productCategoryIdEvents = transform( diff --git a/packages/core/core-flows/src/return-reason/steps/create-return-reasons.ts b/packages/core/core-flows/src/return-reason/steps/create-return-reasons.ts index 75763bc415..ed3488df4e 100644 --- a/packages/core/core-flows/src/return-reason/steps/create-return-reasons.ts +++ b/packages/core/core-flows/src/return-reason/steps/create-return-reasons.ts @@ -8,6 +8,14 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createReturnReasonsStepId = "create-return-reasons" /** * This step creates one or more return reasons. + * + * @example + * const data = createReturnReasonsStep([ + * { + * label: "Damaged", + * value: "damaged", + * } + * ]) */ export const createReturnReasonsStep = createStep( createReturnReasonsStepId, diff --git a/packages/core/core-flows/src/return-reason/steps/delete-return-reasons.ts b/packages/core/core-flows/src/return-reason/steps/delete-return-reasons.ts index 4320037d37..a0d6858442 100644 --- a/packages/core/core-flows/src/return-reason/steps/delete-return-reasons.ts +++ b/packages/core/core-flows/src/return-reason/steps/delete-return-reasons.ts @@ -2,13 +2,21 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the return reasons to delete. + */ +export type DeleteReturnReasonStepInput = string[] + export const deleteReturnReasonStepId = "delete-return-reasons" /** * This step deletes one or more return reasons. + * + * @example + * const data = deleteReturnReasonStep(["rr_123"]) */ export const deleteReturnReasonStep = createStep( deleteReturnReasonStepId, - async (ids: string[], { container }) => { + async (ids: DeleteReturnReasonStepInput, { container }) => { const service = container.resolve(Modules.ORDER) await service.softDeleteReturnReasons(ids) diff --git a/packages/core/core-flows/src/return-reason/steps/update-return-reasons.ts b/packages/core/core-flows/src/return-reason/steps/update-return-reasons.ts index fd717e8a1c..3cbb1488c1 100644 --- a/packages/core/core-flows/src/return-reason/steps/update-return-reasons.ts +++ b/packages/core/core-flows/src/return-reason/steps/update-return-reasons.ts @@ -10,14 +10,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update return reasons. + */ type UpdateReturnReasonStepInput = { + /** + * The filters to select the return reasons to update. + */ selector: FilterableOrderReturnReasonProps + /** + * The data to update in the return reasons. + */ update: ReturnReasonUpdatableFields } export const updateReturnReasonStepId = "update-return-reasons" /** * This step updates return reasons matching the specified filters. + * + * @example + * const data = updateReturnReasonsStep({ + * selector: { + * id: "rr_123", + * }, + * update: { + * value: "damaged", + * } + * }) */ export const updateReturnReasonsStep = createStep( updateReturnReasonStepId, diff --git a/packages/core/core-flows/src/return-reason/workflows/create-return-reasons.ts b/packages/core/core-flows/src/return-reason/workflows/create-return-reasons.ts index 627c9408e3..35a16f179b 100644 --- a/packages/core/core-flows/src/return-reason/workflows/create-return-reasons.ts +++ b/packages/core/core-flows/src/return-reason/workflows/create-return-reasons.ts @@ -9,19 +9,51 @@ import { } from "@medusajs/framework/workflows-sdk" import { createReturnReasonsStep } from "../steps" +/** + * The data to create return reasons. + */ export type CreateReturnReasonsWorkflowInput = { + /** + * The return reasons to create. + */ data: CreateOrderReturnReasonDTO[] } +/** + * The created return reasons. + */ +export type CreateReturnReasonsWorkflowOutput = OrderReturnReasonDTO[] + export const createReturnReasonsWorkflowId = "create-return-reasons" /** - * This workflow creates one or more return reasons. + * This workflow creates one or more return reasons. It's used by the + * [Create Return Reason Admin API Route](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasons). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create return reasons within your custom flows. + * + * @example + * const { result } = await createReturnReasonsWorkflow(container) + * .run({ + * input: { + * data: [ + * { + * label: "Damaged", + * value: "damaged", + * } + * ] + * } + * }) + * + * @summary + * + * Create return reasons. */ export const createReturnReasonsWorkflow = createWorkflow( createReturnReasonsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(createReturnReasonsStep(input.data)) } ) diff --git a/packages/core/core-flows/src/return-reason/workflows/delete-return-reasons.ts b/packages/core/core-flows/src/return-reason/workflows/delete-return-reasons.ts index e748a63551..e140cca2e3 100644 --- a/packages/core/core-flows/src/return-reason/workflows/delete-return-reasons.ts +++ b/packages/core/core-flows/src/return-reason/workflows/delete-return-reasons.ts @@ -1,11 +1,35 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { deleteReturnReasonStep } from "../steps" -export type DeleteReturnReasonsWorkflowInput = { ids: string[] } +/** + * The IDs of return reasons to delete. + */ +export type DeleteReturnReasonsWorkflowInput = { + /** + * The IDs of return reasons to delete. + */ + ids: string[] +} export const deleteReturnReasonsWorkflowId = "delete-return-reasons" /** - * This workflow deletes one or more return reasons. + * This workflow deletes one or more return reasons. It's used by the + * [Delete Return Reasons Admin API Route](https://docs.medusajs.com/api/admin#return-reasons_deletereturnreasonsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete return reasons within your custom flows. + * + * @example + * const { result } = await deleteReturnReasonsWorkflow(container) + * .run({ + * input: { + * ids: ["rr_123"] + * } + * }) + * + * @summary + * + * Delete return reasons. */ export const deleteReturnReasonsWorkflow = createWorkflow( deleteReturnReasonsWorkflowId, diff --git a/packages/core/core-flows/src/return-reason/workflows/update-return-reasons.ts b/packages/core/core-flows/src/return-reason/workflows/update-return-reasons.ts index 4e22f9233a..c33286d81f 100644 --- a/packages/core/core-flows/src/return-reason/workflows/update-return-reasons.ts +++ b/packages/core/core-flows/src/return-reason/workflows/update-return-reasons.ts @@ -10,20 +10,55 @@ import { } from "@medusajs/framework/workflows-sdk" import { updateReturnReasonsStep } from "../steps" +/** + * The data to update return reasons. + */ export type UpdateReturnReasonsWorkflowInput = { + /** + * The filters to select the return reasons to update. + */ selector: FilterableOrderReturnReasonProps + /** + * The data to update the return reasons. + */ update: ReturnReasonUpdatableFields } +/** + * The updated return reasons. + */ +export type UpdateReturnReasonsWorkflowOutput = OrderReturnReasonDTO[] + export const updateReturnReasonsWorkflowId = "update-return-reasons" /** - * This workflow updates return reasons matching the specified filters. + * This workflow updates return reasons matching the specified filters. It's used by the + * [Update Return Reason Admin API Route](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasonsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * update return reasons within your custom flows. + * + * @example + * const { result } = await updateReturnReasonsWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "rr_123", + * }, + * update: { + * value: "damaged", + * } + * } + * }) + * + * @summary + * + * Update return reasons. */ export const updateReturnReasonsWorkflow = createWorkflow( updateReturnReasonsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateReturnReasonsStep(input)) } ) diff --git a/packages/core/core-flows/src/sales-channel/steps/associate-locations-with-channels.ts b/packages/core/core-flows/src/sales-channel/steps/associate-locations-with-channels.ts index 56e0fc9d27..2889b5615c 100644 --- a/packages/core/core-flows/src/sales-channel/steps/associate-locations-with-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/associate-locations-with-channels.ts @@ -2,9 +2,21 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" +/** + * The data to associate locations with sales channels. + */ export interface AssociateLocationsWithSalesChannelsStepInput { + /** + * The links to create between locations and sales channels. + */ links: { + /** + * The ID of the sales channel. + */ sales_channel_id: string + /** + * The ID of the location. + */ location_id: string }[] } @@ -12,7 +24,17 @@ export interface AssociateLocationsWithSalesChannelsStepInput { export const associateLocationsWithSalesChannelsStepId = "associate-locations-with-sales-channels-step" /** - * This step creates links between locations and sales channel records. + * This step creates links between stock locations and sales channel records. + * + * @example + * const data = associateLocationsWithSalesChannelsStep({ + * links: [ + * { + * sales_channel_id: "sc_123", + * location_id: "sloc_123" + * } + * ] + * }) */ export const associateLocationsWithSalesChannelsStep = createStep( associateLocationsWithSalesChannelsStepId, diff --git a/packages/core/core-flows/src/sales-channel/steps/associate-products-with-channels.ts b/packages/core/core-flows/src/sales-channel/steps/associate-products-with-channels.ts index a1d3c6f970..70b2365371 100644 --- a/packages/core/core-flows/src/sales-channel/steps/associate-products-with-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/associate-products-with-channels.ts @@ -1,9 +1,21 @@ import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to associate products with sales channels. + */ export interface AssociateProductsWithSalesChannelsStepInput { + /** + * The links to create between products and sales channels. + */ links: { + /** + * The ID of the sales channel. + */ sales_channel_id: string + /** + * The ID of the product. + */ product_id: string }[] } @@ -12,6 +24,16 @@ export const associateProductsWithSalesChannelsStepId = "associate-products-with-channels" /** * This step creates links between products and sales channel records. + * + * @example + * const data = associateProductsWithSalesChannelsStep({ + * links: [ + * { + * sales_channel_id: "sc_123", + * product_id: "prod_123" + * } + * ] + * }) */ export const associateProductsWithSalesChannelsStep = createStep( associateProductsWithSalesChannelsStepId, diff --git a/packages/core/core-flows/src/sales-channel/steps/can-delete-sales-channels.ts b/packages/core/core-flows/src/sales-channel/steps/can-delete-sales-channels.ts index 1ea082d1f0..a60587bc0d 100644 --- a/packages/core/core-flows/src/sales-channel/steps/can-delete-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/can-delete-sales-channels.ts @@ -1,12 +1,32 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" - import { MedusaError, Modules } from "@medusajs/framework/utils" + +/** + * The data to validate if sales channels can be deleted. + */ +export type CanDeleteSalesChannelsOrThrowStepInput = { + /** + * The IDs of the sales channels to validate. + */ + ids: string | string[] +} + export const canDeleteSalesChannelsOrThrowStepId = "can-delete-sales-channels-or-throw-step" +/** + * This step validates that the specified sales channels can be deleted. + * If any of the sales channels are default sales channels for a store, + * the step will throw an error. + * + * @example + * const data = canDeleteSalesChannelsOrThrowStep({ + * ids: ["sc_123"] + * }) + */ export const canDeleteSalesChannelsOrThrowStep = createStep( canDeleteSalesChannelsOrThrowStepId, - async ({ ids }: { ids: string | string[] }, { container }) => { + async ({ ids }: CanDeleteSalesChannelsOrThrowStepInput, { container }) => { const salesChannelIdsToDelete = Array.isArray(ids) ? ids : [ids] const storeModule = await container.resolve(Modules.STORE) diff --git a/packages/core/core-flows/src/sales-channel/steps/create-default-sales-channel.ts b/packages/core/core-flows/src/sales-channel/steps/create-default-sales-channel.ts index 094ae2430a..11232b8851 100644 --- a/packages/core/core-flows/src/sales-channel/steps/create-default-sales-channel.ts +++ b/packages/core/core-flows/src/sales-channel/steps/create-default-sales-channel.ts @@ -5,13 +5,27 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create a default sales channel. + */ export interface CreateDefaultSalesChannelStepInput { + /** + * The default sales channel data. + */ data: CreateSalesChannelDTO } export const createDefaultSalesChannelStepId = "create-default-sales-channel" /** - * This step creates a default sales channel. + * This step creates a default sales channel if none exist in the application. + * This is useful when creating seed scripts. + * + * @example + * const data = createDefaultSalesChannelStep({ + * data: { + * name: "Webshop", + * } + * }) */ export const createDefaultSalesChannelStep = createStep( createDefaultSalesChannelStepId, diff --git a/packages/core/core-flows/src/sales-channel/steps/create-sales-channels.ts b/packages/core/core-flows/src/sales-channel/steps/create-sales-channels.ts index e4e794d4d9..37b898867c 100644 --- a/packages/core/core-flows/src/sales-channel/steps/create-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/create-sales-channels.ts @@ -5,13 +5,26 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create sales channels. + */ export interface CreateSalesChannelsStepInput { + /** + * The sales channels to create. + */ data: CreateSalesChannelDTO[] } export const createSalesChannelsStepId = "create-sales-channels" /** * This step creates one or more sales channels. + * + * @example + * const data = createSalesChannelsStep({ + * data: [{ + * name: "Webshop", + * }] + * }) */ export const createSalesChannelsStep = createStep( createSalesChannelsStepId, diff --git a/packages/core/core-flows/src/sales-channel/steps/delete-sales-channels.ts b/packages/core/core-flows/src/sales-channel/steps/delete-sales-channels.ts index d0a5fb73a1..1073d2016b 100644 --- a/packages/core/core-flows/src/sales-channel/steps/delete-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/delete-sales-channels.ts @@ -2,13 +2,18 @@ import { ISalesChannelModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the sales channels to delete. + */ +export type DeleteSalesChannelsStepInput = string[] + export const deleteSalesChannelsStepId = "delete-sales-channels" /** * This step deletes one or more sales channels. */ export const deleteSalesChannelsStep = createStep( deleteSalesChannelsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteSalesChannelsStepInput, { container }) => { const service = container.resolve( Modules.SALES_CHANNEL ) diff --git a/packages/core/core-flows/src/sales-channel/steps/detach-locations-from-channels.ts b/packages/core/core-flows/src/sales-channel/steps/detach-locations-from-channels.ts index 78c0aee290..c4e732cf43 100644 --- a/packages/core/core-flows/src/sales-channel/steps/detach-locations-from-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/detach-locations-from-channels.ts @@ -3,9 +3,21 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" +/** + * The data to detach stock locations from sales channels. + */ export interface DetachLocationsFromSalesChannelsStepInput { + /** + * The links to dismiss between locations and sales channels. + */ links: { + /** + * The ID of the sales channel. + */ sales_channel_id: string + /** + * The ID of the location. + */ location_id: string }[] } @@ -13,7 +25,17 @@ export interface DetachLocationsFromSalesChannelsStepInput { export const detachLocationsFromSalesChannelsStepId = "detach-locations-from-sales-channels" /** - * This step dismisses links between location and sales channel records. + * This step dismisses links between stock location and sales channel records. + * + * @example + * const data = detachLocationsFromSalesChannelsStep({ + * links: [ + * { + * sales_channel_id: "sc_123", + * location_id: "sloc_123" + * } + * ] + * }) */ export const detachLocationsFromSalesChannelsStep = createStep( detachLocationsFromSalesChannelsStepId, diff --git a/packages/core/core-flows/src/sales-channel/steps/detach-products-from-sales-channels.ts b/packages/core/core-flows/src/sales-channel/steps/detach-products-from-sales-channels.ts index ae64a38759..284fefa14a 100644 --- a/packages/core/core-flows/src/sales-channel/steps/detach-products-from-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/detach-products-from-sales-channels.ts @@ -1,9 +1,21 @@ import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to detach products from sales channels. + */ export interface DetachProductsFromSalesChannelsStepInput { + /** + * The links to dismiss between products and sales channels. + */ links: { + /** + * The ID of the sales channel. + */ sales_channel_id: string + /** + * The ID of the product. + */ product_id: string }[] } @@ -12,6 +24,16 @@ export const detachProductsFromSalesChannelsStepId = "detach-products-from-sales-channels-step" /** * This step dismisses links between product and sales channel records. + * + * @example + * const data = detachProductsFromSalesChannelsStep({ + * links: [ + * { + * sales_channel_id: "sc_123", + * product_id: "prod_123" + * } + * ] + * }) */ export const detachProductsFromSalesChannelsStep = createStep( detachProductsFromSalesChannelsStepId, diff --git a/packages/core/core-flows/src/sales-channel/steps/update-sales-channels.ts b/packages/core/core-flows/src/sales-channel/steps/update-sales-channels.ts index ad8ed17127..3ebe6ea8a1 100644 --- a/packages/core/core-flows/src/sales-channel/steps/update-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/steps/update-sales-channels.ts @@ -9,14 +9,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update sales channels. + */ export type UpdateSalesChannelsStepInput = { + /** + * The filters to select the sales channels to update. + */ selector: FilterableSalesChannelProps + /** + * The data to update the sales channels. + */ update: UpdateSalesChannelDTO } export const updateSalesChannelsStepId = "update-sales-channels" /** * This step updates sales channels matching the specified filters. + * + * @example + * const data = updateSalesChannelsStep({ + * selector: { + * id: "sc_123" + * }, + * update: { + * name: "Webshop" + * } + * }) */ export const updateSalesChannelsStep = createStep( updateSalesChannelsStepId, diff --git a/packages/core/core-flows/src/sales-channel/workflows/create-sales-channels.ts b/packages/core/core-flows/src/sales-channel/workflows/create-sales-channels.ts index d27562834e..9588260999 100644 --- a/packages/core/core-flows/src/sales-channel/workflows/create-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/workflows/create-sales-channels.ts @@ -12,19 +12,50 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { createSalesChannelsStep } from "../steps/create-sales-channels" +/** + * The data to create sales channels. + */ export type CreateSalesChannelsWorkflowInput = { + /** + * The sales channels to create. + */ salesChannelsData: CreateSalesChannelDTO[] } +/** + * The created sales channels. + */ +export type CreateSalesChannelsWorkflowOutput = SalesChannelDTO[] + export const createSalesChannelsWorkflowId = "create-sales-channels" /** - * This workflow creates one or more sales channels. + * This workflow creates one or more sales channels. It's used by the + * [Create Sales Channel Admin API Route](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannels). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create sales channels within your custom flows. + * + * @example + * const { result } = await createSalesChannelsWorkflow(container) + * .run({ + * input: { + * salesChannelsData: [ + * { + * name: "Webshop" + * } + * ] + * } + * }) + * + * @summary + * + * Create sales channels. */ export const createSalesChannelsWorkflow = createWorkflow( createSalesChannelsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { const createdSalesChannels = createSalesChannelsStep({ data: input.salesChannelsData, }) diff --git a/packages/core/core-flows/src/sales-channel/workflows/delete-sales-channels.ts b/packages/core/core-flows/src/sales-channel/workflows/delete-sales-channels.ts index ee2b7ba228..f98c0653af 100644 --- a/packages/core/core-flows/src/sales-channel/workflows/delete-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/workflows/delete-sales-channels.ts @@ -9,11 +9,35 @@ import { removeRemoteLinkStep } from "../../common/steps/remove-remote-links" import { deleteSalesChannelsStep } from "../steps/delete-sales-channels" import { canDeleteSalesChannelsOrThrowStep } from "../steps" -export type DeleteSalesChannelsWorkflowInput = { ids: string[] } +/** + * The data to delete sales channels. + */ +export type DeleteSalesChannelsWorkflowInput = { + /** + * The IDs of the sales channels to delete. + */ + ids: string[] +} export const deleteSalesChannelsWorkflowId = "delete-sales-channels" /** - * This workflow deletes one or more sales channels. + * This workflow deletes one or more sales channels. It's used by the + * [Delete Sales Channel Admin API Route](https://docs.medusajs.com/api/admin#sales-channels_deletesaleschannelsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete sales channels within your custom flows. + * + * @example + * const { result } = await deleteSalesChannelsWorkflow(container) + * .run({ + * input: { + * ids: ["sc_123"], + * } + * }) + * + * @summary + * + * Delete sales channels. */ export const deleteSalesChannelsWorkflow = createWorkflow( deleteSalesChannelsWorkflowId, diff --git a/packages/core/core-flows/src/sales-channel/workflows/link-products-to-sales-channel.ts b/packages/core/core-flows/src/sales-channel/workflows/link-products-to-sales-channel.ts index cbe1697723..975877d2e6 100644 --- a/packages/core/core-flows/src/sales-channel/workflows/link-products-to-sales-channel.ts +++ b/packages/core/core-flows/src/sales-channel/workflows/link-products-to-sales-channel.ts @@ -4,14 +4,41 @@ import { associateProductsWithSalesChannelsStep } from "../steps/associate-produ import { transform } from "@medusajs/framework/workflows-sdk" import { detachProductsFromSalesChannelsStep } from "../steps" +/** + * The data to manage products available in a sales channel. + * + * @property id - The ID of the sales channel. + * @property add - The products to add to the sales channel. + * @property remove - The products to remove from the sales channel. + */ +export type LinkProductsToSalesChannelWorkflowInput = LinkWorkflowInput + export const linkProductsToSalesChannelWorkflowId = "link-products-to-sales-channel" /** - * This workflow creates or dismisses links between product and sales channel records. + * This workflow manages the products available in a sales channel. It's used by the + * [Manage Products Admin API Route](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelsidproducts). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * manage the products available in a sales channel within your custom flows. + * + * @example + * const { result } = await linkProductsToSalesChannelWorkflow(container) + * .run({ + * input: { + * id: "sc_123", + * add: ["prod_123"], + * remove: ["prod_321"] + * } + * }) + * + * @summary + * + * Manage the products available in a sales channel. */ export const linkProductsToSalesChannelWorkflow = createWorkflow( linkProductsToSalesChannelWorkflowId, - (input: WorkflowData): WorkflowData => { + (input: WorkflowData): WorkflowData => { const toAdd = transform({ input }, (data) => { return data.input.add?.map((productId) => ({ sales_channel_id: data.input.id, diff --git a/packages/core/core-flows/src/sales-channel/workflows/update-sales-channels.ts b/packages/core/core-flows/src/sales-channel/workflows/update-sales-channels.ts index 5d701eefcd..0715c8167b 100644 --- a/packages/core/core-flows/src/sales-channel/workflows/update-sales-channels.ts +++ b/packages/core/core-flows/src/sales-channel/workflows/update-sales-channels.ts @@ -13,20 +13,55 @@ import { import { emitEventStep } from "../../common" import { updateSalesChannelsStep } from "../steps/update-sales-channels" +/** + * The data to update sales channels. + */ export type UpdateSalesChannelsWorkflowInput = { + /** + * The filters to select the sales channels to update. + */ selector: FilterableSalesChannelProps + /** + * The data to update the sales channels. + */ update: UpdateSalesChannelDTO } +/** + * The updated sales channels. + */ +export type UpdateSalesChannelsWorkflowOutput = SalesChannelDTO[] + export const updateSalesChannelsWorkflowId = "update-sales-channels" /** - * This workflow updates sales channels matching the specified conditions. + * This workflow updates sales channels matching the specified conditions. It's used by the + * [Update Sales Channel Admin API Route](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * update sales channels within your custom flows. + * + * @example + * const { result } = await updateSalesChannelsWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "sc_123" + * }, + * update: { + * name: "Webshop" + * } + * } + * }) + * + * @summary + * + * Update sales channels. */ export const updateSalesChannelsWorkflow = createWorkflow( updateSalesChannelsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { const updatedSalesChannels = updateSalesChannelsStep(input) const salesChannelIdEvents = transform( diff --git a/packages/core/core-flows/src/shipping-options/steps/list-shipping-options-for-context.ts b/packages/core/core-flows/src/shipping-options/steps/list-shipping-options-for-context.ts index 9da7fcbc24..41b18243a1 100644 --- a/packages/core/core-flows/src/shipping-options/steps/list-shipping-options-for-context.ts +++ b/packages/core/core-flows/src/shipping-options/steps/list-shipping-options-for-context.ts @@ -6,15 +6,60 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to retrieve the list of shipping options. + */ export interface ListShippingOptionsForContextStepInput { + /** + * The context of retrieving the shipping options. This context + * will be compared against shipping options' rules. The key + * of the context is a name of an attribute, and the value is + * the attribute's value. Shipping options that have rules + * matching this context are retrieved. + */ context: Record + /** + * The fields and relations to select in the returned shipping options, + * along with pagination and sorting options. + * + * Learn more in the [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list). + */ config?: FindConfig } export const listShippingOptionsForContextStepId = "list-shipping-options-for-context" /** - * This step retrieves shipping options that can be used in the specified context. + * This step retrieves shipping options that can be used in the specified context, based on + * the shipping options' rules. + * + * @example + * To retrieve shipping options matching a context: + * + * ```ts + * const data = listShippingOptionsForContextStep({ + * context: { + * region_id: "reg_123" + * } + * }) + * ``` + * + * To retrieve shipping options matching a context with pagination: + * + * ```ts + * const data = listShippingOptionsForContextStep({ + * context: { + * region_id: "reg_123" + * }, + * config: { + * skip: 0, + * take: 10 + * } + * }) + * ``` + * + * Learn more about paginating records and selecting fields in the + * [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list). */ export const listShippingOptionsForContextStep = createStep( listShippingOptionsForContextStepId, diff --git a/packages/core/core-flows/src/shipping-profile/steps/delete-shipping-profile.ts b/packages/core/core-flows/src/shipping-profile/steps/delete-shipping-profile.ts index c528f83177..50203f5228 100644 --- a/packages/core/core-flows/src/shipping-profile/steps/delete-shipping-profile.ts +++ b/packages/core/core-flows/src/shipping-profile/steps/delete-shipping-profile.ts @@ -2,13 +2,18 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the shipping profiles to delete. + */ +export type DeleteShippingProfilesStepInput = string[] + export const deleteShippingProfilesStepId = "delete-shipping-profile" /** * This step deletes one or more shipping profiles. */ export const deleteShippingProfilesStep = createStep( deleteShippingProfilesStepId, - async (ids: string[], { container }) => { + async (ids: DeleteShippingProfilesStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/shipping-profile/workflows/delete-shipping-profile.ts b/packages/core/core-flows/src/shipping-profile/workflows/delete-shipping-profile.ts index 71538fd1ad..c70576fa0d 100644 --- a/packages/core/core-flows/src/shipping-profile/workflows/delete-shipping-profile.ts +++ b/packages/core/core-flows/src/shipping-profile/workflows/delete-shipping-profile.ts @@ -4,14 +4,40 @@ import { deleteShippingProfilesStep } from "../steps" import { removeRemoteLinkStep } from "../../common" import { Modules } from "@medusajs/framework/utils" +/** + * The data to delete shipping profiles. + */ +export type DeleteShippingProfilesWorkflowInput = { + /** + * The IDs of the shipping profiles to delete. + */ + ids: string[] +} + export const deleteShippingProfileWorkflowId = "delete-shipping-profile-workflow" /** - * This workflow deletes one or more shipping profiles. + * This workflow deletes one or more shipping profiles. It's used by the + * [Delete Shipping Profile Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_deleteshippingprofilesid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete shipping profiles within your custom flows. + * + * @example + * const { result } = await deleteShippingProfileWorkflow(container) + * .run({ + * input: { + * ids: ["sp_123"] + * } + * }) + * + * @summary + * + * Delete shipping profiles. */ export const deleteShippingProfileWorkflow = createWorkflow( deleteShippingProfileWorkflowId, - (input: WorkflowData<{ ids: string[] }>) => { + (input: WorkflowData) => { deleteShippingProfilesStep(input.ids) removeRemoteLinkStep({ diff --git a/packages/core/core-flows/src/store/steps/create-stores.ts b/packages/core/core-flows/src/store/steps/create-stores.ts index 0fa4d19463..1bbda7226e 100644 --- a/packages/core/core-flows/src/store/steps/create-stores.ts +++ b/packages/core/core-flows/src/store/steps/create-stores.ts @@ -5,6 +5,11 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createStoresStepId = "create-stores" /** * This step creates one or more stores. + * + * @example + * const data = createStoresStep([{ + * name: "Acme" + * }]) */ export const createStoresStep = createStep( createStoresStepId, diff --git a/packages/core/core-flows/src/store/steps/delete-stores.ts b/packages/core/core-flows/src/store/steps/delete-stores.ts index 12f9fa9bb9..aaa33aa931 100644 --- a/packages/core/core-flows/src/store/steps/delete-stores.ts +++ b/packages/core/core-flows/src/store/steps/delete-stores.ts @@ -2,13 +2,18 @@ import { IStoreModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the stores to delete. + */ +export type DeleteStoresStepInput = string[] + export const deleteStoresStepId = "delete-stores" /** * This step deletes one or more stores. */ export const deleteStoresStep = createStep( deleteStoresStepId, - async (ids: string[], { container }) => { + async (ids: DeleteStoresStepInput, { container }) => { const storeModule = container.resolve(Modules.STORE) await storeModule.softDeleteStores(ids) diff --git a/packages/core/core-flows/src/store/steps/update-stores.ts b/packages/core/core-flows/src/store/steps/update-stores.ts index 6d6bfee31d..eada51399e 100644 --- a/packages/core/core-flows/src/store/steps/update-stores.ts +++ b/packages/core/core-flows/src/store/steps/update-stores.ts @@ -9,14 +9,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update in a store. + */ export type UpdateStoresStepInput = { + /** + * The filters to select the stores to update. + */ selector: FilterableStoreProps + /** + * The data to update in the stores. + */ update: UpdateStoreDTO } export const updateStoresStepId = "update-stores" /** * This step updates stores matching the specified filters. + * + * @example + * const data = updateStoresStep({ + * selector: { + * id: "store_123" + * }, + * update: { + * name: "Acme" + * } + * }) */ export const updateStoresStep = createStep( updateStoresStepId, diff --git a/packages/core/core-flows/src/store/workflows/create-stores.ts b/packages/core/core-flows/src/store/workflows/create-stores.ts index e4981ea4d7..5221ca9fdb 100644 --- a/packages/core/core-flows/src/store/workflows/create-stores.ts +++ b/packages/core/core-flows/src/store/workflows/create-stores.ts @@ -8,19 +8,54 @@ import { import { createStoresStep } from "../steps" import { updatePricePreferencesAsArrayStep } from "../../pricing" -type CreateStoresWorkflowInput = { +/** + * The data to create stores. + */ +export type CreateStoresWorkflowInput = { + /** + * The stores to create. + */ stores: StoreWorkflow.CreateStoreWorkflowInput[] } +/** + * The created stores. + */ +export type CreateStoresWorkflowOutput = StoreDTO[] + export const createStoresWorkflowId = "create-stores" /** - * This workflow creates one or more stores. + * This workflow creates one or more stores. By default, Medusa uses a single store. This is useful + * if you're building a multi-tenant application or a marketplace where each tenant has its own store. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * create stores within your custom flows. + * + * @example + * const { result } = await createStoresWorkflow(container) + * .run({ + * input: { + * stores: [ + * { + * name: "Acme", + * supported_currencies: [{ + * currency_code: "usd", + * is_default: true + * }] + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more stores. */ export const createStoresWorkflow = createWorkflow( createStoresWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { const normalizedInput = transform({ input }, (data) => { return data.input.stores.map((store) => { return { diff --git a/packages/core/core-flows/src/store/workflows/delete-stores.ts b/packages/core/core-flows/src/store/workflows/delete-stores.ts index 474a9b00e2..96527cbc60 100644 --- a/packages/core/core-flows/src/store/workflows/delete-stores.ts +++ b/packages/core/core-flows/src/store/workflows/delete-stores.ts @@ -1,11 +1,38 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { deleteStoresStep } from "../steps" -export type DeleteStoresWorkflowInput = { ids: string[] } +/** + * The data to delete stores. + */ +export type DeleteStoresWorkflowInput = { + /** + * The IDs of the stores to delete. + */ + ids: string[] +} export const deleteStoresWorkflowId = "delete-stores" /** * This workflow deletes one or more stores. + * + * :::note + * + * By default, Medusa uses a single store. This is useful + * if you're building a multi-tenant application or a marketplace where each tenant has its own store. + * If you delete the only store in your application, the Medusa application will re-create it on application start-up. + * + * ::: + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * delete stores within your custom flows. + * + * @example + * const { result } = await deleteStoresWorkflow(container) + * .run({ + * input: { + * ids: ["store_123"] + * } + * }) */ export const deleteStoresWorkflow = createWorkflow( deleteStoresWorkflowId, diff --git a/packages/core/core-flows/src/store/workflows/update-stores.ts b/packages/core/core-flows/src/store/workflows/update-stores.ts index f5750a5d3d..f67b536700 100644 --- a/packages/core/core-flows/src/store/workflows/update-stores.ts +++ b/packages/core/core-flows/src/store/workflows/update-stores.ts @@ -9,15 +9,41 @@ import { import { updateStoresStep } from "../steps" import { updatePricePreferencesAsArrayStep } from "../../pricing" +/** + * The updated stores. + */ +export type UpdateStoresWorkflowOutput = StoreDTO[] + export const updateStoresWorkflowId = "update-stores" /** - * This workflow updates stores matching the specified filters. + * This workflow updates stores matching the specified filters. It's used by the + * [Update Store Admin API Route](https://docs.medusajs.com/api/admin#stores_poststoresid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to + * update stores within your custom flows. + * + * @example + * const { result } = await updateStoresWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "store_123" + * }, + * update: { + * name: "Acme" + * } + * } + * }) + * + * @summary + * + * Update stores. */ export const updateStoresWorkflow = createWorkflow( updateStoresWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { const normalizedInput = transform({ input }, (data) => { if (!data.input.update.supported_currencies?.length) { return data.input diff --git a/packages/core/types/src/api-key/mutations/api-key.ts b/packages/core/types/src/api-key/mutations/api-key.ts index 8b098a2749..cc83e47864 100644 --- a/packages/core/types/src/api-key/mutations/api-key.ts +++ b/packages/core/types/src/api-key/mutations/api-key.ts @@ -16,6 +16,8 @@ export interface CreateApiKeyDTO { /** * Who created the API key. + * If the API key type is `secret`, the user can use the created API key's token to authenticate + * as explained in the [API Reference](https://docs.medusajs.com/api/admin#2-api-token). */ 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 diff --git a/packages/core/types/src/http/store/admin/payloads.ts b/packages/core/types/src/http/store/admin/payloads.ts index 13460c0227..3c74e539a7 100644 --- a/packages/core/types/src/http/store/admin/payloads.ts +++ b/packages/core/types/src/http/store/admin/payloads.ts @@ -1,14 +1,52 @@ -interface AdminUpdateStoreSupportedCurrency { +/** + * The details of a supported currency in a store. + */ +export interface AdminUpdateStoreSupportedCurrency { + /** + * The currency's ISO 3 code. + * + * @example + * usd + */ currency_code: string + /** + * Whether this currency is the default currency in the store. + */ is_default?: boolean + /** + * Whether prices in this currency are tax inclusive. + * + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing). + */ is_tax_inclusive?: boolean } +/** + * The data to update in a store. + */ export interface AdminUpdateStore { + /** + * The name of the store. + */ name?: string + /** + * The supported currencies of the store. + */ supported_currencies?: AdminUpdateStoreSupportedCurrency[] + /** + * The ID of the default sales channel of the store. + */ default_sales_channel_id?: string | null + /** + * The ID of the default region of the store. + */ default_region_id?: string | null + /** + * The ID of the default stock location of the store. + */ default_location_id?: string | null + /** + * Custom key-value pairs to store custom data in the store. + */ metadata?: Record | null } diff --git a/packages/core/types/src/workflow/product-category/index.ts b/packages/core/types/src/workflow/product-category/index.ts index 6cfc22df5f..4579153e47 100644 --- a/packages/core/types/src/workflow/product-category/index.ts +++ b/packages/core/types/src/workflow/product-category/index.ts @@ -5,11 +5,26 @@ import { UpdateProductCategoryDTO, } from "../../product" +/** + * The data to create product categories. + */ export interface CreateProductCategoriesWorkflowInput { + /** + * The product categories to create. + */ product_categories: CreateProductCategoryDTO[] } +/** + * The data to update product categories. + */ export interface UpdateProductCategoriesWorkflowInput { + /** + * The filters to select the product categories to update. + */ selector: FilterableProductCategoryProps + /** + * The data to update in the product categories. + */ update: UpdateProductCategoryDTO } diff --git a/packages/core/types/src/workflow/store/index.ts b/packages/core/types/src/workflow/store/index.ts index 509696833e..f1020eb2cc 100644 --- a/packages/core/types/src/workflow/store/index.ts +++ b/packages/core/types/src/workflow/store/index.ts @@ -1,18 +1,47 @@ import { AdminUpdateStore } from "../../http" import { CreateStoreDTO, FilterableStoreProps } from "../../store" +/** + * The stores to create. + */ export type CreateStoreWorkflowInput = Omit< CreateStoreDTO, "supported_currencies" > & { + /** + * The supported currencies of the store. + */ supported_currencies: { + /** + * The currency ISO 3 code. + * + * @example + * usd + */ currency_code: string + /** + * Whether this currency is the default currency in the store. + */ is_default?: boolean + /** + * Whether prices in this currency are tax inclusive. + * + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing). + */ is_tax_inclusive?: boolean }[] } +/** + * The data to update stores. + */ export interface UpdateStoreWorkflowInput { + /** + * The filters to select the stores to update. + */ selector: FilterableStoreProps + /** + * The data to update in the stores. + */ update: AdminUpdateStore }