chore(core-flows): [1] export types and types, add basic TSDocs (#8504)

This PR exports types and steps from the core-flows package, and adds simple TSDocs for workflows / steps. This is essential for the workflows reference.

PR 1/n

packages/core/core-flows/src/api-key/steps/create-api-keys.ts

@@ -2,11 +2,14 @@ import { CreateApiKeyDTO, IApiKeyModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type CreateApiKeysStepInput = {
+export type CreateApiKeysStepInput = {
   api_keys: CreateApiKeyDTO[]
 }
 
 export const createApiKeysStepId = "create-api-keys"
+/**
+ * This step creates one or more API keys.
+ */
 export const createApiKeysStep = createStep(
   createApiKeysStepId,
   async (data: CreateApiKeysStepInput, { container }) => {

packages/core/core-flows/src/api-key/steps/delete-api-keys.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 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 }) => {

packages/core/core-flows/src/api-key/steps/link-sales-channels-to-publishable-key.ts

@@ -3,6 +3,9 @@ import { ContainerRegistrationKeys, Modules, promiseAll } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const linkSalesChannelsToApiKeyStepId = "link-sales-channels-to-api-key"
+/**
+ * This step links sales channels to API keys.
+ */
 export const linkSalesChannelsToApiKeyStep = createStep(
   linkSalesChannelsToApiKeyStepId,
   async (input: LinkWorkflowInput, { container }) => {

packages/core/core-flows/src/api-key/steps/revoke-api-keys.ts

@@ -6,12 +6,15 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type RevokeApiKeysStepInput = {
+export type RevokeApiKeysStepInput = {
   selector: FilterableApiKeyProps
   revoke: RevokeApiKeyDTO
 }
 
 export const revokeApiKeysStepId = "revoke-api-keys"
+/**
+ * This step revokes one or more API keys.
+ */
 export const revokeApiKeysStep = createStep(
   { name: revokeApiKeysStepId, noCompensation: true },
   async (data: RevokeApiKeysStepInput, { container }) => {

packages/core/core-flows/src/api-key/steps/update-api-keys.ts

@@ -9,12 +9,15 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type UpdateApiKeysStepInput = {
+export type UpdateApiKeysStepInput = {
   selector: FilterableApiKeyProps
   update: UpdateApiKeyDTO
 }
 
 export const updateApiKeysStepId = "update-api-keys"
+/**
+ * This step updates one or more API keys.
+ */
 export const updateApiKeysStep = createStep(
   updateApiKeysStepId,
   async (data: UpdateApiKeysStepInput, { container }) => {

packages/core/core-flows/src/api-key/steps/validate-sales-channel-exists.ts

@@ -6,14 +6,17 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface ValidateSalesChannelsExistStepInput {
   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.
+ */
 export const validateSalesChannelsExistStep = createStep(
   validateSalesChannelsExistStepId,
-  async (data: StepInput, { container }) => {
+  async (data: ValidateSalesChannelsExistStepInput, { container }) => {
     const salesChannelModuleService =
       container.resolve<ISalesChannelModuleService>(
         ModuleRegistrationName.SALES_CHANNEL

packages/core/core-flows/src/api-key/workflows/create-api-keys.ts

@@ -6,12 +6,15 @@ import {
 } from "@medusajs/workflows-sdk"
 import { createApiKeysStep } from "../steps"
 
-type WorkflowInput = { api_keys: CreateApiKeyDTO[] }
+export type CreateApiKeysWorkflowInput = { api_keys: CreateApiKeyDTO[] }
 
 export const createApiKeysWorkflowId = "create-api-keys"
+/**
+ * This workflow creates one or more API keys.
+ */
 export const createApiKeysWorkflow = createWorkflow(
   createApiKeysWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowResponse<ApiKeyDTO[]> => {
+  (input: WorkflowData<CreateApiKeysWorkflowInput>): WorkflowResponse<ApiKeyDTO[]> => {
     return new WorkflowResponse(createApiKeysStep(input))
   }
 )

packages/core/core-flows/src/api-key/workflows/delete-api-keys.ts

@@ -3,12 +3,15 @@ import { removeRemoteLinkStep } from "../../common/steps/remove-remote-links"
 import { deleteApiKeysStep } from "../steps"
 import { Modules } from "@medusajs/utils"
 
-type WorkflowInput = { ids: string[] }
+export type DeleteApiKeysWorkflowInput = { ids: string[] }
 
 export const deleteApiKeysWorkflowId = "delete-api-keys"
+/**
+ * This workflow deletes one or more API keys.
+ */
 export const deleteApiKeysWorkflow = createWorkflow(
   deleteApiKeysWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<DeleteApiKeysWorkflowInput>): WorkflowData<void> => {
     deleteApiKeysStep(input.ids)
 
     // Please note, the ids here should be publishable key IDs

packages/core/core-flows/src/api-key/workflows/link-sales-channels-to-publishable-key.ts

@@ -7,6 +7,9 @@ import {
 
 export const linkSalesChannelsToApiKeyWorkflowId =
   "link-sales-channels-to-api-key"
+/**
+ * This workflow links sales channels to API keys.
+ */
 export const linkSalesChannelsToApiKeyWorkflow = createWorkflow(
   linkSalesChannelsToApiKeyWorkflowId,
   (input: WorkflowData<LinkWorkflowInput>) => {

packages/core/core-flows/src/api-key/workflows/revoke-api-keys.ts

@@ -10,17 +10,18 @@ import {
 } from "@medusajs/workflows-sdk"
 import { revokeApiKeysStep } from "../steps"
 
-type RevokeApiKeysStepInput = {
+export type RevokeApiKeysWorkflowInput = {
   selector: FilterableApiKeyProps
   revoke: RevokeApiKeyDTO
 }
 
-type WorkflowInput = RevokeApiKeysStepInput
-
 export const revokeApiKeysWorkflowId = "revoke-api-keys"
+/**
+ * This workflow revokes one or more API keys.
+ */
 export const revokeApiKeysWorkflow = createWorkflow(
   revokeApiKeysWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowResponse<ApiKeyDTO[]> => {
+  (input: WorkflowData<RevokeApiKeysWorkflowInput>): WorkflowResponse<ApiKeyDTO[]> => {
     return new WorkflowResponse(revokeApiKeysStep(input))
   }
 )

packages/core/core-flows/src/api-key/workflows/update-api-keys.ts

@@ -10,17 +10,18 @@ import {
 } from "@medusajs/workflows-sdk"
 import { updateApiKeysStep } from "../steps"
 
-type UpdateApiKeysStepInput = {
+export type UpdateApiKeysWorkflowInput = {
   selector: FilterableApiKeyProps
   update: UpdateApiKeyDTO
 }
 
-type WorkflowInput = UpdateApiKeysStepInput
-
 export const updateApiKeysWorkflowId = "update-api-keys"
+/**
+ * This workflow creates one or more API keys.
+ */
 export const updateApiKeysWorkflow = createWorkflow(
   updateApiKeysWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowResponse<ApiKeyDTO[]> => {
+  (input: WorkflowData<UpdateApiKeysWorkflowInput>): WorkflowResponse<ApiKeyDTO[]> => {
     return new WorkflowResponse(updateApiKeysStep(input))
   }
 )

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

@@ -3,16 +3,19 @@ import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 import { IAuthModuleService } from "@medusajs/types"
 import { isDefined, ModuleRegistrationName } from "@medusajs/utils"
 
-type StepInput = {
+export type SetAuthAppMetadataStepInput = {
   authIdentityId: string
   actorType: string
   value: string
 }
 
 export const setAuthAppMetadataStepId = "set-auth-app-metadata"
+/**
+ * This step sets the `app_metadata` property of an auth identity.
+ */
 export const setAuthAppMetadataStep = createStep(
   setAuthAppMetadataStepId,
-  async (data: StepInput, { container }) => {
+  async (data: SetAuthAppMetadataStepInput, { container }) => {
     const service = container.resolve<IAuthModuleService>(
       ModuleRegistrationName.AUTH
     )

packages/core/core-flows/src/common/workflows/batch-links.ts

@@ -11,6 +11,9 @@ import { dismissRemoteLinkStep } from "../steps/dismiss-remote-links"
 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.
+ */
 export const batchLinksWorkflow = createWorkflow(
   batchLinksWorkflowId,
   (

packages/core/core-flows/src/common/workflows/create-links.ts

@@ -7,6 +7,9 @@ import {
 import { createRemoteLinkStep } from "../steps/create-remote-links"
 
 export const createLinksWorkflowId = "create-link"
+/**
+ * This workflow creates one or more links between records.
+ */
 export const createLinksWorkflow = createWorkflow(
   createLinksWorkflowId,
   (input: WorkflowData<LinkDefinition[]>) => {

packages/core/core-flows/src/common/workflows/dismiss-links.ts

@@ -7,6 +7,9 @@ import {
 import { dismissRemoteLinkStep } from "../steps/dismiss-remote-links"
 
 export const dismissLinksWorkflowId = "dismiss-link"
+/**
+ * This workflow dismisses one or more links between records.
+ */
 export const dismissLinksWorkflow = createWorkflow(
   dismissLinksWorkflowId,
   (input: WorkflowData<LinkDefinition[]>) => {

packages/core/core-flows/src/common/workflows/update-links.ts

@@ -7,6 +7,9 @@ import {
 import { updateRemoteLinksStep } from "../steps/update-remote-links"
 
 export const updateLinksWorkflowId = "update-link"
+/**
+ * This workflow updates one or more links between records.
+ */
 export const updateLinksWorkflow = createWorkflow(
   updateLinksWorkflowId,
   (input: WorkflowData<LinkDefinition[]>) => {

packages/core/core-flows/src/customer/steps/create-addresses.ts

@@ -6,6 +6,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createCustomerAddressesStepId = "create-customer-addresses"
+/**
+ * This step creates one or more customer addresses.
+ */
 export const createCustomerAddressesStep = createStep(
   createCustomerAddressesStepId,
   async (data: CreateCustomerAddressDTO[], { container }) => {

packages/core/core-flows/src/customer/steps/create-customers.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createCustomersStepId = "create-customers"
+/**
+ * This step creates one or more customers.
+ */
 export const createCustomersStep = createStep(
   createCustomersStepId,
   async (data: CreateCustomerDTO[], { container }) => {

packages/core/core-flows/src/customer/steps/delete-addresses.ts

@@ -2,11 +2,13 @@ import { ICustomerModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
-type DeleteCustomerAddressStepInput = string[]
 export const deleteCustomerAddressesStepId = "delete-customer-addresses"
+/**
+ * This step deletes one or more customer addresses.
+ */
 export const deleteCustomerAddressesStep = createStep(
   deleteCustomerAddressesStepId,
-  async (ids: DeleteCustomerAddressStepInput, { container }) => {
+  async (ids: string[], { container }) => {
     const service = container.resolve<ICustomerModuleService>(
       ModuleRegistrationName.CUSTOMER
     )

packages/core/core-flows/src/customer/steps/delete-customers.ts

@@ -2,12 +2,13 @@ import { ICustomerModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
-type DeleteCustomerStepInput = string[]
-
 export const deleteCustomersStepId = "delete-customers"
+/**
+ * This step deletes one or more customers.
+ */
 export const deleteCustomersStep = createStep(
   deleteCustomersStepId,
-  async (ids: DeleteCustomerStepInput, { container }) => {
+  async (ids: string[], { container }) => {
     const service = container.resolve<ICustomerModuleService>(
       ModuleRegistrationName.CUSTOMER
     )

packages/core/core-flows/src/customer/steps/maybe-unset-default-billing-addresses.ts

@@ -8,7 +8,7 @@ import { ModuleRegistrationName, isDefined } from "@medusajs/utils"
 import { createStep } from "@medusajs/workflows-sdk"
 import { unsetForCreate, unsetForUpdate } from "./utils"
 
-type StepInput = {
+export type MaybeUnsetDefaultBillingAddressStepInput = {
   create?: CreateCustomerAddressDTO[]
   update?: {
     selector: FilterableCustomerAddressProps
@@ -18,9 +18,12 @@ type StepInput = {
 
 export const maybeUnsetDefaultBillingAddressesStepId =
   "maybe-unset-default-billing-customer-addresses"
+/**
+ * This step unsets the `is_default_billing` property of one or more addresses.
+ */
 export const maybeUnsetDefaultBillingAddressesStep = createStep(
   maybeUnsetDefaultBillingAddressesStepId,
-  async (data: StepInput, { container }) => {
+  async (data: MaybeUnsetDefaultBillingAddressStepInput, { container }) => {
     const customerModuleService = container.resolve<ICustomerModuleService>(
       ModuleRegistrationName.CUSTOMER
     )

packages/core/core-flows/src/customer/steps/maybe-unset-default-shipping-addresses.ts

@@ -8,7 +8,7 @@ import { ModuleRegistrationName, isDefined } from "@medusajs/utils"
 import { createStep } from "@medusajs/workflows-sdk"
 import { unsetForCreate, unsetForUpdate } from "./utils"
 
-type StepInput = {
+export type MaybeUnsetDefaultShippingAddressesStepInput = {
   create?: CreateCustomerAddressDTO[]
   update?: {
     selector: FilterableCustomerAddressProps
@@ -18,9 +18,12 @@ type StepInput = {
 
 export const maybeUnsetDefaultShippingAddressesStepId =
   "maybe-unset-default-shipping-customer-addresses"
+/**
+ * This step unsets the `is_default_shipping` property of one or more addresses.
+ */
 export const maybeUnsetDefaultShippingAddressesStep = createStep(
   maybeUnsetDefaultShippingAddressesStepId,
-  async (data: StepInput, { container }) => {
+  async (data: MaybeUnsetDefaultShippingAddressesStepInput, { container }) => {
     const customerModuleService = container.resolve<ICustomerModuleService>(
       ModuleRegistrationName.CUSTOMER
     )

packages/core/core-flows/src/customer/steps/update-addresses.ts

@@ -10,12 +10,15 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type UpdateCustomerAddresseStepInput = {
+export type UpdateCustomerAddresseStepInput = {
   selector: FilterableCustomerAddressProps
   update: UpdateCustomerAddressDTO
 }
 
 export const updateCustomerAddresseStepId = "update-customer-addresses"
+/**
+ * This step updates one or more customer addresses.
+ */
 export const updateCustomerAddressesStep = createStep(
   updateCustomerAddresseStepId,
   async (data: UpdateCustomerAddresseStepInput, { container }) => {

packages/core/core-flows/src/customer/steps/update-customers.ts

@@ -10,12 +10,15 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type UpdateCustomersStepInput = {
+export type UpdateCustomersStepInput = {
   selector: FilterableCustomerProps
   update: CustomerUpdatableFields
 }
 
 export const updateCustomersStepId = "update-customer"
+/**
+ * This step updates one or more customers.
+ */
 export const updateCustomersStep = createStep(
   updateCustomersStepId,
   async (data: UpdateCustomersStepInput, { container }) => {

packages/core/core-flows/src/customer/workflows/create-addresses.ts

@@ -13,12 +13,15 @@ import {
   maybeUnsetDefaultShippingAddressesStep,
 } from "../steps"
 
-type WorkflowInput = { addresses: CreateCustomerAddressDTO[] } & AdditionalData
+export type CreateCustomerAddressesWorkflowInput = { addresses: CreateCustomerAddressDTO[] } & AdditionalData
 
 export const createCustomerAddressesWorkflowId = "create-customer-addresses"
+/**
+ * This workflow creates one or more customer address.
+ */
 export const createCustomerAddressesWorkflow = createWorkflow(
   createCustomerAddressesWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<CreateCustomerAddressesWorkflowInput>) => {
     const unsetInput = transform(input, (data) => ({
       create: data.addresses,
     }))

packages/core/core-flows/src/customer/workflows/create-customer-account.ts

@@ -8,15 +8,18 @@ import { createCustomersStep } from "../steps"
 import { transform } from "@medusajs/workflows-sdk"
 import { setAuthAppMetadataStep } from "../../auth"
 
-type WorkflowInput = {
+export type CreateCustomerAccountWorkflowInput = {
   authIdentityId: string
   customersData: CreateCustomerDTO
 }
 
 export const createCustomerAccountWorkflowId = "create-customer-account"
+/**
+ * This workflow creates an authentication account for a customer.
+ */
 export const createCustomerAccountWorkflow = createWorkflow(
   createCustomerAccountWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowResponse<CustomerDTO> => {
+  (input: WorkflowData<CreateCustomerAccountWorkflowInput>): WorkflowResponse<CustomerDTO> => {
     const customers = createCustomersStep([input.customersData])
 
     const customer = transform(

packages/core/core-flows/src/customer/workflows/create-customers.ts

@@ -7,13 +7,15 @@ import {
 } from "@medusajs/workflows-sdk"
 import { createCustomersStep } from "../steps"
 
-type WorkflowInput = { customersData: CreateCustomerDTO[] } & AdditionalData
+export type CreateCustomersWorkflowInput = { customersData: CreateCustomerDTO[] } & AdditionalData
 
 export const createCustomersWorkflowId = "create-customers"
-
+/**
+ * This workflow creates one or more customers.
+ */
 export const createCustomersWorkflow = createWorkflow(
   createCustomersWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<CreateCustomersWorkflowInput>) => {
     const createdCustomers = createCustomersStep(input.customersData)
     const customersCreated = createHook("customersCreated", {
       customers: createdCustomers,

packages/core/core-flows/src/customer/workflows/delete-addresses.ts

@@ -6,12 +6,15 @@ import {
 } from "@medusajs/workflows-sdk"
 import { deleteCustomerAddressesStep } from "../steps"
 
-type WorkflowInput = { ids: string[] }
+export type DeleteCustomerAddressesWorkflowInput = { ids: string[] }
 
 export const deleteCustomerAddressesWorkflowId = "delete-customer-addresses"
+/**
+ * This workflow deletes one or more customer addresses.
+ */
 export const deleteCustomerAddressesWorkflow = createWorkflow(
   deleteCustomerAddressesWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<DeleteCustomerAddressesWorkflowInput>) => {
     const deletedAddresses = deleteCustomerAddressesStep(input.ids)
     const addressesDeleted = createHook("addressesDeleted", {
       ids: input.ids,

packages/core/core-flows/src/customer/workflows/delete-customers.ts

@@ -6,12 +6,15 @@ import {
 } from "@medusajs/workflows-sdk"
 import { deleteCustomersStep } from "../steps"
 
-type WorkflowInput = { ids: string[] }
+export type DeleteCustomersWorkflowInput = { ids: string[] }
 
 export const deleteCustomersWorkflowId = "delete-customers"
+/**
+ * This workflow deletes one or more customers.
+ */
 export const deleteCustomersWorkflow = createWorkflow(
   deleteCustomersWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<DeleteCustomersWorkflowInput>) => {
     const deletedCustomers = deleteCustomersStep(input.ids)
     const customersDeleted = createHook("customersDeleted", {
       ids: input.ids,

packages/core/core-flows/src/customer/workflows/update-addresses.ts

@@ -17,15 +17,18 @@ import {
   updateCustomerAddressesStep,
 } from "../steps"
 
-type WorkflowInput = {
+export type UpdateCustomerAddressesWorkflowInput = {
   selector: FilterableCustomerAddressProps
   update: UpdateCustomerAddressDTO
 } & AdditionalData
 
 export const updateCustomerAddressesWorkflowId = "update-customer-addresses"
+/**
+ * This workflow updates one or more customer addresses.
+ */
 export const updateCustomerAddressesWorkflow = createWorkflow(
   updateCustomerAddressesWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<UpdateCustomerAddressesWorkflowInput>) => {
     const unsetInput = transform(input, (data) => ({
       update: data,
     }))

packages/core/core-flows/src/customer/workflows/update-customers.ts

@@ -11,17 +11,18 @@ import {
 } from "@medusajs/workflows-sdk"
 import { updateCustomersStep } from "../steps"
 
-type UpdateCustomersStepInput = {
+export type UpdateCustomersWorkflowInput = {
   selector: FilterableCustomerProps
   update: CustomerUpdatableFields
 } & AdditionalData
 
-type WorkflowInput = UpdateCustomersStepInput
-
 export const updateCustomersWorkflowId = "update-customers"
+/**
+ * This workflow updates one or more customers.
+ */
 export const updateCustomersWorkflow = createWorkflow(
   updateCustomersWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<UpdateCustomersWorkflowInput>) => {
     const updatedCustomers = updateCustomersStep(input)
     const customersUpdated = createHook("customersUpdated", {
       customers: updatedCustomers,