From 52f6cfe9221346c38dd5a19ec45effed772cea42 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 16 Jan 2025 15:05:01 +0200 Subject: [PATCH] chore(core-flows,types): improve tsdocs of fulfillment (#10995) --- .../steps/add-shipping-options-prices.ts | 52 ++++++++- .../calculate-shipping-options-prices.ts | 27 ++++- .../fulfillment/steps/cancel-fulfillment.ts | 7 +- .../steps/create-fulfillment-set.ts | 7 +- .../fulfillment/steps/create-fulfillment.ts | 25 ++++- .../steps/create-return-fulfillment.ts | 23 ++++ .../fulfillment/steps/create-service-zones.ts | 7 +- .../steps/create-shipping-profiles.ts | 7 +- .../steps/delete-fulfillment-sets.ts | 7 +- .../fulfillment/steps/delete-service-zones.ts | 7 +- .../steps/delete-shipping-options.ts | 7 +- .../core-flows/src/fulfillment/steps/index.ts | 3 + .../steps/set-shipping-options-price-sets.ts | 9 ++ .../steps/set-shipping-options-prices.ts | 22 ++++ .../fulfillment/steps/update-fulfillment.ts | 6 + .../fulfillment/steps/update-service-zones.ts | 10 ++ .../steps/update-shipping-option-rules.ts | 10 ++ .../steps/update-shipping-profiles.ts | 19 ++++ .../steps/upsert-shipping-options.ts | 3 + .../steps/validate-fulfillment-providers.ts | 15 ++- .../fulfillment/steps/validate-shipment.ts | 9 +- .../steps/validate-shipping-option-prices.ts | 29 ++++- .../workflows/batch-shipping-option-rules.ts | 62 ++++++++-- .../calculate-shipping-options-prices.ts | 34 +++++- .../workflows/cancel-fulfillment.ts | 30 ++++- .../workflows/create-fulfillment.ts | 47 +++++++- .../workflows/create-return-fulfillment.ts | 43 ++++++- .../workflows/create-service-zones.ts | 36 +++++- .../fulfillment/workflows/create-shipment.ts | 25 ++++- .../workflows/create-shipping-options.ts | 76 ++++++++++++- .../workflows/create-shipping-profiles.ts | 23 +++- .../workflows/delete-fulfillment-sets.ts | 30 ++++- .../workflows/delete-service-zones.ts | 30 ++++- .../workflows/delete-shipping-options.ts | 18 ++- .../mark-fulfillment-as-delivered.ts | 45 +++++++- .../workflows/update-fulfillment.ts | 19 +++- .../workflows/update-service-zones.ts | 30 ++++- .../workflows/update-shipping-options.ts | 30 ++++- .../workflows/update-shipping-profiles.ts | 30 ++++- .../core/types/src/fulfillment/provider.ts | 3 + .../core/types/src/fulfillment/workflows.ts | 18 +++ .../types/src/pricing/common/price-rule.ts | 21 ++++ .../calculate-shipping-options-prices.ts | 26 ++++- .../fulfillment/create-fulfillment.ts | 3 + .../fulfillment/create-shipping-options.ts | 72 ++++++++++++ .../fulfillment/delete-shipping-options.ts | 6 + .../src/workflow/fulfillment/service-zones.ts | 43 ++++++- .../workflow/fulfillment/shipping-profiles.ts | 27 +++++ .../fulfillment/update-shipping-options.ts | 106 ++++++++++++++++++ 49 files changed, 1188 insertions(+), 56 deletions(-) diff --git a/packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts b/packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts index 202691d773..27f128715c 100644 --- a/packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts +++ b/packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts @@ -8,23 +8,73 @@ import { import { isString, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to create price sets for a currency code. + */ export interface ShippingOptionsPriceCurrencyCode { + /** + * The currency code of the price. + * + * @example + * usd + */ currency_code: string + /** + * The amount of the price. + */ amount: number + /** + * The rules of the price. + */ rules?: PriceRule[] } +/** + * The data to create price sets for a region ID. + */ interface ShippingOptionsPriceRegionId { + /** + * The ID of the region that this price applies in. + */ region_id: string + /** + * The amount of the price. + */ amount: number + /** + * The rules of the price. + */ rules?: PriceRule[] } +/** + * The data to create price sets for shipping options. + */ export type CreateShippingOptionsPriceSetsStepInput = { + /** + * The ID of the shipping option. + */ id: string + /** + * The prices to create for the shipping option. + */ prices: (ShippingOptionsPriceCurrencyCode | ShippingOptionsPriceRegionId)[] }[] +/** + * The result of creating price sets for shipping options. + */ +export type CreateShippingOptionsPriceSetsStepOutput = { + /** + * The ID of the shipping option. + */ + id: string + /** + * The ID of the price set. + */ + priceSetId: string +}[] + export function buildPriceSet( prices: CreateShippingOptionsPriceSetsStepInput[0]["prices"], regionToCurrencyMap: Map @@ -126,7 +176,7 @@ export const createShippingOptionsPriceSetsStep = createStep( id: input.id, priceSetId: priceSets[index].id, } - }) + }) as CreateShippingOptionsPriceSetsStepOutput return new StepResponse( shippingOptionPriceSetLinData, diff --git a/packages/core/core-flows/src/fulfillment/steps/calculate-shipping-options-prices.ts b/packages/core/core-flows/src/fulfillment/steps/calculate-shipping-options-prices.ts index f1b9f52d6b..ebdec56bbd 100644 --- a/packages/core/core-flows/src/fulfillment/steps/calculate-shipping-options-prices.ts +++ b/packages/core/core-flows/src/fulfillment/steps/calculate-shipping-options-prices.ts @@ -5,14 +5,39 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to calculate the prices for one or more shipping options. + */ +export type CalculateShippingOptionsPriceStepInput = CalculateShippingOptionPriceDTO[] + export const calculateShippingOptionsPricesStepId = "calculate-shipping-options-prices" /** * This step calculates the prices for one or more shipping options. + * + * @example + * const data = calculateShippingOptionsPricesStep([{ + * id: "so_123", + * provider_id: "provider_123", + * optionData: { + * // custom data relevant for the fulfillment provider + * carrier_code: "UPS", + * }, + * data: { + * // custom data relevant for the fulfillment provider + * // specific to the cart using this shipping option + * }, + * context: { + * from_location: { + * id: "sloc_123", + * // other location fields + * } + * } + * }]) */ export const calculateShippingOptionsPricesStep = createStep( calculateShippingOptionsPricesStepId, - async (input: CalculateShippingOptionPriceDTO[], { container }) => { + async (input: CalculateShippingOptionsPriceStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts index 56bb78b7dd..673a126dbf 100644 --- a/packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.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 ID of the fulfillment to cancel. + */ +export type CancelFulfillmentStepInput = string + export const cancelFulfillmentStepId = "cancel-fulfillment" /** * This step cancels a fulfillment. */ export const cancelFulfillmentStep = createStep( cancelFulfillmentStepId, - async (id: string, { container }) => { + async (id: CancelFulfillmentStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts b/packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts index d4539f0e6e..bf4b984e35 100644 --- a/packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts +++ b/packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts @@ -5,13 +5,18 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create one or more fulfillment sets. + */ +export type CreateFulfillmentSetsStepInput = CreateFulfillmentSetDTO[] + export const createFulfillmentSetsId = "create-fulfillment-sets" /** * This step creates one or more fulfillment sets. */ export const createFulfillmentSets = createStep( createFulfillmentSetsId, - async (data: CreateFulfillmentSetDTO[], { container }) => { + async (data: CreateFulfillmentSetsStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts index 9c53b7bc13..90e1d553af 100644 --- a/packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts @@ -7,7 +7,30 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createFulfillmentStepId = "create-fulfillment" /** - * This step creates a fulfillment + * This step creates a fulfillment. + * + * @example + * const data = createFulfillmentStep({ + * location_id: "sloc_123", + * provider_id: "provider_123", + * delivery_address: { + * first_name: "John", + * last_name: "Doe", + * address_1: "Test Street 1", + * city: "Test City", + * postal_code: "12345", + * country_code: "US", + * phone: "123456789", + * }, + * items: [ + * { + * title: "Shirt", + * sku: "shirt", + * quantity: 1, + * barcode: "123456789", + * } + * ] + * }) */ export const createFulfillmentStep = createStep( createFulfillmentStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts index 6f5b8485f1..a3d5ff2c38 100644 --- a/packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts @@ -8,6 +8,29 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createReturnFulfillmentStepId = "create-return-fulfillment" /** * This step creates a fulfillment for a return. + * + * @example + * const data = createReturnFulfillmentStep({ + * location_id: "sloc_123", + * provider_id: "provider_123", + * delivery_address: { + * first_name: "John", + * last_name: "Doe", + * address_1: "Test Street 1", + * city: "Test City", + * postal_code: "12345", + * country_code: "US", + * phone: "123456789", + * }, + * items: [ + * { + * title: "Shirt", + * sku: "shirt", + * quantity: 1, + * barcode: "123456789", + * } + * ] + * }) */ export const createReturnFulfillmentStep = createStep( createReturnFulfillmentStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts b/packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts index 3f6d90661f..05b3f2b5c2 100644 --- a/packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts +++ b/packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts @@ -5,13 +5,18 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The service zones to create. + */ +export type CreateServiceZonesStepInput = CreateServiceZoneDTO[] + export const createServiceZonesStepId = "create-service-zones" /** * This step creates one or more service zones. */ export const createServiceZonesStep = createStep( createServiceZonesStepId, - async (input: CreateServiceZoneDTO[], { container }) => { + async (input: CreateServiceZonesStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts b/packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts index 19ae7c2a2b..b8ad6082f3 100644 --- a/packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts +++ b/packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts @@ -5,13 +5,18 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The shipping profiles to create. + */ +export type CreateShippingProfilesStepInput = CreateShippingProfileDTO[] + export const createShippingProfilesStepId = "create-shipping-profiles" /** * This step creates one or more shipping profiles. */ export const createShippingProfilesStep = createStep( createShippingProfilesStepId, - async (input: CreateShippingProfileDTO[], { container }) => { + async (input: CreateShippingProfilesStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts b/packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts index 37fea5df50..7b85569abd 100644 --- a/packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts +++ b/packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts @@ -2,13 +2,18 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the fulfillment sets to delete. + */ +export type DeleteFulfillmentSetsStepInput = string[] + export const deleteFulfillmentSetsStepId = "delete-fulfillment-sets" /** * This step deletes one or more fulfillment sets. */ export const deleteFulfillmentSetsStep = createStep( deleteFulfillmentSetsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteFulfillmentSetsStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts b/packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts index 9604e4f262..35c376655b 100644 --- a/packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts +++ b/packages/core/core-flows/src/fulfillment/steps/delete-service-zones.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 service zones to delete. + */ +export type DeleteServiceZonesStepInput = string[] + export const deleteServiceZonesStepId = "delete-service-zones" /** * This step deletes one or more service zones. */ export const deleteServiceZonesStep = createStep( deleteServiceZonesStepId, - async (ids: string[], { container }) => { + async (ids: DeleteServiceZonesStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts b/packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts index 262dbf4f64..a2221b21c1 100644 --- a/packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts +++ b/packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts @@ -3,13 +3,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 options to delete. + */ +export type DeleteShippingOptionsStepInput = string[] + export const deleteShippingOptionsStepId = "delete-shipping-options-step" /** * This step deletes one or more shipping options. */ export const deleteShippingOptionsStep = createStep( deleteShippingOptionsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteShippingOptionsStepInput, { container }) => { if (!ids?.length) { return } diff --git a/packages/core/core-flows/src/fulfillment/steps/index.ts b/packages/core/core-flows/src/fulfillment/steps/index.ts index dbb9b5d332..c84233379d 100644 --- a/packages/core/core-flows/src/fulfillment/steps/index.ts +++ b/packages/core/core-flows/src/fulfillment/steps/index.ts @@ -16,3 +16,6 @@ export * from "./update-shipping-profiles" export * from "./upsert-shipping-options" export * from "./validate-shipment" export * from "./calculate-shipping-options-prices" +export * from "./update-service-zones" +export * from "./update-shipping-option-rules" +export * from "./validate-shipping-option-prices" \ No newline at end of file diff --git a/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts b/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts index 4e9255e106..3bc65449f3 100644 --- a/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts +++ b/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts @@ -8,8 +8,17 @@ import { promiseAll, } from "@medusajs/framework/utils" +/** + * The data to set the price sets of a shipping option. + */ export type SetShippingOptionsPriceSetsStepInput = { + /** + * The ID of the shipping option. + */ id: string + /** + * The IDs of the price sets of the shipping option. + */ price_sets?: string[] }[] diff --git a/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts b/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts index f58b3babba..811c17237d 100644 --- a/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts +++ b/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts @@ -23,8 +23,17 @@ interface PriceRegionId { amount: number } +/** + * The data to set the prices of a shipping option. + */ export type SetShippingOptionsPricesStepInput = { + /** + * The ID of the shipping option. + */ id: string + /** + * The prices of the shipping option. + */ prices?: FulfillmentWorkflow.UpdateShippingOptionPriceRecord[] }[] @@ -120,6 +129,19 @@ function buildPrices( export const setShippingOptionsPricesStepId = "set-shipping-options-prices-step" /** * This step sets the prices of one or more shipping options. + * + * @example + * const data = setShippingOptionsPricesStep([ + * { + * id: "so_123", + * prices: [ + * { + * amount: 1000, + * currency_code: "usd", + * } + * ] + * } + * ]) */ export const setShippingOptionsPricesStep = createStep( setShippingOptionsPricesStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts index ae86177030..54ab9b19a1 100644 --- a/packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts @@ -11,6 +11,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const updateFulfillmentStepId = "update-fulfillment" /** * This step updates a fulfillment. + * + * @example + * const data = updateFulfillmentStep({ + * id: "ful_123", + * delivered_at: new Date(), + * }) */ export const updateFulfillmentStep = createStep( updateFulfillmentStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts b/packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts index 744e99a9a9..9ba0550e37 100644 --- a/packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts +++ b/packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts @@ -11,6 +11,16 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const updateServiceZonesStepId = "update-service-zones" /** * This step updates service zones matching the specified filters. + * + * @example + * const data = updateServiceZonesStep({ + * selector: { + * id: "serzo_123" + * }, + * update: { + * name: "US", + * } + * }) */ export const updateServiceZonesStep = createStep( updateServiceZonesStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts b/packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts index 817f3f5df4..dc48e876ea 100644 --- a/packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts +++ b/packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts @@ -9,6 +9,16 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const updateShippingOptionRulesStepId = "update-shipping-option-rules" /** * This step updates one or more shipping option rules. + * + * @example + * const data = updateShippingOptionRulesStep({ + * data: [ + * { + * id: "sor_123", + * operator: "in" + * } + * ] + * }) */ export const updateShippingOptionRulesStep = createStep( updateShippingOptionRulesStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts b/packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts index 6f9e59c418..a7cd885b70 100644 --- a/packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts +++ b/packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts @@ -9,14 +9,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update a shipping profile. + */ export type UpdateShippingProfilesStepInput = { + /** + * The data to update in the shipping profiles. + */ update: UpdateShippingProfileDTO + /** + * The filters to select the shipping profiles to update. + */ selector: FilterableShippingProfileProps } export const updateShippingProfilesStepId = "update-shipping-profiles" /** * This step updates shipping profiles matching the specified filters. + * + * @example + * const data = updateShippingProfilesStep({ + * selector: { + * id: "sp_123" + * }, + * update: { + * name: "Standard" + * } + * }) */ export const updateShippingProfilesStep = createStep( updateShippingProfilesStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts b/packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts index 4b40925153..e9745df09b 100644 --- a/packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts +++ b/packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts @@ -11,6 +11,9 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create or update shipping options. + */ export type UpsertShippingOptionsStepInput = Omit< | FulfillmentWorkflow.CreateShippingOptionsWorkflowInput | FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput, diff --git a/packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts b/packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts index a76eac084d..ed0c29614e 100644 --- a/packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts +++ b/packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts @@ -6,9 +6,21 @@ import { } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to validate fulfillment providers. + */ export type FulfillmentProviderValidationWorkflowInput = { + /** + * The ID of the shipping option to validate. + */ id?: string + /** + * The ID of the shipping option's service zone. + */ service_zone_id?: string + /** + * The ID of the fulfillment provider to validate. + */ provider_id?: string } @@ -16,7 +28,8 @@ export const validateFulfillmentProvidersStepId = "validate-fulfillment-providers-step" /** * This step validates that the specified fulfillment providers are available in the - * specified service zones. + * specified service zones. If the service zone or provider ID are not specified, or + * the provider is not available in the service zone, the step throws an error. */ export const validateFulfillmentProvidersStep = createStep( validateFulfillmentProvidersStepId, diff --git a/packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts b/packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts index 2df8922a7c..7a857c0520 100644 --- a/packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts +++ b/packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts @@ -2,13 +2,20 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types" import { MedusaError, Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The ID of the shipment to validate. + */ +export type ValidateShipmentStepInput = string + export const validateShipmentStepId = "validate-shipment" /** * This step validates that a shipment can be created for a fulfillment. + * If the shipment has already been created, the fulfillment has been canceled, + * or the fulfillment does not have a shipping option, the step throws an error. */ export const validateShipmentStep = createStep( validateShipmentStepId, - async (id: string, { container }) => { + async (id: ValidateShipmentStepInput, { container }) => { const service = container.resolve( Modules.FULFILLMENT ) diff --git a/packages/core/core-flows/src/fulfillment/steps/validate-shipping-option-prices.ts b/packages/core/core-flows/src/fulfillment/steps/validate-shipping-option-prices.ts index 05915ff88e..a354805408 100644 --- a/packages/core/core-flows/src/fulfillment/steps/validate-shipping-option-prices.ts +++ b/packages/core/core-flows/src/fulfillment/steps/validate-shipping-option-prices.ts @@ -6,7 +6,10 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" -type OptionsInput = ( +/** + * The data to validate shipping option prices. + */ +export type ValidateShippingOptionPricesStepInput = ( | FulfillmentWorkflow.CreateShippingOptionsWorkflowInput | FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput )[] @@ -15,14 +18,32 @@ export const validateShippingOptionPricesStepId = "validate-shipping-option-prices" /** - * Validate that shipping options can be crated based on provided price configuration. + * This step validates that shipping options can be created based on provided price configuration. * * For flat rate prices, it validates that regions exist for the shipping option prices. * For calculated prices, it validates with the fulfillment provider if the price can be calculated. + * + * If not valid, the step throws an error. + * + * @example + * const data = validateShippingOptionPricesStep([ + * { + * name: "Standard Shipping", + * service_zone_id: "serzo_123", + * shipping_profile_id: "sp_123", + * provider_id: "prov_123", + * type: { + * label: "Standard", + * description: "Standard shipping", + * code: "standard" + * }, + * price_type: "calculated", + * } + * ]) */ export const validateShippingOptionPricesStep = createStep( validateShippingOptionPricesStepId, - async (options: OptionsInput, { container }) => { + async (options: ValidateShippingOptionPricesStepInput, { container }) => { const fulfillmentModuleService = container.resolve(Modules.FULFILLMENT) const optionIds = options.map( @@ -62,7 +83,7 @@ export const validateShippingOptionPricesStep = createStep( const flatRatePrices: FulfillmentWorkflow.UpdateShippingOptionPriceRecord[] = [] - const calculatedOptions: OptionsInput = [] + const calculatedOptions: ValidateShippingOptionPricesStepInput = [] options.forEach((option) => { if (option.price_type === ShippingOptionPriceType.FLAT) { diff --git a/packages/core/core-flows/src/fulfillment/workflows/batch-shipping-option-rules.ts b/packages/core/core-flows/src/fulfillment/workflows/batch-shipping-option-rules.ts index 5d6cc23785..ab18ff7f95 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/batch-shipping-option-rules.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/batch-shipping-option-rules.ts @@ -18,20 +18,66 @@ import { } from "../steps" import { updateShippingOptionRulesStep } from "../steps/update-shipping-option-rules" +/** + * The data to manage the shipping option rules in bulk. + * + * @property create - The shipping option rules to create. + * @property update - The shipping option rules to update. + * @property delete - The IDs of the shipping option rules to delete. + */ +export type BatchShippingOptionRulesInput = BatchWorkflowInput< + CreateShippingOptionRuleDTO, + UpdateShippingOptionRuleDTO +> + +/** + * The result of managing the shipping option rules in bulk. + * + * @property created - The shipping option rules that were created. + * @property updated - The shipping option rules that were updated. + * @property deleted - The IDs of the shipping option rules that were deleted. + */ +export type BatchShippingOptionRulesOutput = BatchWorkflowOutput + export const batchShippingOptionRulesWorkflowId = "batch-shipping-option-rules" /** - * This workflow manages shipping option rules by creating, updating, or deleting them. + * This workflow manages shipping option rules allowing you to create, update, or delete them. It's used by the + * [Manage the Rules of Shipping Option Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsidrulesbatch). + * + * You can use this workflow within your own custom workflows, allowing you to + * manage shipping option rules within your custom flows. + * + * @example + * const { result } = await batchShippingOptionRulesWorkflow(container) + * .run({ + * input: { + * create: [ + * { + * attribute: "customer_group", + * value: "cusgrp_123", + * operator: "eq", + * shipping_option_id: "so_123" + * } + * ], + * update: [ + * { + * id: "sor_123", + * operator: "in" + * } + * ], + * delete: ["sor_321"] + * } + * }) + * + * @summary + * + * Manage shipping option rules. */ export const batchShippingOptionRulesWorkflow = createWorkflow( batchShippingOptionRulesWorkflowId, ( - input: WorkflowData< - BatchWorkflowInput< - CreateShippingOptionRuleDTO, - UpdateShippingOptionRuleDTO - > - > - ): WorkflowResponse> => { + input: WorkflowData + ): WorkflowResponse => { const actionInputs = transform({ input }, (data) => { const { create, update, delete: del } = data.input return { diff --git a/packages/core/core-flows/src/fulfillment/workflows/calculate-shipping-options-prices.ts b/packages/core/core-flows/src/fulfillment/workflows/calculate-shipping-options-prices.ts index 9087eb8ce9..bb255e0dc6 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/calculate-shipping-options-prices.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/calculate-shipping-options-prices.ts @@ -12,7 +12,39 @@ import { cartFieldsForCalculateShippingOptionsPrices } from "../../cart/utils/fi export const calculateShippingOptionsPricesWorkflowId = "calculate-shipping-options-prices-workflow" /** - * This workflow calculates the prices for one or more shipping options. + * This workflow calculates the prices for one or more shipping options in a cart. It's used by the + * [Calculate Shipping Option Price Store API Route](https://docs.medusajs.com/api/store#shipping-options_postshippingoptionsidcalculate). + * + * :::note + * + * Calculating shipping option prices may require sending requests to third-party fulfillment services. + * This depends on the implementation of the fulfillment provider associated with the shipping option. + * + * ::: + * + * You can use this workflow within your own custom workflows, allowing you to + * calculate the prices of shipping options within your custom flows. + * + * @example + * const { result } = await calculateShippingOptionsPricesWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * shipping_options: [ + * { + * id: "so_123", + * data: { + * // custom data relevant for the fulfillment provider + * carrier_code: "ups", + * } + * } + * ] + * } + * }) + * + * @summary + * + * Calculate shipping option prices in a cart. */ export const calculateShippingOptionsPricesWorkflow = createWorkflow( calculateShippingOptionsPricesWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts b/packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts index 291f12b3da..931e8be5f1 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts @@ -1,13 +1,39 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { cancelFulfillmentStep } from "../steps" +/** + * The data to cancel a fulfillment. + */ +export type CancelFulfillmentWorkflowInput = { + /** + * The ID of the fulfillment to cancel. + */ + id: string +} + export const cancelFulfillmentWorkflowId = "cancel-fulfillment-workflow" /** - * This workflow cancels a fulfillment. + * This workflow cancels a fulfillment. It's used by the + * [Cancel Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillmentsidcancel). + * + * You can use this workflow within your own custom workflows, allowing you to + * cancel a fulfillment within your custom flows. + * + * @example + * const { result } = await cancelFulfillmentWorkflow(container) + * .run({ + * input: { + * id: "ful_123" + * } + * }) + * + * @summary + * + * Cancel a fulfillment. */ export const cancelFulfillmentWorkflow = createWorkflow( cancelFulfillmentWorkflowId, - (input: WorkflowData<{ id: string }>) => { + (input: WorkflowData) => { cancelFulfillmentStep(input.id) } ) diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts b/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts index 0be60c4ec3..3cdef1ad2e 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts @@ -14,7 +14,52 @@ import { useRemoteQueryStep } from "../../common" export const createFulfillmentWorkflowId = "create-fulfillment-workflow" /** - * This workflow creates a fulfillment. + * This workflow creates a fulfillment, which can be used for an order, return, exchanges, and similar concepts. + * The workflow is used by the [Create Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillments). + * + * You can use this workflow within your own custom workflows, allowing you to + * create a fulfillment within your custom flows. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const { result } = await createFulfillmentWorkflow(container) + * .run({ + * input: { + * location_id: "sloc_123", + * provider_id: "provider_123", + * delivery_address: { + * first_name: "John", + * last_name: "Doe", + * address_1: "Test street 1", + * city: "Stockholm", + * country_code: "se", + * postal_code: "12345", + * phone: "123456789" + * }, + * items: [ + * { + * quantity: 1, + * sku: "shirt", + * title: "Shirt", + * barcode: "123" + * } + * ], + * order: { + * id: "order_123" + * // other order details... + * } + * } + * }) + * + * @summary + * + * Create a fulfillment. */ export const createFulfillmentWorkflow = createWorkflow( createFulfillmentWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-return-fulfillment.ts b/packages/core/core-flows/src/fulfillment/workflows/create-return-fulfillment.ts index 0b2b7af6fe..161273ef46 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-return-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-return-fulfillment.ts @@ -15,7 +15,48 @@ import { useRemoteQueryStep } from "../../common" export const createReturnFulfillmentWorkflowId = "create-return-fulfillment-workflow" /** - * This workflow creates a fulfillment for a return. + * This workflow creates a fulfillment for a return. It's used by other return-related workflows, + * such as {@link createAndCompleteReturnOrderWorkflow}. + * + * You can use this workflow within your own custom workflows, allowing you to + * create a fulfillment for a return within your custom flows. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const { result } = await createReturnFulfillmentWorkflow(container) + * .run({ + * input: { + * location_id: "sloc_123", + * provider_id: "provider_123", + * delivery_address: { + * first_name: "John", + * last_name: "Doe", + * address_1: "Test street 1", + * city: "Stockholm", + * country_code: "se", + * postal_code: "12345", + * phone: "123456789" + * }, + * items: [ + * { + * quantity: 1, + * sku: "shirt", + * title: "Shirt", + * barcode: "123" + * } + * ], + * order: { + * id: "order_123" + * // other order details... + * } + * } + * }) */ export const createReturnFulfillmentWorkflow = createWorkflow( createReturnFulfillmentWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-service-zones.ts b/packages/core/core-flows/src/fulfillment/workflows/create-service-zones.ts index 2103943615..aafc43ba6e 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-service-zones.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-service-zones.ts @@ -6,15 +6,47 @@ import { } from "@medusajs/framework/workflows-sdk" import { createServiceZonesStep } from "../steps" +/** + * The service zones to create. + */ +export type CreateServiceZonesWorkflowOutput = ServiceZoneDTO[] + export const createServiceZonesWorkflowId = "create-service-zones-workflow" /** - * This workflow creates one or more service zones. + * This workflow creates one or more service zones. It's used by the + * [Add Service Zone to Fulfillment Set Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_postfulfillmentsetsidservicezones). + * + * You can use this workflow within your own custom workflows, allowing you to + * create service zones within your custom flows. + * + * @example + * const { result } = await createServiceZonesWorkflow(container) + * .run({ + * input: { + * data: [ + * { + * name: "US", + * fulfillment_set_id: "fuset_123", + * geo_zones: [ + * { + * type: "country", + * country_code: "us", + * } + * ] + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more service zones. */ export const createServiceZonesWorkflow = createWorkflow( createServiceZonesWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(createServiceZonesStep(input.data)) } ) diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts b/packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts index 8e60ca7488..d8013ad6d9 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts @@ -10,7 +10,30 @@ import { updateFulfillmentWorkflow } from "./update-fulfillment" export const createShipmentWorkflowId = "create-shipment-workflow" /** - * This workflow creates shipments for a fulfillment. + * This workflow creates shipments for a fulfillment. It's used by the + * [Create Shipment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillmentsidshipment). + * + * You can use this workflow within your own custom workflows, allowing you to + * create shipments within your custom flows. + * + * @example + * const { result } = await createShipmentWorkflow(container) + * .run({ + * input: { + * id: "ful_123", + * labels: [ + * { + * tracking_url: "https://example.com", + * tracking_number: "123", + * label_url: "https://example.com" + * } + * ] + * } + * }) + * + * @summary + * + * Create a shipment for a fulfillment. */ export const createShipmentWorkflow = createWorkflow( createShipmentWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-shipping-options.ts b/packages/core/core-flows/src/fulfillment/workflows/create-shipping-options.ts index e8a6de0caa..63dba9e4b3 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-shipping-options.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-shipping-options.ts @@ -14,17 +14,85 @@ import { setShippingOptionsPriceSetsStep } from "../steps/set-shipping-options-p import { validateFulfillmentProvidersStep } from "../steps/validate-fulfillment-providers" import { validateShippingOptionPricesStep } from "../steps/validate-shipping-option-prices" +/** + * The data to create the shipping options. + */ +export type CreateShippingOptionsWorkflowInput = FulfillmentWorkflow.CreateShippingOptionsWorkflowInput[] + export const createShippingOptionsWorkflowId = "create-shipping-options-workflow" /** - * This workflow creates one or more shipping options. + * This workflow creates one or more shipping options. It's used by the + * [Create Shipping Option Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions). + * + * You can use this workflow within your own custom workflows, allowing you to + * create shipping options within your custom flows. + * + * @example + * To calculate a shipping option with flat rate prices: + * + * ```ts + * const { result } = await createShippingOptionsWorkflow(container) + * .run({ + * input: [ + * { + * name: "Standard Shipping", + * service_zone_id: "serzo_123", + * shipping_profile_id: "sp_123", + * provider_id: "prov_123", + * type: { + * label: "Standard", + * description: "Standard shipping", + * code: "standard" + * }, + * price_type: "flat", + * prices: [ + * { + * amount: 500, + * currency_code: "usd" + * } + * ] + * } + * ] + * }) + * ``` + * + * To calculate shipping option with calculated prices, set `price_type` to `calculated` and don't pass a `prices` array: + * + * :::note + * + * You can calculate the shipping option's price for a cart using the [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/calculateShippingOptionsPricesWorkflow). + * + * ::: + * + * ```ts + * const { result } = await createShippingOptionsWorkflow(container) + * .run({ + * input: [ + * { + * name: "Standard Shipping", + * service_zone_id: "serzo_123", + * shipping_profile_id: "sp_123", + * provider_id: "prov_123", + * type: { + * label: "Standard", + * description: "Standard shipping", + * code: "standard" + * }, + * price_type: "calculated", + * } + * ] + * }) + * ``` + * + * @summary + * + * Create shipping options. */ export const createShippingOptionsWorkflow = createWorkflow( createShippingOptionsWorkflowId, ( - input: WorkflowData< - FulfillmentWorkflow.CreateShippingOptionsWorkflowInput[] - > + input: WorkflowData ): WorkflowResponse => { parallelize( validateFulfillmentProvidersStep(input), diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-shipping-profiles.ts b/packages/core/core-flows/src/fulfillment/workflows/create-shipping-profiles.ts index 308d03c6f2..a269d553ad 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-shipping-profiles.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-shipping-profiles.ts @@ -9,7 +9,28 @@ import { createShippingProfilesStep } from "../steps" export const createShippingProfilesWorkflowId = "create-shipping-profiles-workflow" /** - * This workflow creates one or more shipping profiles. + * This workflow creates one or more shipping profiles. It's used by the + * [Create Shipping Profile Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofiles). + * + * You can use this workflow within your own custom workflows, allowing you to + * create shipping profiles within your custom flows. + * + * @example + * const { result } = await createShippingProfilesWorkflow(container) + * .run({ + * input: { + * data: [ + * { + * name: "Standard", + * type: "standard" + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more shipping profiles. */ export const createShippingProfilesWorkflow = createWorkflow( createShippingProfilesWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/delete-fulfillment-sets.ts b/packages/core/core-flows/src/fulfillment/workflows/delete-fulfillment-sets.ts index a3dd4077b7..1998101f5a 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/delete-fulfillment-sets.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/delete-fulfillment-sets.ts @@ -3,14 +3,40 @@ import { deleteFulfillmentSetsStep } from "../steps" import { removeRemoteLinkStep } from "../../common" import { Modules } from "@medusajs/framework/utils" +/** + * The data to delete one or more fulfillment sets. + */ +export type DeleteFulfillmentSetsWorkflowInput = { + /** + * The IDs of the fulfillment sets to delete. + */ + ids: string[] +} + export const deleteFulfillmentSetsWorkflowId = "delete-fulfillment-sets-workflow" /** - * This workflow deletes one or more fulfillment sets. + * This workflow deletes one or more fulfillment sets. It's used by the + * [Delete Fulfillment Sets Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_deletefulfillmentsetsid). + * + * You can use this workflow within your own custom workflows, allowing you to + * delete fulfillment sets within your custom flows. + * + * @example + * const { result } = await deleteFulfillmentSetsWorkflow(container) + * .run({ + * input: { + * ids: ["fulset_123"] + * } + * }) + * + * @summary + * + * Delete one or more fulfillment sets. */ export const deleteFulfillmentSetsWorkflow = createWorkflow( deleteFulfillmentSetsWorkflowId, - (input: WorkflowData<{ ids: string[] }>) => { + (input: WorkflowData) => { deleteFulfillmentSetsStep(input.ids) removeRemoteLinkStep({ diff --git a/packages/core/core-flows/src/fulfillment/workflows/delete-service-zones.ts b/packages/core/core-flows/src/fulfillment/workflows/delete-service-zones.ts index b1956316f7..854d50009a 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/delete-service-zones.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/delete-service-zones.ts @@ -1,13 +1,39 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { deleteServiceZonesStep } from "../steps" +/** + * The data to delete one or more service zones. + */ +export type DeleteServiceZonesWorkflowInput = { + /** + * The IDs of the service zones to delete. + */ + ids: string[] +} + export const deleteServiceZonesWorkflowId = "delete-service-zones-workflow" /** - * This workflow deletes one or more service zones. + * This workflow deletes one or more service zones. It's used by the + * [Remove Service Zones from Fulfillment Set Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_deletefulfillmentsetsidservicezoneszone_id). + * + * You can use this workflow within your own custom workflows, allowing you to + * delete service zones within your custom flows. + * + * @example + * const { result } = await deleteServiceZonesWorkflow(container) + * .run({ + * input: { + * ids: ["serzo_123"] + * } + * }) + * + * @summary + * + * Delete one or more service zones. */ export const deleteServiceZonesWorkflow = createWorkflow( deleteServiceZonesWorkflowId, - (input: WorkflowData<{ ids: string[] }>) => { + (input: WorkflowData) => { deleteServiceZonesStep(input.ids) } ) diff --git a/packages/core/core-flows/src/fulfillment/workflows/delete-shipping-options.ts b/packages/core/core-flows/src/fulfillment/workflows/delete-shipping-options.ts index 0d5dfbc47b..37aaca46fa 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/delete-shipping-options.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/delete-shipping-options.ts @@ -6,7 +6,23 @@ import { removeRemoteLinkStep } from "../../common" export const deleteShippingOptionsWorkflowId = "delete-shipping-options-workflow" /** - * This workflow deletes one or more shipping options. + * This workflow deletes one or more shipping options. It's used by the + * [Delete Shipping Options Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_deleteshippingoptionsid). + * + * You can use this workflow within your own custom workflows, allowing you to + * delete shipping options within your custom flows. + * + * @example + * const { result } = await deleteShippingOptionsWorkflow(container) + * .run({ + * input: { + * ids: ["so_123"] + * } + * }) + * + * @summary + * + * Delete one or more shipping options. */ export const deleteShippingOptionsWorkflow = createWorkflow( deleteShippingOptionsWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/mark-fulfillment-as-delivered.ts b/packages/core/core-flows/src/fulfillment/workflows/mark-fulfillment-as-delivered.ts index 7c3f903f05..d16335719f 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/mark-fulfillment-as-delivered.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/mark-fulfillment-as-delivered.ts @@ -14,7 +14,21 @@ import { updateFulfillmentWorkflow } from "./update-fulfillment" export const validateFulfillmentDeliverabilityStepId = "validate-fulfillment-deliverability" /** - * This step validates that if a fulfillment can be marked delivered + * This step validates that a fulfillment can be marked delivered. + * If the fulfillment has already been canceled or delivered, the step will throw an error. + * + * :::note + * + * You can retrieve a fulfillment's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = validateFulfillmentDeliverabilityStep({ + * id: "ful_123", + * // other fulfillment data... + * }) */ export const validateFulfillmentDeliverabilityStep = createStep( validateFulfillmentDeliverabilityStepId, @@ -37,14 +51,39 @@ export const validateFulfillmentDeliverabilityStep = createStep( } ) +/** + * The data to mark a fulfillment as delivered. + */ +export type MarkFulfillmentAsDeliveredInput = { + /** + * The fulfillment's ID. + */ + id: string +} + export const markFulfillmentAsDeliveredWorkflowId = "mark-fulfillment-as-delivered-workflow" /** - * This workflow marks fulfillment as delivered. + * This workflow marks a fulfillment as delivered. It's used by the {@link markOrderFulfillmentAsDeliveredWorkflow}. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to mark a fulfillment as delivered in your custom flows. + * + * @example + * const { result } = await markFulfillmentAsDeliveredWorkflow(container) + * .run({ + * input: { + * id: "ful_123", + * } + * }) + * + * @summary + * + * Mark a fulfillment as delivered. */ export const markFulfillmentAsDeliveredWorkflow = createWorkflow( markFulfillmentAsDeliveredWorkflowId, - ({ id }: WorkflowData<{ id: string }>) => { + ({ id }: WorkflowData) => { const fulfillment = useRemoteQueryStep({ entry_point: "fulfillment", fields: ["id", "delivered_at", "canceled_at"], diff --git a/packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts b/packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts index 26cf2a7874..a825708978 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts @@ -8,7 +8,24 @@ import { updateFulfillmentStep } from "../steps" export const updateFulfillmentWorkflowId = "update-fulfillment-workflow" /** - * This workflow updates a fulfillment. + * This workflow updates a fulfillment. It's used by other workflows that update a + * fulfillment, such as {@link markFulfillmentAsDeliveredWorkflow}. + * + * You can use this workflow within your own custom workflows, allowing you to + * update a fulfillment within your custom flows. + * + * @example + * const { result } = await updateFulfillmentWorkflow(container) + * .run({ + * input: { + * id: "ful_123", + * delivered_at: new Date(), + * } + * }) + * + * @summary + * + * Update a fulfillment. */ export const updateFulfillmentWorkflow = createWorkflow( updateFulfillmentWorkflowId, diff --git a/packages/core/core-flows/src/fulfillment/workflows/update-service-zones.ts b/packages/core/core-flows/src/fulfillment/workflows/update-service-zones.ts index ed05612859..5341caee79 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/update-service-zones.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/update-service-zones.ts @@ -6,15 +6,41 @@ import { } from "@medusajs/framework/workflows-sdk" import { updateServiceZonesStep } from "../steps/update-service-zones" +/** + * The updated service zones. + */ +export type UpdateServiceZonesWorkflowOutput = ServiceZoneDTO[] + export const updateServiceZonesWorkflowId = "update-service-zones-workflow" /** - * This workflow updates one or more service zones. + * This workflow updates one or more service zones. It's used by the + * [Update Service Zones Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_postfulfillmentsetsidservicezoneszone_id). + * + * You can use this workflow within your own custom workflows, allowing you to + * update service zones within your custom flows. + * + * @example + * const { result } = await updateServiceZonesWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "serzo_123" + * }, + * update: { + * name: "Europe" + * } + * } + * }) + * + * @summary + * + * Update one or more service zones. */ export const updateServiceZonesWorkflow = createWorkflow( updateServiceZonesWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateServiceZonesStep(input)) } ) diff --git a/packages/core/core-flows/src/fulfillment/workflows/update-shipping-options.ts b/packages/core/core-flows/src/fulfillment/workflows/update-shipping-options.ts index 9f85d9eec9..07a4cafa9f 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/update-shipping-options.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/update-shipping-options.ts @@ -14,17 +14,39 @@ import { validateFulfillmentProvidersStep } from "../steps/validate-fulfillment- import { validateShippingOptionPricesStep } from "../steps/validate-shipping-option-prices" import { ShippingOptionPriceType } from "@medusajs/framework/utils" +/** + * The data to update the shipping options. + */ +export type UpdateShippingOptionsWorkflowInput = FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput[] + export const updateShippingOptionsWorkflowId = "update-shipping-options-workflow" /** - * This workflow updates one or more shipping options. + * This workflow updates one or more shipping options. It's used by the + * [Update Shipping Options Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsid). + * + * You can use this workflow within your own custom workflows, allowing you to + * update shipping options within your custom flows. + * + * @example + * const { result } = await updateShippingOptionsWorkflow(container) + * .run({ + * input: [ + * { + * id: "so_123", + * name: "Standard Shipping", + * } + * ] + * }) + * + * @summary + * + * Update one or more shipping options. */ export const updateShippingOptionsWorkflow = createWorkflow( updateShippingOptionsWorkflowId, ( - input: WorkflowData< - FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput[] - > + input: WorkflowData ): WorkflowResponse => { parallelize( validateFulfillmentProvidersStep(input), diff --git a/packages/core/core-flows/src/fulfillment/workflows/update-shipping-profiles.ts b/packages/core/core-flows/src/fulfillment/workflows/update-shipping-profiles.ts index 6766f47d26..36c5269021 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/update-shipping-profiles.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/update-shipping-profiles.ts @@ -6,16 +6,42 @@ import { } from "@medusajs/framework/workflows-sdk" import { updateShippingProfilesStep } from "../steps/update-shipping-profiles" +/** + * The updated shipping profiles. + */ +export type UpdateShippingProfilesWorkflowOutput = FulfillmentWorkflow.CreateShippingProfilesWorkflowOutput + export const updateShippingProfilesWorkflowId = "update-shipping-profiles-workflow" /** - * This workflow updates one or more shipping profiles. + * This workflow updates one or more shipping profiles. It's used by the + * [Update Shipping Profiles Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofilesid). + * + * You can use this workflow within your own custom workflows, allowing you to + * update shipping profiles within your custom flows. + * + * @example + * const { result } = await updateShippingProfilesWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "sp_123", + * }, + * update: { + * name: "Standard", + * } + * } + * }) + * + * @summary + * + * Update one or more shipping profiles. */ export const updateShippingProfilesWorkflow = createWorkflow( updateShippingProfilesWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateShippingProfilesStep(input)) } ) diff --git a/packages/core/types/src/fulfillment/provider.ts b/packages/core/types/src/fulfillment/provider.ts index 85095a8b6c..841b4fabdb 100644 --- a/packages/core/types/src/fulfillment/provider.ts +++ b/packages/core/types/src/fulfillment/provider.ts @@ -26,6 +26,9 @@ export type FulfillmentOption = { [k: string]: unknown } +/** + * A calculated shipping option price. + */ export type CalculatedShippingOptionPrice = { /** * The calculated price. diff --git a/packages/core/types/src/fulfillment/workflows.ts b/packages/core/types/src/fulfillment/workflows.ts index 455f5256b9..78cc9bb7ad 100644 --- a/packages/core/types/src/fulfillment/workflows.ts +++ b/packages/core/types/src/fulfillment/workflows.ts @@ -5,15 +5,33 @@ import { UpdateShippingOptionRuleDTO, } from "./mutations" +/** + * The data to create shipping option rules. + */ export type AddFulfillmentShippingOptionRulesWorkflowDTO = { + /** + * The shipping option rules to create. + */ data: CreateShippingOptionRuleDTO[] } +/** + * The data to delete shipping option rules. + */ export type RemoveFulfillmentShippingOptionRulesWorkflowDTO = { + /** + * The IDs of the shipping option rules to delete. + */ ids: string[] } +/** + * The data to update shipping option rules. + */ export type UpdateFulfillmentShippingOptionRulesWorkflowDTO = { + /** + * The shipping option rules to update. + */ data: UpdateShippingOptionRuleDTO[] } diff --git a/packages/core/types/src/pricing/common/price-rule.ts b/packages/core/types/src/pricing/common/price-rule.ts index c59a0b4bcf..bcf981b88b 100644 --- a/packages/core/types/src/pricing/common/price-rule.ts +++ b/packages/core/types/src/pricing/common/price-rule.ts @@ -139,8 +139,29 @@ export interface FilterablePriceRuleProps */ export type PricingRuleOperatorValues = "gt" | "lt" | "eq" | "lte" | "gte" +/** + * The rules of a price. + */ export interface PriceRule { + /** + * The attribute to compare. + * + * @example + * amount + */ attribute: string + /** + * The operator to use in the comparison. + * + * @example + * gt + */ operator: PricingRuleOperatorValues + /** + * The value to compare against. + * + * @example + * 100 + */ value: number } diff --git a/packages/core/types/src/workflow/fulfillment/calculate-shipping-options-prices.ts b/packages/core/types/src/workflow/fulfillment/calculate-shipping-options-prices.ts index a1597ec0e1..177254b021 100644 --- a/packages/core/types/src/workflow/fulfillment/calculate-shipping-options-prices.ts +++ b/packages/core/types/src/workflow/fulfillment/calculate-shipping-options-prices.ts @@ -1,9 +1,33 @@ import { CalculatedShippingOptionPrice } from "../../fulfillment" +/** + * The data to calculate shipping option prices. + */ export type CalculateShippingOptionsPricesWorkflowInput = { + /** + * The ID of the cart to calculate the shipping options for. + */ cart_id: string - shipping_options: { id: string; data?: Record }[] + /** + * The shipping options to calculate the prices for. + */ + shipping_options: { + /** + * The ID of the shipping option. + */ + id: string + /** + * Custom data that's necessary for the shipping option's fulfillment provider + * to calculate the price. + * + * Learn more about this property in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ + data?: Record + }[] } +/** + * The calculated shipping option prices. + */ export type CalculateShippingOptionsPricesWorkflowOutput = CalculatedShippingOptionPrice[] diff --git a/packages/core/types/src/workflow/fulfillment/create-fulfillment.ts b/packages/core/types/src/workflow/fulfillment/create-fulfillment.ts index 70c3e91f32..40de1c7d9f 100644 --- a/packages/core/types/src/workflow/fulfillment/create-fulfillment.ts +++ b/packages/core/types/src/workflow/fulfillment/create-fulfillment.ts @@ -115,6 +115,9 @@ export type CreateFulfillmentLabelWorkflowDTO = { export type CreateFulfillmentOrderWorkflowDTO = Record +/** + * The details of a fulfillment to create. + */ export type CreateFulfillmentWorkflowInput = { /** * The associated location's ID. diff --git a/packages/core/types/src/workflow/fulfillment/create-shipping-options.ts b/packages/core/types/src/workflow/fulfillment/create-shipping-options.ts index 15a7563f28..1bc4e6cabb 100644 --- a/packages/core/types/src/workflow/fulfillment/create-shipping-options.ts +++ b/packages/core/types/src/workflow/fulfillment/create-shipping-options.ts @@ -11,35 +11,107 @@ type CreateFlatRateShippingOptionPriceRecord = amount: number } +/** + * The details of the shipping option to create. + */ type CreateFlatShippingOptionInputBase = { + /** + * The name of the shipping option. + */ name: string + /** + * The ID of the service zone the shipping option belongs to. + */ service_zone_id: string + /** + * The ID of the shipping profile the shipping option belongs to. + */ shipping_profile_id: string + /** + * Custom data that's necessary for the shipping option's fulfillment provider. + * Learn more about this property in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ data?: Record + /** + * The ID of the shipping option's fulfillment provider. + */ provider_id: string + /** + * The type of the shipping option. + */ type: { + /** + * The label of the shipping option type. + */ label: string + /** + * The description of the shipping option type. + */ description: string + /** + * The code of the shipping option type. + */ code: string } + /** + * The rules that determine when the shipping option is available. + */ rules?: { + /** + * The attribute to match against. + * @example + * customer_group + */ attribute: string + /** + * The operator to use when matching the attribute. + * + * @example + * in + */ operator: RuleOperatorType + /** + * The value to match against. + * + * @example + * cusgrp_123 + */ value: string | string[] }[] } +/** + * The data to create a flat-rate shipping option. + */ type CreateFlatRateShippingOptionInput = CreateFlatShippingOptionInputBase & { + /** + * The type of the shipping option's price. + */ price_type: "flat" + /** + * The prices for the shipping option. Only required if the price type is `flat`. + */ prices: CreateFlatRateShippingOptionPriceRecord[] } +/** + * The data to create a calculated shipping option. + */ type CreateCalculatedShippingOptionInput = CreateFlatShippingOptionInputBase & { + /** + * The type of the shipping option's price. + */ price_type: "calculated" } +/** + * The data to create a flat rate or calculated shipping option. + */ export type CreateShippingOptionsWorkflowInput = | CreateFlatRateShippingOptionInput | CreateCalculatedShippingOptionInput +/** + * The created shipping options. + */ export type CreateShippingOptionsWorkflowOutput = ShippingOptionDTO[] diff --git a/packages/core/types/src/workflow/fulfillment/delete-shipping-options.ts b/packages/core/types/src/workflow/fulfillment/delete-shipping-options.ts index b50212e171..4800c05fde 100644 --- a/packages/core/types/src/workflow/fulfillment/delete-shipping-options.ts +++ b/packages/core/types/src/workflow/fulfillment/delete-shipping-options.ts @@ -1,3 +1,9 @@ +/** + * The data to delete shipping options. + */ export interface DeleteShippingOptionsWorkflowInput { + /** + * The IDs of the shipping options to delete. + */ ids: string[] } diff --git a/packages/core/types/src/workflow/fulfillment/service-zones.ts b/packages/core/types/src/workflow/fulfillment/service-zones.ts index ef74b00bd2..9db04aa926 100644 --- a/packages/core/types/src/workflow/fulfillment/service-zones.ts +++ b/packages/core/types/src/workflow/fulfillment/service-zones.ts @@ -6,9 +6,21 @@ import { FilterableServiceZoneProps, } from "../../fulfillment" +/** + * The details of a service zone to create. + */ interface CreateServiceZone { + /** + * The name of the service zone. + */ name: string + /** + * The ID of the fulfillment set the service zone belongs to. + */ fulfillment_set_id: string + /** + * The geo zones of the service zone. + */ geo_zones?: ( | Omit | Omit @@ -17,22 +29,51 @@ interface CreateServiceZone { )[] } +/** + * The data to create service zones. + */ export interface CreateServiceZonesWorkflowInput { + /** + * The service zones to create. + */ data: CreateServiceZone[] } +/** + * The data to update a service zone. + */ interface UpdateServiceZone { + /** + * The name of the service zone. + */ name?: string | null + /** + * Add new or existing geo zones to the service zone. + */ geo_zones?: ( | Omit | Omit | Omit | Omit - | { id: string } + | { + /** + * The ID of the geo zone. + */ + id: string + } )[] } +/** + * The data to update service zones. + */ export interface UpdateServiceZonesWorkflowInput { + /** + * The filters to select the service zones to update. + */ selector: FilterableServiceZoneProps + /** + * The data to update in a service zone. + */ update: UpdateServiceZone } diff --git a/packages/core/types/src/workflow/fulfillment/shipping-profiles.ts b/packages/core/types/src/workflow/fulfillment/shipping-profiles.ts index fccf01a59c..0867cc3227 100644 --- a/packages/core/types/src/workflow/fulfillment/shipping-profiles.ts +++ b/packages/core/types/src/workflow/fulfillment/shipping-profiles.ts @@ -3,15 +3,33 @@ import { ShippingProfileDTO, } from "../../fulfillment" +/** + * The details of a shipping profile to create. + */ interface CreateShippingProfile { + /** + * The name of the shipping profile. + */ name: string + /** + * The type of the shipping profile. + */ type: string } +/** + * The data to create shipping profiles. + */ export interface CreateShippingProfilesWorkflowInput { + /** + * The shipping profiles to create. + */ data: CreateShippingProfile[] } +/** + * The created shipping profiles. + */ export type CreateShippingProfilesWorkflowOutput = ShippingProfileDTO[] interface UpdateShippingProfile { @@ -19,7 +37,16 @@ interface UpdateShippingProfile { type?: string } +/** + * The data to update a shipping profile. + */ export interface UpdateShippingProfilesWorkflowInput { + /** + * The filter to select the shipping profiles to update. + */ selector: FilterableShippingProfileProps + /** + * The data to update in the shipping profile. + */ update: UpdateShippingProfile } diff --git a/packages/core/types/src/workflow/fulfillment/update-shipping-options.ts b/packages/core/types/src/workflow/fulfillment/update-shipping-options.ts index 573be19684..755f95b0b9 100644 --- a/packages/core/types/src/workflow/fulfillment/update-shipping-options.ts +++ b/packages/core/types/src/workflow/fulfillment/update-shipping-options.ts @@ -1,54 +1,160 @@ import { RuleOperatorType } from "../../common" import { PriceRule } from "../../pricing" +/** + * The data to update a shipping option. + */ type UpdateFlatShippingOptionInputBase = { + /** + * The ID of the shipping option. + */ id: string + /** + * The name of the shipping option. + */ name?: string + /** + * The ID of the service zone the shipping option belongs to. + */ service_zone_id?: string + /** + * The ID of the shipping profile the shipping option belongs to. + */ shipping_profile_id?: string + /** + * Custom data that's necessary for the shipping option's fulfillment provider. + * Learn more about this property in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ data?: Record + /** + * The ID of the shipping option's fulfillment provider. + */ provider_id?: string + /** + * The type of the shipping option. + */ type?: { + /** + * The label of the shipping option type. + */ label: string + /** + * The description of the shipping option type. + */ description: string + /** + * The code of the shipping option type. + */ code: string } + /** + * The rules that determine when the shipping option is available. + */ rules?: { + /** + * The attribute to compare. + * + * @example + * customer_group + */ attribute: string + /** + * The operator to compare with. + * + * @example + * in + */ operator: RuleOperatorType + /** + * The value to compare with. + * + * @example + * cusgrp_123 + */ value: string | string[] }[] } +/** + * The data to update a flat rate shipping option. + */ export type UpdateShippingOptionPriceRecord = | { + /** + * The ID of the price record. + */ id?: string + /** + * The currency code of the price. + * + * @example + * usd + */ currency_code?: string + /** + * The amount of the price. + */ amount?: number + /** + * The rules of the price. + */ rules?: PriceRule[] } | { + /** + * The ID of the price record. + */ id?: string + /** + * The ID of the region that this price applies in. + */ region_id?: string + /** + * The amount of the price. + */ amount?: number + /** + * The rules of the price. + */ rules?: PriceRule[] } export type UpdateCalculatedShippingOptionInput = UpdateFlatShippingOptionInputBase & { + /** + * The price type of the shipping option. + */ price_type?: "calculated" } +/** + * The data to update a flat rate shipping option. + */ export type UpdateFlatRateShippingOptionInput = UpdateFlatShippingOptionInputBase & { + /** + * The price type of the shipping option. + */ price_type?: "flat" + /** + * The prices of the shipping option. + */ prices?: UpdateShippingOptionPriceRecord[] } +/** + * The data to update shipping options. + */ export type UpdateShippingOptionsWorkflowInput = | UpdateFlatRateShippingOptionInput | UpdateCalculatedShippingOptionInput +/** + * The result of updating shipping options. + */ export type UpdateShippingOptionsWorkflowOutput = { + /** + * The updated shipping option's ID. + */ id: string }[]