From 47802261450f194fae1a80fd0dd880732a48733c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 7 Apr 2025 14:49:24 +0300 Subject: [PATCH] chore(core-flows): added TSDocs for setPricingContext hooks (#12100) --- .../src/cart/workflows/add-to-cart.ts | 34 ++++++++++++++++++ .../src/cart/workflows/create-carts.ts | 34 ++++++++++++++++++ .../list-shipping-options-for-cart.ts | 35 +++++++++++++++++++ .../src/cart/workflows/refresh-cart-items.ts | 35 +++++++++++++++++++ .../workflows/update-line-item-in-cart.ts | 34 ++++++++++++++++++ .../src/order/workflows/add-line-items.ts | 35 +++++++++++++++++++ .../claim/update-claim-shipping-method.ts | 35 +++++++++++++++++++ .../src/order/workflows/create-order.ts | 34 ++++++++++++++++++ .../update-exchange-shipping-method.ts | 35 +++++++++++++++++++ .../create-order-edit-shipping-method.ts | 35 +++++++++++++++++++ .../update-order-edit-shipping-method.ts | 35 +++++++++++++++++++ .../return/create-complete-return.ts | 35 +++++++++++++++++++ .../return/update-return-shipping-method.ts | 35 +++++++++++++++++++ 13 files changed, 451 insertions(+) diff --git a/packages/core/core-flows/src/cart/workflows/add-to-cart.ts b/packages/core/core-flows/src/cart/workflows/add-to-cart.ts index 190a963f94..8fe76f4a11 100644 --- a/packages/core/core-flows/src/cart/workflows/add-to-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/add-to-cart.ts @@ -70,6 +70,40 @@ export const addToCartWorkflowId = "add-to-cart" * Add a line item to a cart. * * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution. + * @property hooks.setPricingContext - This hook is executed after the cart is retrieved and before the line items are created. You can consume this hook to return any custom context useful for the prices retrieval of the variants to be added to the cart. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { addToCartWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * addToCartWorkflow.hooks.setPricingContext(( + * { cart, variantIds, items, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The variants' prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const addToCartWorkflow = createWorkflow( addToCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/create-carts.ts b/packages/core/core-flows/src/cart/workflows/create-carts.ts index 6e68f3b1b5..f2316302dc 100644 --- a/packages/core/core-flows/src/cart/workflows/create-carts.ts +++ b/packages/core/core-flows/src/cart/workflows/create-carts.ts @@ -77,6 +77,40 @@ export const createCartWorkflowId = "create-cart" * * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution. * @property hooks.cartCreated - This hook is executed after a cart is created. You can consume this hook to perform custom actions on the created cart. + * @property hooks.setPricingContext - This hook is executed after the cart is retrieved and before the line items are created. You can consume this hook to return any custom context useful for the prices retrieval of the variants to be added to the cart. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { createCartWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * createCartWorkflow.hooks.setPricingContext(( + * { region, variantIds, salesChannel, customerData, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The variants' prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const createCartWorkflow = createWorkflow( createCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts index abdbc339d2..e95e645c15 100644 --- a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts @@ -43,6 +43,41 @@ export const listShippingOptionsForCartWorkflowId = * @summary * * List a cart's shipping options. + * + * @property hooks.setPricingContext - This hook is executed before the shipping options are retrieved. You can consume this hook to return any custom context useful for the prices retrieval of shipping options. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { listShippingOptionsForCartWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * listShippingOptionsForCartWorkflow.hooks.setPricingContext(( + * { cart, fulfillmentSetIds, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The shipping options' prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const listShippingOptionsForCartWorkflow = createWorkflow( listShippingOptionsForCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts b/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts index 0977daa6d8..ea6029e4a1 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts +++ b/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts @@ -89,6 +89,41 @@ export const refreshCartItemsWorkflowId = "refresh-cart-items" * @summary * * Refresh a cart's details after an update. + * + * @property hooks.setPricingContext - This hook is executed before the cart is refreshed. You can consume this hook to return any custom context useful for the prices retrieval of the variants in the cart. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { refreshCartItemsWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * refreshCartItemsWorkflow.hooks.setPricingContext(( + * { cart, items, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The variants' prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: * */ export const refreshCartItemsWorkflow = createWorkflow( diff --git a/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts b/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts index af1d4889df..f1e836dea4 100644 --- a/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts @@ -50,6 +50,40 @@ export const updateLineItemInCartWorkflowId = "update-line-item-in-cart" * Update a cart's line item. * * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution. + * @property hooks.setPricingContext - This hook is executed before the cart is updated. You can consume this hook to return any custom context useful for the prices retrieval of the line item's variant. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { addToCartWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * addToCartWorkflow.hooks.setPricingContext(( + * { cart, variantIds, items, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The variant's prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const updateLineItemInCartWorkflow = createWorkflow( updateLineItemInCartWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/add-line-items.ts b/packages/core/core-flows/src/order/workflows/add-line-items.ts index 3b7d20f8be..2789f9fb72 100644 --- a/packages/core/core-flows/src/order/workflows/add-line-items.ts +++ b/packages/core/core-flows/src/order/workflows/add-line-items.ts @@ -84,6 +84,41 @@ export const addOrderLineItemsWorkflowId = "order-add-line-items" * @summary * * Add line items to an order. + * + * @property hooks.setPricingContext - This hook is executed after the order is retrieved and before the line items are created. You can consume this hook to return any custom context useful for the prices retrieval of the variants to be added to the order. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { addOrderLineItemsWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * addOrderLineItemsWorkflow.hooks.setPricingContext(( + * { order, variantIds, region, customerData, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The variants' prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const addOrderLineItemsWorkflow = createWorkflow( addOrderLineItemsWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts b/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts index 584b233a4d..9187cd23d4 100644 --- a/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts @@ -130,6 +130,41 @@ export const updateClaimShippingMethodWorkflowId = * @summary * * Update an inbound or outbound shipping method of a claim. + * + * @property hooks.setPricingContext - This hook is executed before the shipping method is updated. You can consume this hook to return any custom context useful for the prices retrieval of the shipping method's option. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { updateClaimShippingMethodWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * updateClaimShippingMethodWorkflow.hooks.setPricingContext(( + * { order_claim, order_change, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The price of the shipping method's option will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const updateClaimShippingMethodWorkflow = createWorkflow( updateClaimShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/create-order.ts b/packages/core/core-flows/src/order/workflows/create-order.ts index 228408b1df..d99ea0f137 100644 --- a/packages/core/core-flows/src/order/workflows/create-order.ts +++ b/packages/core/core-flows/src/order/workflows/create-order.ts @@ -128,6 +128,40 @@ export const createOrdersWorkflowId = "create-orders" * Create an order. * * @property hooks.orderCreated - This hook is executed after the order is created. You can consume this hook to perform custom actions on the created order. + * @property hooks.setPricingContext - This hook is executed after the order is retrieved and before the line items are created. You can consume this hook to return any custom context useful for the prices retrieval of the variants to be added to the order. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { createOrderWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * createOrderWorkflow.hooks.setPricingContext(( + * { variantIds, region, customerData, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The variants' prices will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const createOrderWorkflow = createWorkflow( createOrdersWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts b/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts index 0ee1e29112..05886f28ca 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts @@ -134,6 +134,41 @@ export const updateExchangeShippingMethodWorkflowId = * @summary * * Update an exchange's inbound or outbound shipping method. + * + * @property hooks.setPricingContext - This hook is executed before the shipping method is updated. You can consume this hook to return any custom context useful for the prices retrieval of the shipping method's option. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { updateExchangeShippingMethodWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * updateExchangeShippingMethodWorkflow.hooks.setPricingContext(( + * { order_exchange, order_change, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The price of the shipping method's option will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const updateExchangeShippingMethodWorkflow = createWorkflow( updateExchangeShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts b/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts index 1b40696def..3a9221ad68 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts @@ -113,6 +113,41 @@ export const createOrderEditShippingMethodWorkflowId = * @summary * * Create a shipping method for an order edit. + * + * @property hooks.setPricingContext - This hook is executed before the shipping method is created. You can consume this hook to return any custom context useful for the prices retrieval of the shipping method's option. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { createOrderEditShippingMethodWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * createOrderEditShippingMethodWorkflow.hooks.setPricingContext(( + * { order, shipping_option_id, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The price of the shipping method's option will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const createOrderEditShippingMethodWorkflow = createWorkflow( createOrderEditShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts index 2a28031188..dbf91c98fe 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts @@ -119,6 +119,41 @@ export const updateOrderEditShippingMethodWorkflowId = * @summary * * Update a shipping method of an order edit. + * + * @property hooks.setPricingContext - This hook is executed before the shipping method's option is retrieved. You can consume this hook to return any custom context useful for the prices retrieval of shipping method's option. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { updateOrderEditShippingMethodWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * updateOrderEditShippingMethodWorkflow.hooks.setPricingContext(( + * { order, order_change, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The price of the shipping method's option will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const updateOrderEditShippingMethodWorkflow = createWorkflow( updateOrderEditShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts b/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts index ebc69471dc..ee4ef89172 100644 --- a/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts @@ -311,6 +311,41 @@ export const createAndCompleteReturnOrderWorkflowId = * @summary * * Create and complete a return for an order. + * + * @property hooks.setPricingContext - This hook is executed before the return's shipping method is created. You can consume this hook to return any custom context useful for the prices retrieval of the shipping method's option. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { createAndCompleteReturnOrderWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * createAndCompleteReturnOrderWorkflow.hooks.setPricingContext(( + * { order, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The price of the shipping method's option will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const createAndCompleteReturnOrderWorkflow = createWorkflow( createAndCompleteReturnOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts b/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts index 595b5520ab..89af1b3535 100644 --- a/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts @@ -130,6 +130,41 @@ export const updateReturnShippingMethodWorkflowId = * @summary * * Update the shipping method of a return. + * + * @property hooks.setPricingContext - This hook is executed before the shipping method is created. You can consume this hook to return any custom context useful for the prices retrieval of the shipping method's option. + * + * For example, assuming you have the following custom pricing rule: + * + * ```json + * { + * "attribute": "location_id", + * "operator": "eq", + * "value": "sloc_123", + * } + * ``` + * + * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation: + * + * ```ts + * import { updateReturnShippingMethodWorkflow } from "@medusajs/medusa/core-flows"; + * import { StepResponse } from "@medusajs/workflows-sdk"; + * + * updateReturnShippingMethodWorkflow.hooks.setPricingContext(( + * { order_return, order_change, additional_data }, { container } + * ) => { + * return new StepResponse({ + * location_id: "sloc_123", // Special price for in-store purchases + * }); + * }); + * ``` + * + * The price of the shipping method's option will now be retrieved using the context you return. + * + * :::note + * + * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation. + * + * ::: */ export const updateReturnShippingMethodWorkflow = createWorkflow( updateReturnShippingMethodWorkflowId,