From c09d7e5ba896b045ea04d194944c762e4d9db27c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 17 Jan 2025 11:07:12 +0200 Subject: [PATCH] chore(core-flows,types): improve TSDocs of inventory-related workflows (#11013) --- .../steps/adjust-inventory-levels.ts | 20 +++++- .../inventory/steps/attach-inventory-items.ts | 27 ++++++-- .../inventory/steps/create-inventory-items.ts | 7 +- .../steps/create-inventory-levels.ts | 7 +- .../inventory/steps/delete-inventory-items.ts | 7 +- .../steps/delete-inventory-levels.ts | 7 +- .../inventory/steps/update-inventory-items.ts | 7 +- .../steps/update-inventory-levels.ts | 7 +- .../steps/validate-inventory-items.ts | 8 ++- .../steps/validate-inventory-locations.ts | 11 +++- ...idate-singular-inventory-items-for-tags.ts | 22 ++++++- .../workflows/batch-inventory-item-levels.ts | 56 ++++++++++++++-- .../workflows/create-inventory-items.ts | 39 ++++++++++- .../workflows/create-inventory-levels.ts | 29 +++++++- .../workflows/delete-inventory-items.ts | 30 ++++++++- .../workflows/delete-inventory-levels.ts | 66 +++++++++++++++++-- .../workflows/update-inventory-items.ts | 37 ++++++++++- .../workflows/update-inventory-levels.ts | 39 ++++++++++- .../workflows/create-refund-reasons.ts | 3 +- .../workflows/delete-refund-reasons.ts | 30 ++++++++- .../workflows/update-refund-reasons.ts | 3 +- .../reservation/steps/create-reservations.ts | 16 ++++- .../delete-reservations-by-line-items.ts | 7 +- .../reservation/steps/delete-reservations.ts | 7 +- .../reservation/steps/update-reservations.ts | 15 ++++- .../workflows/create-reservations.ts | 24 ++++++- .../workflows/delete-reservations.ts | 28 +++++++- .../workflows/update-reservations.ts | 23 ++++++- ...sociate-locations-with-fulfillment-sets.ts | 12 ++++ .../steps/create-stock-locations.ts | 7 +- .../steps/delete-stock-locations.ts | 7 +- .../steps/update-stock-locations.ts | 19 ++++++ .../steps/upsert-stock-location-addresses.ts | 5 ++ .../create-location-fulfillment-set.ts | 22 ++++++- .../workflows/create-stock-locations.ts | 28 +++++++- .../workflows/delete-stock-locations.ts | 24 ++++++- .../link-sales-channels-to-stock-location.ts | 31 ++++++++- .../workflows/update-stock-locations.ts | 32 ++++++++- .../src/inventory/mutations/inventory-item.ts | 6 ++ .../inventory/mutations/inventory-level.ts | 2 + .../inventory/mutations/reservation-item.ts | 3 + .../core/types/src/stock-location/common.ts | 7 ++ .../reservation/create-reservations.ts | 9 +++ .../reservation/update-reservations.ts | 9 +++ .../workflows/stock-locations/mutations.ts | 15 +++++ 45 files changed, 764 insertions(+), 56 deletions(-) diff --git a/packages/core/core-flows/src/inventory/steps/adjust-inventory-levels.ts b/packages/core/core-flows/src/inventory/steps/adjust-inventory-levels.ts index ce96f67525..1dafde24f5 100644 --- a/packages/core/core-flows/src/inventory/steps/adjust-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/steps/adjust-inventory-levels.ts @@ -3,14 +3,30 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { MathBN, Modules } from "@medusajs/framework/utils" +/** + * The data to adjust the inventory levels. + */ +export type AdjustInventoryLevelsStepInput = InventoryTypes.BulkAdjustInventoryLevelInput[] + export const adjustInventoryLevelsStepId = "adjust-inventory-levels-step" /** - * This step adjusts one or more inventory levels. + * This step adjusts the stocked quantity of one or more inventory levels. You can + * pass a positive value in `adjustment` to add to the stocked quantity, or a negative value to + * subtract from the stocked quantity. + * + * @example + * const data = adjustInventoryLevelsStep([ + * { + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * adjustment: 10, + * } + * ]) */ export const adjustInventoryLevelsStep = createStep( adjustInventoryLevelsStepId, async ( - input: InventoryTypes.BulkAdjustInventoryLevelInput[], + input: AdjustInventoryLevelsStepInput, { container } ) => { const inventoryService: IInventoryService = container.resolve( diff --git a/packages/core/core-flows/src/inventory/steps/attach-inventory-items.ts b/packages/core/core-flows/src/inventory/steps/attach-inventory-items.ts index a1dd5a771e..1b365d9ce6 100644 --- a/packages/core/core-flows/src/inventory/steps/attach-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/steps/attach-inventory-items.ts @@ -2,18 +2,37 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" +/** + * The data to attach inventory items to variants. + */ +export type AttachInventoryItemToVariantsStepInput = { + /** + * The inventory item ID to attach to the variant. + */ + inventoryItemId: string + /** + * The variant ID to attach the inventory item to. + */ + tag: string +}[] + export const attachInventoryItemToVariantsStepId = "attach-inventory-items-to-variants-step" /** * This step creates one or more links between variant and inventory item records. + * + * @example + * const data = attachInventoryItemToVariants([ + * { + * inventoryItemId: "iitem_123", + * tag: "variant_123" + * } + * ]) */ export const attachInventoryItemToVariants = createStep( attachInventoryItemToVariantsStepId, async ( - input: { - inventoryItemId: string - tag?: string - }[], + input: AttachInventoryItemToVariantsStepInput, { container } ) => { const remoteLink = container.resolve(ContainerRegistrationKeys.LINK) diff --git a/packages/core/core-flows/src/inventory/steps/create-inventory-items.ts b/packages/core/core-flows/src/inventory/steps/create-inventory-items.ts index 77eba581b5..1da0083c6b 100644 --- a/packages/core/core-flows/src/inventory/steps/create-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/steps/create-inventory-items.ts @@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { IInventoryService, InventoryTypes } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" +/** + * The data to create the inventory items. + */ +export type CreateInventoryItemsStepInput = InventoryTypes.CreateInventoryItemInput[] + export const createInventoryItemsStepId = "create-inventory-items" /** * This step creates one or more inventory items. */ export const createInventoryItemsStep = createStep( createInventoryItemsStepId, - async (data: InventoryTypes.CreateInventoryItemInput[], { container }) => { + async (data: CreateInventoryItemsStepInput, { container }) => { const inventoryService: IInventoryService = container.resolve( Modules.INVENTORY ) diff --git a/packages/core/core-flows/src/inventory/steps/create-inventory-levels.ts b/packages/core/core-flows/src/inventory/steps/create-inventory-levels.ts index e4050c2582..f409c9e80a 100644 --- a/packages/core/core-flows/src/inventory/steps/create-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/steps/create-inventory-levels.ts @@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to create the inventory levels. + */ +export type CreateInventoryLevelsStepInput = InventoryTypes.CreateInventoryLevelInput[] + export const createInventoryLevelsStepId = "create-inventory-levels" /** * This step creates one or more inventory levels. */ export const createInventoryLevelsStep = createStep( createInventoryLevelsStepId, - async (data: InventoryTypes.CreateInventoryLevelInput[], { container }) => { + async (data: CreateInventoryLevelsStepInput, { container }) => { const service = container.resolve(Modules.INVENTORY) const inventoryLevels = await service.createInventoryLevels(data) return new StepResponse( diff --git a/packages/core/core-flows/src/inventory/steps/delete-inventory-items.ts b/packages/core/core-flows/src/inventory/steps/delete-inventory-items.ts index fbec629b91..9e497e25ba 100644 --- a/packages/core/core-flows/src/inventory/steps/delete-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/steps/delete-inventory-items.ts @@ -26,13 +26,18 @@ export const validateInventoryDeleteStep = createStep( } ) +/** + * The IDs of the inventory items to delete. + */ +export type DeleteInventoryItemStepInput = string[] + export const deleteInventoryItemStepId = "delete-inventory-item-step" /** * This step deletes one or more inventory items. */ export const deleteInventoryItemStep = createStep( deleteInventoryItemStepId, - async (ids: string[], { container }) => { + async (ids: DeleteInventoryItemStepInput, { container }) => { const inventoryService = container.resolve(Modules.INVENTORY) await inventoryService.softDeleteInventoryItems(ids) diff --git a/packages/core/core-flows/src/inventory/steps/delete-inventory-levels.ts b/packages/core/core-flows/src/inventory/steps/delete-inventory-levels.ts index aef65a5dc7..739ddff6af 100644 --- a/packages/core/core-flows/src/inventory/steps/delete-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/steps/delete-inventory-levels.ts @@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The IDs of inventory levels to delete. + */ +export type DeleteInventoryLevelsStepInput = string[] + export const deleteInventoryLevelsStepId = "delete-inventory-levels-step" /** * This step deletes one or more inventory levels. */ export const deleteInventoryLevelsStep = createStep( deleteInventoryLevelsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteInventoryLevelsStepInput, { container }) => { const service = container.resolve(Modules.INVENTORY) await service.softDeleteInventoryLevels(ids) diff --git a/packages/core/core-flows/src/inventory/steps/update-inventory-items.ts b/packages/core/core-flows/src/inventory/steps/update-inventory-items.ts index fabb65df9f..8a6170e5cf 100644 --- a/packages/core/core-flows/src/inventory/steps/update-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/steps/update-inventory-items.ts @@ -7,13 +7,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to update the inventory items. + */ +export type UpdateInventoryItemsStepInput = InventoryTypes.UpdateInventoryItemInput[] + export const updateInventoryItemsStepId = "update-inventory-items-step" /** * This step updates one or more inventory items. */ export const updateInventoryItemsStep = createStep( updateInventoryItemsStepId, - async (input: InventoryTypes.UpdateInventoryItemInput[], { container }) => { + async (input: UpdateInventoryItemsStepInput, { container }) => { const inventoryService = container.resolve( Modules.INVENTORY ) diff --git a/packages/core/core-flows/src/inventory/steps/update-inventory-levels.ts b/packages/core/core-flows/src/inventory/steps/update-inventory-levels.ts index 6233bd3625..3c4c002097 100644 --- a/packages/core/core-flows/src/inventory/steps/update-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/steps/update-inventory-levels.ts @@ -7,13 +7,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to update the inventory levels. + */ +export type UpdateInventoryLevelsStepInput = InventoryTypes.UpdateInventoryLevelInput[] + export const updateInventoryLevelsStepId = "update-inventory-levels-step" /** * This step updates one or more inventory levels. */ export const updateInventoryLevelsStep = createStep( updateInventoryLevelsStepId, - async (input: InventoryTypes.UpdateInventoryLevelInput[], { container }) => { + async (input: UpdateInventoryLevelsStepInput, { container }) => { const inventoryService: IInventoryService = container.resolve( Modules.INVENTORY ) diff --git a/packages/core/core-flows/src/inventory/steps/validate-inventory-items.ts b/packages/core/core-flows/src/inventory/steps/validate-inventory-items.ts index c01443a92d..706f03e4ab 100644 --- a/packages/core/core-flows/src/inventory/steps/validate-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/steps/validate-inventory-items.ts @@ -5,13 +5,19 @@ import { } from "@medusajs/framework/utils" import { createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the inventory items to validate. + */ +export type ValidateInventoryItemsStepInput = string[] + export const validateInventoryItemsId = "validate-inventory-items-step" /** * This step ensures that the inventory items with the specified IDs exist. + * If not valid, the step will throw an error. */ export const validateInventoryItems = createStep( validateInventoryItemsId, - async (id: string[], { container }) => { + async (id: ValidateInventoryItemsStepInput, { container }) => { const remoteQuery = container.resolve( ContainerRegistrationKeys.REMOTE_QUERY ) diff --git a/packages/core/core-flows/src/inventory/steps/validate-inventory-locations.ts b/packages/core/core-flows/src/inventory/steps/validate-inventory-locations.ts index aa33a69a42..e194b2d06a 100644 --- a/packages/core/core-flows/src/inventory/steps/validate-inventory-locations.ts +++ b/packages/core/core-flows/src/inventory/steps/validate-inventory-locations.ts @@ -7,13 +7,20 @@ import { import { InventoryTypes } from "@medusajs/framework/types" import { createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to validate the inventory levels. + */ +export type ValidateInventoryLocationsStepInput = InventoryTypes.CreateInventoryLevelInput[] + export const validateInventoryLocationsStepId = "validate-inventory-levels-step" /** - * This step ensures that the inventory levels exist for each specified pair of inventory item and location. + * This step ensures that the inventory levels exist for each + * specified pair of inventory item and location. If not, + * the step will throw an error. */ export const validateInventoryLocationsStep = createStep( validateInventoryLocationsStepId, - async (data: InventoryTypes.CreateInventoryLevelInput[], { container }) => { + async (data: ValidateInventoryLocationsStepInput, { container }) => { const remoteQuery = container.resolve( ContainerRegistrationKeys.REMOTE_QUERY ) diff --git a/packages/core/core-flows/src/inventory/steps/validate-singular-inventory-items-for-tags.ts b/packages/core/core-flows/src/inventory/steps/validate-singular-inventory-items-for-tags.ts index c63eda7214..22e89ca769 100644 --- a/packages/core/core-flows/src/inventory/steps/validate-singular-inventory-items-for-tags.ts +++ b/packages/core/core-flows/src/inventory/steps/validate-singular-inventory-items-for-tags.ts @@ -5,17 +5,33 @@ import { } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to validate inventory items for creation. + */ +export type ValidateInventoryItemsForCreateStepInput = { + /** + * The ID of the variant to validate. + */ + tag?: string +}[] + export const validateInventoryItemsForCreateStepId = "validate-inventory-items-for-create-step" /** * This step checks whether a variant already has an inventory item. + * If so, the step will throw an error. + * + * @example + * const data = validateInventoryItemsForCreate([ + * { + * tag: "variant_123" + * } + * ]) */ export const validateInventoryItemsForCreate = createStep( validateInventoryItemsForCreateStepId, async ( - input: { - tag?: string - }[], + input: ValidateInventoryItemsForCreateStepInput, { container } ) => { const remoteLink = container.resolve(ContainerRegistrationKeys.LINK) diff --git a/packages/core/core-flows/src/inventory/workflows/batch-inventory-item-levels.ts b/packages/core/core-flows/src/inventory/workflows/batch-inventory-item-levels.ts index 13ae451136..55e243c1d6 100644 --- a/packages/core/core-flows/src/inventory/workflows/batch-inventory-item-levels.ts +++ b/packages/core/core-flows/src/inventory/workflows/batch-inventory-item-levels.ts @@ -5,18 +5,25 @@ import { WorkflowData, WorkflowResponse, } from "@medusajs/framework/workflows-sdk" -import { BatchWorkflowInput, InventoryTypes } from "@medusajs/types" +import { BatchWorkflowInput, BatchWorkflowOutput, InventoryLevelDTO, InventoryTypes } from "@medusajs/types" import { createInventoryLevelsStep, updateInventoryLevelsStep } from "../steps" import { deleteInventoryLevelsWorkflow } from "./delete-inventory-levels" +/** + * The data to manage the inventory levels in bulk. + * + * @property create - The inventory levels to create. + * @property update - The inventory levels to update. + * @property delete - The IDs of inventory levels to delete. + */ export interface BatchInventoryItemLevelsWorkflowInput extends BatchWorkflowInput< InventoryTypes.CreateInventoryLevelInput, InventoryTypes.UpdateInventoryLevelInput > { /** - * If true, the workflow will force deletion of the inventory levels, even - * if they have a non-zero stocked quantity. It false, the workflow will + * If true, the workflow will force the deletion of the inventory levels, even + * if they have a non-zero stocked quantity. If false, the workflow will * not delete the inventory levels if they have a non-zero stocked quantity. * * Inventory levels that have reserved or incoming items at the location @@ -27,9 +34,50 @@ export interface BatchInventoryItemLevelsWorkflowInput force?: boolean } +/** + * The result of managing inventory levels in bulk. + * + * @property created - The inventory levels that were created. + * @property updated - The inventory levels that were updated. + * @property deleted - The IDs of the inventory levels that were deleted. + */ +export type BatchInventoryItemLevelsWorkflowOutput = BatchWorkflowOutput + export const batchInventoryItemLevelsWorkflowId = "batch-inventory-item-levels-workflow" +/** + * This workflow creates, updates and deletes inventory levels in bulk. + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to manage inventory levels in your custom flows. + * + * @example + * const { result } = await batchInventoryItemLevelsWorkflow(container) + * .run({ + * input: { + * create: [ + * { + * inventory_item_id: "iitem_123", + * location_id: "sloc_123" + * } + * ], + * update: [ + * { + * id: "iilev_123", + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * stocked_quantity: 10 + * } + * ], + * delete: ["iilev_321"] + * } + * }) + * + * @summary + * + * Manage inventory levels in bulk. + */ export const batchInventoryItemLevelsWorkflow = createWorkflow( batchInventoryItemLevelsWorkflowId, (input: WorkflowData) => { @@ -61,7 +109,7 @@ export const batchInventoryItemLevelsWorkflow = createWorkflow( created: data.res[0], updated: data.res[1], deleted: data.input.delete, - } + } as BatchInventoryItemLevelsWorkflowOutput }) ) } diff --git a/packages/core/core-flows/src/inventory/workflows/create-inventory-items.ts b/packages/core/core-flows/src/inventory/workflows/create-inventory-items.ts index c8af5a0d71..305291d3aa 100644 --- a/packages/core/core-flows/src/inventory/workflows/create-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/workflows/create-inventory-items.ts @@ -9,12 +9,24 @@ import { createInventoryItemsStep } from "../steps" import { InventoryTypes } from "@medusajs/framework/types" import { createInventoryLevelsWorkflow } from "./create-inventory-levels" +/** + * The inventory level to create. + */ type LocationLevelWithoutInventory = Omit< InventoryTypes.CreateInventoryLevelInput, "inventory_item_id" > +/** + * The data to create the inventory items. + */ export interface CreateInventoryItemsWorkflowInput { + /** + * The items to create. + */ items: (InventoryTypes.CreateInventoryItemInput & { + /** + * The inventory levels of the inventory item. + */ location_levels?: LocationLevelWithoutInventory[] })[] } @@ -68,7 +80,32 @@ const buildInventoryLevelsInput = (data: { export const createInventoryItemsWorkflowId = "create-inventory-items-workflow" /** - * This workflow creates one or more inventory items. + * This workflow creates one or more inventory items. It's used by the + * [Create Inventory Item Admin API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to create inventory items in your custom flows. + * + * @example + * const { result } = await createInventoryItemsWorkflow(container) + * .run({ + * input: { + * items: [ + * { + * sku: "shirt", + * location_levels: [ + * { + * location_id: "sloc_123", + * } + * ] + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more inventory items. */ export const createInventoryItemsWorkflow = createWorkflow( createInventoryItemsWorkflowId, diff --git a/packages/core/core-flows/src/inventory/workflows/create-inventory-levels.ts b/packages/core/core-flows/src/inventory/workflows/create-inventory-levels.ts index 4e18746868..36edc9f99e 100644 --- a/packages/core/core-flows/src/inventory/workflows/create-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/workflows/create-inventory-levels.ts @@ -9,13 +9,40 @@ import { validateInventoryLocationsStep, } from "../steps" +/** + * The data to create the inventory levels. + */ export interface CreateInventoryLevelsWorkflowInput { + /** + * The inventory levels to create. + */ inventory_levels: InventoryTypes.CreateInventoryLevelInput[] } export const createInventoryLevelsWorkflowId = "create-inventory-levels-workflow" /** - * This workflow creates one or more inventory levels. + * This workflow creates one or more inventory levels. It's used by the + * [Create Inventory Level API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsidlocationlevels). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to create inventory levels in your custom flows. + * + * @example + * const { result } = await createInventoryLevelsWorkflow(container) + * .run({ + * input: { + * inventory_levels: [ + * { + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more inventory levels. */ export const createInventoryLevelsWorkflow = createWorkflow( createInventoryLevelsWorkflowId, diff --git a/packages/core/core-flows/src/inventory/workflows/delete-inventory-items.ts b/packages/core/core-flows/src/inventory/workflows/delete-inventory-items.ts index 7d34b8b191..53ce6dcd30 100644 --- a/packages/core/core-flows/src/inventory/workflows/delete-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/workflows/delete-inventory-items.ts @@ -9,13 +9,39 @@ import { deleteInventoryItemStep, validateInventoryDeleteStep } from "../steps" import { removeRemoteLinkStep } from "../../common/steps/remove-remote-links" import { useQueryGraphStep } from "../../common" +/** + * The IDs of the inventory items to delete. + */ +export type DeleteInventoryItemWorkflowInput = string[] + +/** + * The IDs of deleted inventory items. + */ +export type DeleteInventoryItemWorkflowOutput = string[] + export const deleteInventoryItemWorkflowId = "delete-inventory-item-workflow" /** - * This workflow deletes one or more inventory items. + * This workflow deletes one or more inventory items. It's used by the + * [Delete Inventory Item Admin API Route](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to delete inventory items in your custom flows. + * + * @example + * const { result } = await deleteInventoryItemWorkflow(container) + * .run({ + * input: ["iitem_123"] + * }) + * + * @summary + * + * Delete one or more inventory items. */ export const deleteInventoryItemWorkflow = createWorkflow( deleteInventoryItemWorkflowId, - (input: WorkflowData): WorkflowResponse => { + (input: WorkflowData): WorkflowResponse< + DeleteInventoryItemWorkflowOutput + > => { const { data: inventoryItemsToDelete } = useQueryGraphStep({ entity: "inventory", fields: ["id", "reserved_quantity"], diff --git a/packages/core/core-flows/src/inventory/workflows/delete-inventory-levels.ts b/packages/core/core-flows/src/inventory/workflows/delete-inventory-levels.ts index 8e81007f42..1e437396f2 100644 --- a/packages/core/core-flows/src/inventory/workflows/delete-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/workflows/delete-inventory-levels.ts @@ -15,17 +15,48 @@ import { useRemoteQueryStep } from "../../common" import { deleteEntitiesStep } from "../../common/steps/delete-entities" /** - * This step validates that inventory levels are deletable. + * The data to validate the deletion of inventory levels. + */ +export type ValidateInventoryLevelsDeleteStepInput = { + /** + * The inventory levels to validate. + */ + inventoryLevels: InventoryLevelDTO[] + /** + * If true, the inventory levels will be deleted even if they have stocked items. + */ + force?: boolean +} + +/** + * This step validates that inventory levels are deletable. If the + * inventory levels have reserved or incoming items, or the force + * flag is not set and the inventory levels have stocked items, the + * step will throw an error. + * + * :::note + * + * You can retrieve an inventory level'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 = validateInventoryLevelsDelete({ + * inventoryLevels: [ + * { + * id: "iilev_123", + * // other inventory level details... + * } + * ] + * }) */ export const validateInventoryLevelsDelete = createStep( "validate-inventory-levels-delete", async function ({ inventoryLevels, force, - }: { - inventoryLevels: InventoryLevelDTO[] - force?: boolean - }) { + }: ValidateInventoryLevelsDeleteStepInput) { const undeleteableDueToReservation = inventoryLevels.filter( (i) => i.reserved_quantity > 0 || i.incoming_quantity > 0 ) @@ -60,15 +91,38 @@ export const validateInventoryLevelsDelete = createStep( } ) +/** + * The data to delete inventory levels. The inventory levels to be deleted + * are selected based on the filters that you specify. + */ export interface DeleteInventoryLevelsWorkflowInput extends FilterableInventoryLevelProps { + /** + * If true, the inventory levels will be deleted even if they have stocked items. + */ force?: boolean } export const deleteInventoryLevelsWorkflowId = "delete-inventory-levels-workflow" /** - * This workflow deletes one or more inventory levels. + * This workflow deletes one or more inventory levels. It's used by the + * [Delete Inventory Levels Admin API Route](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsidlocationlevelslocation_id). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to delete inventory levels in your custom flows. + * + * @example + * const { result } = await deleteInventoryLevelsWorkflow(container) + * .run({ + * input: { + * id: ["iilev_123", "iilev_321"], + * } + * }) + * + * @summary + * + * Delete one or more inventory levels. */ export const deleteInventoryLevelsWorkflow = createWorkflow( deleteInventoryLevelsWorkflowId, diff --git a/packages/core/core-flows/src/inventory/workflows/update-inventory-items.ts b/packages/core/core-flows/src/inventory/workflows/update-inventory-items.ts index 1ce5b82b92..eb46c75d25 100644 --- a/packages/core/core-flows/src/inventory/workflows/update-inventory-items.ts +++ b/packages/core/core-flows/src/inventory/workflows/update-inventory-items.ts @@ -7,18 +7,51 @@ import { import { InventoryTypes } from "@medusajs/framework/types" import { updateInventoryItemsStep } from "../steps" +/** + * The data to update the inventory items. + */ export interface UpdateInventoryItemsWorkflowInput { + /** + * The items to update. + */ updates: InventoryTypes.UpdateInventoryItemInput[] } + +/** + * The updated inventory items. + */ +export type UpdateInventoryItemsWorkflowOutput = InventoryTypes.InventoryItemDTO[] + export const updateInventoryItemsWorkflowId = "update-inventory-items-workflow" /** - * This workflow updates one or more inventory items. + * This workflow updates one or more inventory items. It's used by the + * [Update an Inventory Item Admin API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to update inventory items in your custom flows. + * + * @example + * const { result } = await updateInventoryItemsWorkflow(container) + * .run({ + * input: { + * updates: [ + * { + * id: "iitem_123", + * sku: "shirt", + * } + * ] + * } + * }) + * + * @summary + * + * Update one or more inventory items. */ export const updateInventoryItemsWorkflow = createWorkflow( updateInventoryItemsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateInventoryItemsStep(input.updates)) } ) diff --git a/packages/core/core-flows/src/inventory/workflows/update-inventory-levels.ts b/packages/core/core-flows/src/inventory/workflows/update-inventory-levels.ts index f4492f2cb7..1dd79e6577 100644 --- a/packages/core/core-flows/src/inventory/workflows/update-inventory-levels.ts +++ b/packages/core/core-flows/src/inventory/workflows/update-inventory-levels.ts @@ -7,19 +7,54 @@ import { import { updateInventoryLevelsStep } from "../steps/update-inventory-levels" +/** + * The data to update the inventory levels. + */ export interface UpdateInventoryLevelsWorkflowInput { + /** + * The inventory levels to update. + */ updates: InventoryTypes.UpdateInventoryLevelInput[] } + +/** + * The updated inventory levels. + */ +export type UpdateInventoryLevelsWorkflowOutput = InventoryLevelDTO[] + export const updateInventoryLevelsWorkflowId = "update-inventory-levels-workflow" /** - * This workflow updates one or more inventory levels. + * This workflow updates one or more inventory levels. It's used by the + * [Update Inventory Level Admin API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsidlocationlevelslocation_id). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to update inventory levels in your custom flows. + * + * @example + * const { result } = await updateInventoryLevelsWorkflow(container) + * .run({ + * input: { + * updates: [ + * { + * id: "iilev_123", + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * stocked_quantity: 10, + * } + * ] + * } + * }) + * + * @summary + * + * Update one or more inventory levels. */ export const updateInventoryLevelsWorkflow = createWorkflow( updateInventoryLevelsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateInventoryLevelsStep(input.updates)) } ) diff --git a/packages/core/core-flows/src/payment-collection/workflows/create-refund-reasons.ts b/packages/core/core-flows/src/payment-collection/workflows/create-refund-reasons.ts index 539e82c0a5..14f7e927d5 100644 --- a/packages/core/core-flows/src/payment-collection/workflows/create-refund-reasons.ts +++ b/packages/core/core-flows/src/payment-collection/workflows/create-refund-reasons.ts @@ -21,7 +21,8 @@ export type CreateRefundReasonsWorkflowInput = { export const createRefundReasonsWorkflowId = "create-refund-reasons-workflow" /** - * This workflow creates one or more refund reasons. + * This workflow creates one or more refund reasons. It's used by the + * [Create Refund Reason Admin API Route](https://docs.medusajs.com/api/admin#refund-reasons_postrefundreasons). * * You can use this workflow within your own customizations or custom workflows, allowing you * to create refund reasons in your custom flows. diff --git a/packages/core/core-flows/src/payment-collection/workflows/delete-refund-reasons.ts b/packages/core/core-flows/src/payment-collection/workflows/delete-refund-reasons.ts index 28915fb3b7..a5148a16e9 100644 --- a/packages/core/core-flows/src/payment-collection/workflows/delete-refund-reasons.ts +++ b/packages/core/core-flows/src/payment-collection/workflows/delete-refund-reasons.ts @@ -5,13 +5,39 @@ import { } from "@medusajs/framework/workflows-sdk" import { deleteRefundReasonsStep } from "../steps" +/** + * The data to delete refund reasons. + */ +export type DeleteRefundReasonsWorkflowInput = { + /** + * The refund reasons to delete. + */ + ids: string[] +} + export const deleteRefundReasonsWorkflowId = "delete-refund-reasons-workflow" /** - * This workflow deletes one or more refund reasons. + * This workflow deletes one or more refund reasons. It's used by the + * [Delete Refund Reason Admin API Route](https://docs.medusajs.com/api/admin#refund-reasons_deleterefundreasonsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to delete refund reasons in your custom flows. + * + * @example + * const { result } = await deleteRefundReasonsWorkflow(container) + * .run({ + * input: { + * ids: ["refres_123"] + * } + * }) + * + * @summary + * + * Delete refund reasons. */ export const deleteRefundReasonsWorkflow = createWorkflow( deleteRefundReasonsWorkflowId, - (input: WorkflowData<{ ids: string[] }>): WorkflowResponse => { + (input: WorkflowData): WorkflowResponse => { return new WorkflowResponse(deleteRefundReasonsStep(input.ids)) } ) diff --git a/packages/core/core-flows/src/payment-collection/workflows/update-refund-reasons.ts b/packages/core/core-flows/src/payment-collection/workflows/update-refund-reasons.ts index c329f1ebc3..ec439e5e6e 100644 --- a/packages/core/core-flows/src/payment-collection/workflows/update-refund-reasons.ts +++ b/packages/core/core-flows/src/payment-collection/workflows/update-refund-reasons.ts @@ -21,7 +21,8 @@ export type UpdateRefundReasonsWorkflowOutput = RefundReasonDTO[] export const updateRefundReasonsWorkflowId = "update-refund-reasons" /** - * This workflow updates one or more refund reasons. + * This workflow updates one or more refund reasons. It's used by the + * [Update Refund Reason Admin API Route](https://docs.medusajs.com/api/admin#refund-reasons_postrefundreasonsid). * * You can use this workflow within your own customizations or custom workflows, allowing you * to update refund reasons in your custom flows. diff --git a/packages/core/core-flows/src/reservation/steps/create-reservations.ts b/packages/core/core-flows/src/reservation/steps/create-reservations.ts index d186798b23..5aef2cca21 100644 --- a/packages/core/core-flows/src/reservation/steps/create-reservations.ts +++ b/packages/core/core-flows/src/reservation/steps/create-reservations.ts @@ -3,13 +3,27 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to create reservation items. + */ +export type CreateReservationsStepInput = InventoryTypes.CreateReservationItemInput[] + export const createReservationsStepId = "create-reservations-step" /** * This step creates one or more reservations. + * + * @example + * const data = createReservationsStep([ + * { + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * quantity: 1, + * } + * ]) */ export const createReservationsStep = createStep( createReservationsStepId, - async (data: InventoryTypes.CreateReservationItemInput[], { container }) => { + async (data: CreateReservationsStepInput, { container }) => { const service = container.resolve(Modules.INVENTORY) const locking = container.resolve(Modules.LOCKING) diff --git a/packages/core/core-flows/src/reservation/steps/delete-reservations-by-line-items.ts b/packages/core/core-flows/src/reservation/steps/delete-reservations-by-line-items.ts index dd5bddcdc6..a465909a6f 100644 --- a/packages/core/core-flows/src/reservation/steps/delete-reservations-by-line-items.ts +++ b/packages/core/core-flows/src/reservation/steps/delete-reservations-by-line-items.ts @@ -3,6 +3,11 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { IInventoryService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" +/** + * The IDs of the line items to delete reservations for. + */ +export type DeleteReservationsByLineItemsStepInput = string[] + export const deleteReservationsByLineItemsStepId = "delete-reservations-by-line-items" /** @@ -10,7 +15,7 @@ export const deleteReservationsByLineItemsStepId = */ export const deleteReservationsByLineItemsStep = createStep( deleteReservationsByLineItemsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteReservationsByLineItemsStepInput, { container }) => { const service = container.resolve(Modules.INVENTORY) await service.deleteReservationItemsByLineItem(ids) diff --git a/packages/core/core-flows/src/reservation/steps/delete-reservations.ts b/packages/core/core-flows/src/reservation/steps/delete-reservations.ts index 5906311e71..4e85addca1 100644 --- a/packages/core/core-flows/src/reservation/steps/delete-reservations.ts +++ b/packages/core/core-flows/src/reservation/steps/delete-reservations.ts @@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { IInventoryService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" +/** + * The IDs of the reservations to delete. + */ +export type DeleteReservationsStepInput = string[] + export const deleteReservationsStepId = "delete-reservations" /** * This step deletes one or more reservations. */ export const deleteReservationsStep = createStep( deleteReservationsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteReservationsStepInput, { container }) => { const service = container.resolve(Modules.INVENTORY) await service.softDeleteReservationItems(ids) diff --git a/packages/core/core-flows/src/reservation/steps/update-reservations.ts b/packages/core/core-flows/src/reservation/steps/update-reservations.ts index 1890ebfca5..7d85f50781 100644 --- a/packages/core/core-flows/src/reservation/steps/update-reservations.ts +++ b/packages/core/core-flows/src/reservation/steps/update-reservations.ts @@ -7,13 +7,26 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to update reservation items. + */ +export type UpdateReservationsStepInput = InventoryTypes.UpdateReservationItemInput[] + export const updateReservationsStepId = "update-reservations-step" /** * This step updates one or more reservations. + * + * @example + * const data = updateReservationsStep([ + * { + * id: "res_123", + * quantity: 1, + * } + * ]) */ export const updateReservationsStep = createStep( updateReservationsStepId, - async (data: InventoryTypes.UpdateReservationItemInput[], { container }) => { + async (data: UpdateReservationsStepInput, { container }) => { const inventoryModuleService = container.resolve( Modules.INVENTORY ) diff --git a/packages/core/core-flows/src/reservation/workflows/create-reservations.ts b/packages/core/core-flows/src/reservation/workflows/create-reservations.ts index aa24fef772..bac872b17a 100644 --- a/packages/core/core-flows/src/reservation/workflows/create-reservations.ts +++ b/packages/core/core-flows/src/reservation/workflows/create-reservations.ts @@ -9,7 +9,29 @@ import { createReservationsStep } from "../steps" export const createReservationsWorkflowId = "create-reservations-workflow" /** - * This workflow creates one or more reservations. + * This workflow creates one or more reservations. It's used by the + * [Create Reservations Admin API Route](https://docs.medusajs.com/api/admin#reservations_postreservations). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to create reservations in your custom flows. + * + * @example + * const { result } = await createReservationsWorkflow(container) + * .run({ + * input: { + * reservations: [ + * { + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more reservations. */ export const createReservationsWorkflow = createWorkflow( createReservationsWorkflowId, diff --git a/packages/core/core-flows/src/reservation/workflows/delete-reservations.ts b/packages/core/core-flows/src/reservation/workflows/delete-reservations.ts index c21a457b98..543538ea77 100644 --- a/packages/core/core-flows/src/reservation/workflows/delete-reservations.ts +++ b/packages/core/core-flows/src/reservation/workflows/delete-reservations.ts @@ -2,11 +2,35 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { deleteReservationsStep } from "../steps" -type WorkflowInput = { ids: string[] } +/** + * The data to delete the reservations. + */ +type WorkflowInput = { + /** + * The IDs of the reservations to delete. + */ + ids: string[] +} export const deleteReservationsWorkflowId = "delete-reservations" /** - * This workflow deletes one or more reservations. + * This workflow deletes one or more reservations. It's used by the + * [Delete Reservations Admin API Route](https://docs.medusajs.com/api/admin#reservations_deletereservationsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to delete reservations in your custom flows. + * + * @example + * const { result } = await deleteReservationsWorkflow(container) + * .run({ + * input: { + * ids: ["res_123"] + * } + * }) + * + * @summary + * + * Delete one or more reservations. */ export const deleteReservationsWorkflow = createWorkflow( deleteReservationsWorkflowId, diff --git a/packages/core/core-flows/src/reservation/workflows/update-reservations.ts b/packages/core/core-flows/src/reservation/workflows/update-reservations.ts index 47dde45582..1476a49f55 100644 --- a/packages/core/core-flows/src/reservation/workflows/update-reservations.ts +++ b/packages/core/core-flows/src/reservation/workflows/update-reservations.ts @@ -9,7 +9,28 @@ import { updateReservationsStep } from "../steps" export const updateReservationsWorkflowId = "update-reservations-workflow" /** - * This workflow updates one or more reservations. + * This workflow updates one or more reservations. It's used by the + * [Update Reservations Admin API Route](https://docs.medusajs.com/api/admin#reservations_postreservationsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to update reservations in your custom flows. + * + * @example + * const { result } = await updateReservationsWorkflow(container) + * .run({ + * input: { + * updates: [ + * { + * id: "res_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Update one or more reservations. */ export const updateReservationsWorkflow = createWorkflow( updateReservationsWorkflowId, diff --git a/packages/core/core-flows/src/stock-location/steps/associate-locations-with-fulfillment-sets.ts b/packages/core/core-flows/src/stock-location/steps/associate-locations-with-fulfillment-sets.ts index 4f34993d47..44468a1e94 100644 --- a/packages/core/core-flows/src/stock-location/steps/associate-locations-with-fulfillment-sets.ts +++ b/packages/core/core-flows/src/stock-location/steps/associate-locations-with-fulfillment-sets.ts @@ -1,9 +1,21 @@ import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to associate fulfillment sets with locations. + */ export interface AssociateFulfillmentSetsWithLocationStepInput { + /** + * The data to associate fulfillment sets with locations. + */ input: { + /** + * The ID of the location to associate the fulfillment sets with. + */ location_id: string + /** + * The IDs of the fulfillment sets to associate with the location. + */ fulfillment_set_ids: string[] }[] } diff --git a/packages/core/core-flows/src/stock-location/steps/create-stock-locations.ts b/packages/core/core-flows/src/stock-location/steps/create-stock-locations.ts index ff07d18ace..fbab2d79d4 100644 --- a/packages/core/core-flows/src/stock-location/steps/create-stock-locations.ts +++ b/packages/core/core-flows/src/stock-location/steps/create-stock-locations.ts @@ -6,13 +6,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The stock locations to create. + */ +export type CreateStockLocationsStepInput = CreateStockLocationInput[] + export const createStockLocationsStepId = "create-stock-locations" /** * This step creates one or more stock locations. */ export const createStockLocations = createStep( createStockLocationsStepId, - async (data: CreateStockLocationInput[], { container }) => { + async (data: CreateStockLocationsStepInput, { container }) => { const stockLocationService = container.resolve( Modules.STOCK_LOCATION ) diff --git a/packages/core/core-flows/src/stock-location/steps/delete-stock-locations.ts b/packages/core/core-flows/src/stock-location/steps/delete-stock-locations.ts index bb167477fe..578bdd5e7e 100644 --- a/packages/core/core-flows/src/stock-location/steps/delete-stock-locations.ts +++ b/packages/core/core-flows/src/stock-location/steps/delete-stock-locations.ts @@ -2,13 +2,18 @@ import { DeleteEntityInput } from "@medusajs/framework/modules-sdk" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of stock locations to delete. + */ +export type DeleteStockLocationsStepInput = string[] + export const deleteStockLocationsStepId = "delete-stock-locations-step" /** * This step deletes one or more stock locations. */ export const deleteStockLocationsStep = createStep( deleteStockLocationsStepId, - async (input: string[], { container }) => { + async (input: DeleteStockLocationsStepInput, { container }) => { const service = container.resolve(Modules.STOCK_LOCATION) const softDeletedEntities = await service.softDeleteStockLocations(input) diff --git a/packages/core/core-flows/src/stock-location/steps/update-stock-locations.ts b/packages/core/core-flows/src/stock-location/steps/update-stock-locations.ts index f9fed8a4c7..99e32bf0a1 100644 --- a/packages/core/core-flows/src/stock-location/steps/update-stock-locations.ts +++ b/packages/core/core-flows/src/stock-location/steps/update-stock-locations.ts @@ -8,14 +8,33 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to update stock locations. + */ interface StepInput { + /** + * The filters to select stock locations to update. + */ selector: FilterableStockLocationProps + /** + * The data to update stock locations with. + */ update: UpdateStockLocationInput } export const updateStockLocationsStepId = "update-stock-locations-step" /** * This step updates stock locations matching the specified filters. + * + * @example + * const data = updateStockLocationsStep({ + * selector: { + * id: "sloc_123" + * }, + * update: { + * name: "European Warehouse" + * } + * }) */ export const updateStockLocationsStep = createStep( updateStockLocationsStepId, diff --git a/packages/core/core-flows/src/stock-location/steps/upsert-stock-location-addresses.ts b/packages/core/core-flows/src/stock-location/steps/upsert-stock-location-addresses.ts index ec2c82c383..2ced463ea6 100644 --- a/packages/core/core-flows/src/stock-location/steps/upsert-stock-location-addresses.ts +++ b/packages/core/core-flows/src/stock-location/steps/upsert-stock-location-addresses.ts @@ -10,6 +10,11 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { Modules } from "@medusajs/framework/utils" +/** + * The data to upsert stock location addresses. + */ +export type UpsertStockLocationAddressesStepInput = UpsertStockLocationAddressInput[] + export const upsertStockLocationAddressesStepId = "upsert-stock-location-addresses-step" /** diff --git a/packages/core/core-flows/src/stock-location/workflows/create-location-fulfillment-set.ts b/packages/core/core-flows/src/stock-location/workflows/create-location-fulfillment-set.ts index 6fc13a04c0..471456782e 100644 --- a/packages/core/core-flows/src/stock-location/workflows/create-location-fulfillment-set.ts +++ b/packages/core/core-flows/src/stock-location/workflows/create-location-fulfillment-set.ts @@ -10,7 +10,27 @@ import { associateFulfillmentSetsWithLocationStep } from "../steps/associate-loc export const createLocationFulfillmentSetWorkflowId = "create-location-fulfillment-set" /** - * This workflow creates links between location and fulfillment set records. + * This workflow adds a fulfillment set to a stock location. It's used by the + * [Add Fulfillment Set to Stock Location Admin API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsidfulfillmentsets). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to add fulfillment sets to a stock location in your custom flows. + * + * @example + * const { result } = await createLocationFulfillmentSetWorkflow(container) + * .run({ + * input: { + * location_id: "sloc_123", + * fulfillment_set_data: { + * name: "Shipping", + * type: "shipping", + * } + * } + * }) + * + * @summary + * + * Add fulfillment set to a stock location. */ export const createLocationFulfillmentSetWorkflow = createWorkflow( createLocationFulfillmentSetWorkflowId, diff --git a/packages/core/core-flows/src/stock-location/workflows/create-stock-locations.ts b/packages/core/core-flows/src/stock-location/workflows/create-stock-locations.ts index 9b78fd5e76..2794fe2f0b 100644 --- a/packages/core/core-flows/src/stock-location/workflows/create-stock-locations.ts +++ b/packages/core/core-flows/src/stock-location/workflows/create-stock-locations.ts @@ -7,13 +7,39 @@ import { import { CreateStockLocationInput } from "@medusajs/framework/types" import { createStockLocations } from "../steps" +/** + * The data to create the stock locations. + */ export interface CreateStockLocationsWorkflowInput { + /** + * The stock locations to create. + */ locations: CreateStockLocationInput[] } export const createStockLocationsWorkflowId = "create-stock-locations-workflow" /** - * This workflow creates one or more stock locations. + * This workflow creates one or more stock locations. It's used by the + * [Create Stock Location Admin API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to create stock locations in your custom flows. + * + * @example + * const { result } = await createStockLocationsWorkflow(container) + * .run({ + * input: { + * locations: [ + * { + * name: "European Warehouse", + * } + * ] + * } + * }) + * + * @summary + * + * Create one or more stock locations. */ export const createStockLocationsWorkflow = createWorkflow( createStockLocationsWorkflowId, diff --git a/packages/core/core-flows/src/stock-location/workflows/delete-stock-locations.ts b/packages/core/core-flows/src/stock-location/workflows/delete-stock-locations.ts index 460696b66f..e7bf6ab2c0 100644 --- a/packages/core/core-flows/src/stock-location/workflows/delete-stock-locations.ts +++ b/packages/core/core-flows/src/stock-location/workflows/delete-stock-locations.ts @@ -3,13 +3,35 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { removeRemoteLinkStep } from "../../common/steps/remove-remote-links" import { deleteStockLocationsStep } from "../steps" +/** + * The data to delete stock locations. + */ export interface DeleteStockLocationWorkflowInput { + /** + * The IDs of the stock locations to delete. + */ ids: string[] } export const deleteStockLocationsWorkflowId = "delete-stock-locations-workflow" /** - * This workflow deletes one or more stock locations. + * This workflow deletes one or more stock locations. It's used by the + * [Delete Stock Location Admin API Route](https://docs.medusajs.com/api/admin#stock-locations_deletestocklocationsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to delete stock locations in your custom flows. + * + * @example + * const { result } = await deleteStockLocationsWorkflow(container) + * .run({ + * input: { + * ids: ["sloc_123"] + * } + * }) + * + * @summary + * + * Delete one or more stock locations. */ export const deleteStockLocationsWorkflow = createWorkflow( deleteStockLocationsWorkflowId, diff --git a/packages/core/core-flows/src/stock-location/workflows/link-sales-channels-to-stock-location.ts b/packages/core/core-flows/src/stock-location/workflows/link-sales-channels-to-stock-location.ts index db025d5bac..1de7c1f24b 100644 --- a/packages/core/core-flows/src/stock-location/workflows/link-sales-channels-to-stock-location.ts +++ b/packages/core/core-flows/src/stock-location/workflows/link-sales-channels-to-stock-location.ts @@ -6,14 +6,41 @@ import { detachLocationsFromSalesChannelsStep, } from "../../sales-channel" +/** + * The sales channels to manage for a stock location. + * + * @property id - The ID of the stock location. + * @property add - The IDs of the sales channels to add to the stock location. + * @property remove - The IDs of the sales channels to remove from the stock location. + */ +export type LinkSalesChannelsToStockLocationWorkflowInput = LinkWorkflowInput + export const linkSalesChannelsToStockLocationWorkflowId = "link-sales-channels-to-stock-location" /** - * This workflow creates and dismisses links between location and sales channel records. + * This workflow manages the sales channels of a stock location. It's used by the + * [Manage Sales Channels Admin API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsidsaleschannels). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to manage the sales channels of a stock location in your custom flows. + * + * @example + * const { result } = await linkSalesChannelsToStockLocationWorkflow(container) + * .run({ + * input: { + * id: "sloc_123", + * add: ["sc_123"], + * remove: ["sc_321"] + * } + * }) + * + * @summary + * + * Manage the sales channels of a stock location. */ export const linkSalesChannelsToStockLocationWorkflow = createWorkflow( linkSalesChannelsToStockLocationWorkflowId, - (input: WorkflowData): void => { + (input: WorkflowData): void => { const toAdd = transform({ input }, (data) => { return data.input.add?.map((salesChannelId) => ({ sales_channel_id: salesChannelId, diff --git a/packages/core/core-flows/src/stock-location/workflows/update-stock-locations.ts b/packages/core/core-flows/src/stock-location/workflows/update-stock-locations.ts index 6b4d264f77..a8cf12b4ce 100644 --- a/packages/core/core-flows/src/stock-location/workflows/update-stock-locations.ts +++ b/packages/core/core-flows/src/stock-location/workflows/update-stock-locations.ts @@ -15,13 +15,43 @@ import { useQueryGraphStep } from "../../common" import { updateStockLocationsStep } from "../steps" import { upsertStockLocationAddressesStep } from "../steps/upsert-stock-location-addresses" +/** + * The data to update the stock locations. + */ export interface UpdateStockLocationsWorkflowInput { + /** + * The filters to select the stock locations to update. + */ selector: FilterableStockLocationProps + /** + * The data to update the stock locations with. + */ update: UpdateStockLocationInput } export const updateStockLocationsWorkflowId = "update-stock-locations-workflow" /** - * This workflow updates stock locations matching the specified filters. + * This workflow updates stock locations matching the specified filters. It's used by the + * [Update Stock Location Admin API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsid). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to update stock locations in your custom flows. + * + * @example + * const { result } = await updateStockLocationsWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "sloc_123" + * }, + * update: { + * name: "European Warehouse" + * } + * } + * }) + * + * @summary + * + * Update stock locations. */ export const updateStockLocationsWorkflow = createWorkflow( updateStockLocationsWorkflowId, diff --git a/packages/core/types/src/inventory/mutations/inventory-item.ts b/packages/core/types/src/inventory/mutations/inventory-item.ts index 0bbc974a84..9a5b82d866 100644 --- a/packages/core/types/src/inventory/mutations/inventory-item.ts +++ b/packages/core/types/src/inventory/mutations/inventory-item.ts @@ -1,5 +1,11 @@ +/** + * The data to update in an inventory item. + */ export interface UpdateInventoryItemInput extends Partial { + /** + * The ID of the inventory item to update. + */ id: string } /** diff --git a/packages/core/types/src/inventory/mutations/inventory-level.ts b/packages/core/types/src/inventory/mutations/inventory-level.ts index 1d0e38cfb7..f58e432b55 100644 --- a/packages/core/types/src/inventory/mutations/inventory-level.ts +++ b/packages/core/types/src/inventory/mutations/inventory-level.ts @@ -59,6 +59,8 @@ export type BulkAdjustInventoryLevelInput = { /** * The quantity to adjust the inventory level by. + * If positive, the quantity will be added to the stocked quantity. + * If negative, the quantity will be subtracted from the stocked quantity. */ adjustment: BigNumberInput } diff --git a/packages/core/types/src/inventory/mutations/reservation-item.ts b/packages/core/types/src/inventory/mutations/reservation-item.ts index 35ab01d3f5..bae51d44e9 100644 --- a/packages/core/types/src/inventory/mutations/reservation-item.ts +++ b/packages/core/types/src/inventory/mutations/reservation-item.ts @@ -6,6 +6,9 @@ import { BigNumberInput } from "../../totals" * The attributes to update in a reservation item. */ export interface UpdateReservationItemInput { + /** + * The ID of the reservation to update. + */ id: string /** * The reserved quantity. diff --git a/packages/core/types/src/stock-location/common.ts b/packages/core/types/src/stock-location/common.ts index 4e3792f324..624676ac30 100644 --- a/packages/core/types/src/stock-location/common.ts +++ b/packages/core/types/src/stock-location/common.ts @@ -457,7 +457,14 @@ export type UpdateStockLocationAddressInput = StockLocationAddressInput & { id: string } +/** + * The stock location address to create or update. If the `id` property isn't provided, + * the stock location address is created. In that case, the `address_1` property is required. + */ export type UpsertStockLocationAddressInput = StockLocationAddressInput & { + /** + * The ID of the stock location address, if updating. + */ id?: string } diff --git a/packages/core/types/src/workflow/reservation/create-reservations.ts b/packages/core/types/src/workflow/reservation/create-reservations.ts index be7d53a454..163ff33979 100644 --- a/packages/core/types/src/workflow/reservation/create-reservations.ts +++ b/packages/core/types/src/workflow/reservation/create-reservations.ts @@ -1,7 +1,16 @@ import { CreateReservationItemInput, ReservationItemDTO } from "../../inventory" +/** + * The data to create the reservations. + */ export interface CreateReservationsWorkflowInput { + /** + * The reservations to create. + */ reservations: CreateReservationItemInput[] } +/** + * The created reservations. + */ export type CreateReservationsWorkflowOutput = ReservationItemDTO[] diff --git a/packages/core/types/src/workflow/reservation/update-reservations.ts b/packages/core/types/src/workflow/reservation/update-reservations.ts index d8f22cc332..8e422a1bb0 100644 --- a/packages/core/types/src/workflow/reservation/update-reservations.ts +++ b/packages/core/types/src/workflow/reservation/update-reservations.ts @@ -1,7 +1,16 @@ import { ReservationItemDTO, UpdateReservationItemInput } from "../../inventory" +/** + * The data to update the reservations. + */ export interface UpdateReservationsWorkflowInput { + /** + * The reservations to update. + */ updates: UpdateReservationItemInput[] } +/** + * The updated reservations. + */ export type UpdateReservationsWorkflowOutput = ReservationItemDTO[] diff --git a/packages/core/types/src/workflows/stock-locations/mutations.ts b/packages/core/types/src/workflows/stock-locations/mutations.ts index ba2cac3c7a..14618ff5fb 100644 --- a/packages/core/types/src/workflows/stock-locations/mutations.ts +++ b/packages/core/types/src/workflows/stock-locations/mutations.ts @@ -1,7 +1,22 @@ +/** + * The data to add a fulfillment set to a stock location. + */ export interface CreateLocationFulfillmentSetWorkflowInputDTO { + /** + * The ID of the stock location to add the fulfillment set to. + */ location_id: string + /** + * The data of the fulfillment set to add. + */ fulfillment_set_data: { + /** + * The name of the fulfillment set. + */ name: string + /** + * The type of the fulfillment set. + */ type: string } }