From 8e7c13862dde038daabf57bc214619965461fe5e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 16 Jan 2025 20:12:25 +0200 Subject: [PATCH] chore(core-flows): improve TSDocs for payment workflows / steps (#10998) --- .../workflows/add-shipping-method-to-cart.ts | 2 +- .../src/cart/workflows/add-to-cart.ts | 2 +- .../src/cart/workflows/complete-cart.ts | 2 +- .../workflows/confirm-variant-inventory.ts | 2 +- .../create-payment-collection-for-cart.ts | 2 +- ...-shipping-options-for-cart-with-pricing.ts | 2 +- .../list-shipping-options-for-cart.ts | 2 +- .../src/cart/workflows/refresh-cart-items.ts | 2 +- .../refresh-cart-shipping-methods.ts | 2 +- .../workflows/refresh-payment-collection.ts | 2 +- .../cart/workflows/transfer-cart-customer.ts | 2 +- .../cart/workflows/update-cart-promotions.ts | 2 +- .../workflows/update-line-item-in-cart.ts | 2 +- .../src/cart/workflows/update-tax-lines.ts | 2 +- .../workflows/batch-shipping-option-rules.ts | 2 +- .../calculate-shipping-options-prices.ts | 2 +- .../workflows/cancel-fulfillment.ts | 2 +- .../workflows/create-fulfillment.ts | 2 +- .../workflows/create-return-fulfillment.ts | 2 +- .../workflows/create-service-zones.ts | 2 +- .../fulfillment/workflows/create-shipment.ts | 2 +- .../workflows/create-shipping-options.ts | 2 +- .../workflows/create-shipping-profiles.ts | 2 +- .../workflows/delete-fulfillment-sets.ts | 2 +- .../workflows/delete-service-zones.ts | 2 +- .../workflows/delete-shipping-options.ts | 2 +- .../workflows/update-fulfillment.ts | 2 +- .../workflows/update-service-zones.ts | 2 +- .../workflows/update-shipping-options.ts | 2 +- .../workflows/update-shipping-profiles.ts | 2 +- .../steps/create-payment-session.ts | 27 +++++- .../steps/create-refund-reasons.ts | 7 +- .../steps/delete-payment-sessions.ts | 8 +- .../steps/delete-refund-reasons.ts | 7 +- .../steps/update-payment-collection.ts | 19 ++++ .../steps/update-refund-reasons.ts | 7 +- .../validate-deleted-payment-sessions.ts | 16 ++++ .../workflows/create-payment-session.ts | 36 +++++++- .../workflows/create-refund-reasons.ts | 31 ++++++- .../workflows/delete-payment-sessions.ts | 24 ++++- .../workflows/update-refund-reasons.ts | 32 ++++++- .../steps/authorize-payment-session.ts | 16 ++++ .../src/payment/steps/cancel-payment.ts | 6 ++ .../src/payment/steps/capture-payment.ts | 12 +++ .../src/payment/steps/refund-payment.ts | 12 +++ .../src/payment/steps/refund-payments.ts | 24 +++-- .../src/payment/workflows/capture-payment.ts | 42 +++++++-- .../src/payment/workflows/process-payment.ts | 27 ++++++ .../src/payment/workflows/refund-payment.ts | 89 ++++++++++++++++--- .../src/payment/workflows/refund-payments.ts | 66 +++++++++++--- .../batch-link-products-collection.ts | 2 +- .../workflows/batch-product-variants.ts | 2 +- .../workflows/batch-products-in-category.ts | 2 +- .../src/product/workflows/batch-products.ts | 2 +- .../workflows/upsert-variant-prices.ts | 2 +- 55 files changed, 500 insertions(+), 78 deletions(-) diff --git a/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts b/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts index f16cab4781..dfb991dedb 100644 --- a/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts @@ -51,7 +51,7 @@ export const addShippingMethodToCartWorkflowId = "add-shipping-method-to-cart" * This workflow adds a shipping method to a cart. It's executed by the * [Add Shipping Method Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidshippingmethods). * - * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding a shipping method to the cart. + * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding a shipping method to the cart. * * @example * const { result } = await addShippingMethodToCartWorkflow(container) 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 6bce74e49d..75fde56594 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 @@ -38,7 +38,7 @@ export const addToCartWorkflowId = "add-to-cart" * This workflow adds a product variant to a cart as a line item. It's executed by the * [Add Line Item Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidlineitems). * - * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding an item to the cart. + * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding an item to the cart. * For example, you can use this workflow to add a line item to the cart with a custom price. * * @example diff --git a/packages/core/core-flows/src/cart/workflows/complete-cart.ts b/packages/core/core-flows/src/cart/workflows/complete-cart.ts index 0bcaefa3f3..0a96289e00 100644 --- a/packages/core/core-flows/src/cart/workflows/complete-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/complete-cart.ts @@ -60,7 +60,7 @@ export const completeCartWorkflowId = "complete-cart" * This workflow completes a cart and places an order for the customer. It's executed by the * [Complete Cart Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidcomplete). * - * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around completing a cart. + * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around completing a cart. * For example, in the [Subscriptions recipe](https://docs.medusajs.com/resources/recipes/subscriptions/examples/standard#create-workflow), * this workflow is used within another workflow that creates a subscription order. * diff --git a/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts b/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts index 55b5fb0c13..3902229d73 100644 --- a/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts +++ b/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts @@ -59,7 +59,7 @@ export const confirmVariantInventoryWorkflowId = "confirm-item-inventory" * * ::: * - * You can use this workflow within your own custom workflows, allowing you to check whether a product variant has enough inventory quantity before adding them to the cart. + * You can use this workflow within your own customizations or custom workflows, allowing you to check whether a product variant has enough inventory quantity before adding them to the cart. * * @example * You can retrieve a variant's required details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query): diff --git a/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts b/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts index 6e4645a44b..4ec277172d 100644 --- a/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts @@ -61,7 +61,7 @@ export const createPaymentCollectionForCartWorkflowId = * This workflow creates a payment collection for a cart. It's executed by the * [Create Payment Collection Store API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollections). * - * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding creating a payment collection for a cart. + * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding creating a payment collection for a cart. * * @example * const { result } = await createPaymentCollectionForCartWorkflow(container) diff --git a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts index 6fe22bb779..a8b00dc037 100644 --- a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts +++ b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts @@ -48,7 +48,7 @@ export const listShippingOptionsForCartWithPricingWorkflowId = * This workflow is executed in other cart-related workflows, such as {@link addShippingMethodToCartWorkflow} to retrieve the * price of the shipping method being added to the cart. * - * You can use this workflow within your own custom workflows, allowing you to retrieve the shipping options of a cart and their prices + * You can use this workflow within your own customizations or custom workflows, allowing you to retrieve the shipping options of a cart and their prices * in your custom flows. * * @example 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 1d80b1123a..18193c986a 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 @@ -22,7 +22,7 @@ export const listShippingOptionsForCartWorkflowId = * * ::: * - * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around to retrieve the shipping options of a cart + * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around to retrieve the shipping options of a cart * in your custom flows. * * @example 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 6dec0d0925..1a8ad28842 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 @@ -51,7 +51,7 @@ export const refreshCartItemsWorkflowId = "refresh-cart-items" * This workflow is used by other cart-related workflows, such as the {@link addToCartWorkflow} after an item * is added to the cart. * - * You can use this workflow within your own custom workflows, allowing you to refresh the cart after making updates to it in your + * You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart after making updates to it in your * custom flows. * * @example diff --git a/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts b/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts index 55f68141c6..cd43f3945f 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts +++ b/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts @@ -29,7 +29,7 @@ export const refreshCartShippingMethodsWorkflowId = * This workflow refreshes a cart's shipping methods, ensuring that their associated shipping options can still be used on the cart, * and retrieve their correct pricing after a cart update. This workflow is used by the {@link refreshCartItemsWorkflow}. * - * You can use this workflow within your own custom workflows, allowing you to refresh the cart's shipping method after making updates to the cart. + * You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart's shipping method after making updates to the cart. * * @example * const { result } = await refreshCartShippingMethodsWorkflow(container) diff --git a/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts b/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts index 66dccb8be8..e873df8202 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts +++ b/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts @@ -32,7 +32,7 @@ export const refreshPaymentCollectionForCartWorkflowId = * This workflow is used by other cart-related workflows, such as the {@link refreshCartItemsWorkflow} to refresh the cart's * payment collection after an update. * - * You can use this workflow within your own custom workflows, allowing you to refresh the cart's payment collection after making updates to it in your + * You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart's payment collection after making updates to it in your * custom flows. * * @example diff --git a/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts b/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts index 975192744a..afe1e24220 100644 --- a/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts +++ b/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts @@ -30,7 +30,7 @@ export const transferCartCustomerWorkflowId = "transfer-cart-customer" * adding the items to their cart, allowing you to transfer the cart's ownership to the logged-in customer. This workflow is used * by the [Set Cart's Customer Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidcustomer). * - * You can use this workflow within your own custom workflows, allowing you to set the cart's customer within your custom flows. + * You can use this workflow within your own customizations or custom workflows, allowing you to set the cart's customer within your custom flows. * * @example * const { result } = await transferCartCustomerWorkflow(container) diff --git a/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts b/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts index 3c8fb37d31..8eb5ca3f97 100644 --- a/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts +++ b/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts @@ -48,7 +48,7 @@ export const updateCartPromotionsWorkflowId = "update-cart-promotions" * that need to be applied to the cart's line items and shipping methods based on the promotions applied. This workflow is used by * [Add Promotions Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidpromotions). * - * You can use this workflow within your own custom workflows, allowing you to update a cart's promotions within your custom flows. + * You can use this workflow within your own customizations or custom workflows, allowing you to update a cart's promotions within your custom flows. * * @example * const { result } = await updateCartPromotionsWorkflow(container) 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 101b38093d..97631f0c45 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 @@ -27,7 +27,7 @@ export const updateLineItemInCartWorkflowId = "update-line-item-in-cart" * This workflow updates a line item's details in a cart. You can update the line item's quantity, unit price, and more. This workflow is executed * by the [Update Line Item Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidlineitemsline_id). * - * You can use this workflow within your own custom workflows, allowing you to update a line item's details in your custom flows. + * You can use this workflow within your own customizations or custom workflows, allowing you to update a line item's details in your custom flows. * * @example * const { result } = await updateLineItemInCartWorkflow(container) diff --git a/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts b/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts index c786269a8b..da289507b0 100644 --- a/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts +++ b/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts @@ -101,7 +101,7 @@ export const updateTaxLinesWorkflowId = "update-tax-lines" * This workflow updates a cart's tax lines that are applied on line items and shipping methods. You can update the line item's quantity, unit price, and more. This workflow is executed * by the [Calculate Taxes Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidtaxes). * - * You can use this workflow within your own custom workflows, allowing you to update a cart's tax lines in your custom flows. + * You can use this workflow within your own customizations or custom workflows, allowing you to update a cart's tax lines in your custom flows. * * @example * const { result } = await updateTaxLinesWorkflow(container) 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 ab18ff7f95..19052e6617 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 @@ -44,7 +44,7 @@ export const batchShippingOptionRulesWorkflowId = "batch-shipping-option-rules" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * manage shipping option rules within your custom flows. * * @example 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 bb255e0dc6..4d477492b8 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 @@ -22,7 +22,7 @@ export const calculateShippingOptionsPricesWorkflowId = * * ::: * - * You can use this workflow within your own custom workflows, allowing you to + * You can use this workflow within your own customizations or custom workflows, allowing you to * calculate the prices of shipping options within your custom flows. * * @example 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 931e8be5f1..7ac374643e 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts @@ -16,7 +16,7 @@ export const cancelFulfillmentWorkflowId = "cancel-fulfillment-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * cancel a fulfillment within your custom flows. * * @example 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 3cdef1ad2e..e1d9bf2eab 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts @@ -17,7 +17,7 @@ export const createFulfillmentWorkflowId = "create-fulfillment-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * create a fulfillment within your custom flows. * * :::note 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 161273ef46..8dbeda85f4 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 @@ -18,7 +18,7 @@ export const createReturnFulfillmentWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * create a fulfillment for a return within your custom flows. * * :::note 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 aafc43ba6e..53ebad0067 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 @@ -16,7 +16,7 @@ export const createServiceZonesWorkflowId = "create-service-zones-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * create service zones within your custom flows. * * @example 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 d8013ad6d9..542fa97fb3 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts @@ -13,7 +13,7 @@ export const createShipmentWorkflowId = "create-shipment-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * create shipments within your custom flows. * * @example 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 63dba9e4b3..1f566b2d63 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 @@ -25,7 +25,7 @@ export const createShippingOptionsWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * create shipping options within your custom flows. * * @example 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 a269d553ad..b37267915c 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 @@ -12,7 +12,7 @@ export const createShippingProfilesWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * create shipping profiles within your custom flows. * * @example 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 1998101f5a..edc0cbb9b0 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 @@ -19,7 +19,7 @@ export const deleteFulfillmentSetsWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * delete fulfillment sets within your custom flows. * * @example 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 854d50009a..a4278b83da 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 @@ -16,7 +16,7 @@ export const deleteServiceZonesWorkflowId = "delete-service-zones-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * delete service zones within your custom flows. * * @example 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 37aaca46fa..033314b32b 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 @@ -9,7 +9,7 @@ export const deleteShippingOptionsWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * delete shipping options within your custom flows. * * @example 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 a825708978..d23d90ba8c 100644 --- a/packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts +++ b/packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts @@ -11,7 +11,7 @@ export const updateFulfillmentWorkflowId = "update-fulfillment-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * update a fulfillment within your custom flows. * * @example 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 5341caee79..103c14024a 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 @@ -16,7 +16,7 @@ export const updateServiceZonesWorkflowId = "update-service-zones-workflow" * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * update service zones within your custom flows. * * @example 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 07a4cafa9f..667aeff3b8 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 @@ -25,7 +25,7 @@ export const updateShippingOptionsWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * update shipping options within your custom flows. * * @example 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 36c5269021..172588f14f 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 @@ -17,7 +17,7 @@ export const updateShippingProfilesWorkflowId = * 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 + * You can use this workflow within your own customizations or custom workflows, allowing you to * update shipping profiles within your custom flows. * * @example diff --git a/packages/core/core-flows/src/payment-collection/steps/create-payment-session.ts b/packages/core/core-flows/src/payment-collection/steps/create-payment-session.ts index 0d0e8474ac..6f5c9d6942 100644 --- a/packages/core/core-flows/src/payment-collection/steps/create-payment-session.ts +++ b/packages/core/core-flows/src/payment-collection/steps/create-payment-session.ts @@ -6,18 +6,43 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to create a payment session. + */ export interface CreatePaymentSessionStepInput { + /** + * The ID of the payment collection that the session belongs to. + */ payment_collection_id: string + /** + * The ID of the payment provider that the payment session is associated with. + */ provider_id: string + /** + * The payment session's amount. + */ amount: BigNumberInput + /** + * The currency code of the payment session. + * + * @example + * usd + */ currency_code: string + /** + * Additional context that's useful for the payment provider to process the payment session. + */ context?: PaymentProviderContext + /** + * Custom data relevant for the payment provider to process the payment session. + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/payment/payment-session#data-property). + */ data?: Record } export const createPaymentSessionStepId = "create-payment-session" /** - * This step creates a payment session. + * This step creates a payment session. */ export const createPaymentSessionStep = createStep( createPaymentSessionStepId, diff --git a/packages/core/core-flows/src/payment-collection/steps/create-refund-reasons.ts b/packages/core/core-flows/src/payment-collection/steps/create-refund-reasons.ts index 720d597e84..6484b73cc0 100644 --- a/packages/core/core-flows/src/payment-collection/steps/create-refund-reasons.ts +++ b/packages/core/core-flows/src/payment-collection/steps/create-refund-reasons.ts @@ -5,13 +5,18 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The refund reasons to create. + */ +export type CreateRefundReasonStepInput = CreateRefundReasonDTO[] + export const createRefundReasonStepId = "create-refund-reason" /** * This step creates one or more refund reasons. */ export const createRefundReasonStep = createStep( createRefundReasonStepId, - async (data: CreateRefundReasonDTO[], { container }) => { + async (data: CreateRefundReasonStepInput, { container }) => { const service = container.resolve(Modules.PAYMENT) const refundReasons = await service.createRefundReasons(data) diff --git a/packages/core/core-flows/src/payment-collection/steps/delete-payment-sessions.ts b/packages/core/core-flows/src/payment-collection/steps/delete-payment-sessions.ts index af6fbac177..f0b7a610cb 100644 --- a/packages/core/core-flows/src/payment-collection/steps/delete-payment-sessions.ts +++ b/packages/core/core-flows/src/payment-collection/steps/delete-payment-sessions.ts @@ -10,7 +10,13 @@ import { } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to delete payment sessions. + */ export interface DeletePaymentSessionStepInput { + /** + * The IDs of the payment sessions to delete. + */ ids: string[] } @@ -19,7 +25,7 @@ export const deletePaymentSessionsStepId = "delete-payment-sessions" * This step deletes one or more payment sessions. * * Note: This step should not be used alone as it doesn't consider a revert - * Use deletePaymentSessionsWorkflow instead that uses this step + * Use {@link deletePaymentSessionsWorkflow} instead, which uses this step. */ export const deletePaymentSessionsStep = createStep( deletePaymentSessionsStepId, diff --git a/packages/core/core-flows/src/payment-collection/steps/delete-refund-reasons.ts b/packages/core/core-flows/src/payment-collection/steps/delete-refund-reasons.ts index c34f2358d5..3221f5050e 100644 --- a/packages/core/core-flows/src/payment-collection/steps/delete-refund-reasons.ts +++ b/packages/core/core-flows/src/payment-collection/steps/delete-refund-reasons.ts @@ -2,13 +2,18 @@ import { IPaymentModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The refund reasons to delete. + */ +export type DeleteRefundReasonsStepInput = string[] + export const deleteRefundReasonsStepId = "delete-refund-reasons" /** * This step deletes one or more refund reasons. */ export const deleteRefundReasonsStep = createStep( deleteRefundReasonsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteRefundReasonsStepInput, { container }) => { const service = container.resolve(Modules.PAYMENT) await service.softDeleteRefundReasons(ids) diff --git a/packages/core/core-flows/src/payment-collection/steps/update-payment-collection.ts b/packages/core/core-flows/src/payment-collection/steps/update-payment-collection.ts index 636200e25e..71fbec14a8 100644 --- a/packages/core/core-flows/src/payment-collection/steps/update-payment-collection.ts +++ b/packages/core/core-flows/src/payment-collection/steps/update-payment-collection.ts @@ -10,14 +10,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to update a payment collection. + */ export interface UpdatePaymentCollectionStepInput { + /** + * The filters to select the payment collections to update. + */ selector: FilterablePaymentCollectionProps + /** + * The data to update in the selected payment collections. + */ update: PaymentCollectionUpdatableFields } export const updatePaymentCollectionStepId = "update-payment-collection" /** * This step updates payment collections matching the specified filters. + * + * @example + * const data = updatePaymentCollectionStep({ + * selector: { + * id: "paycol_123", + * }, + * update: { + * amount: 10, + * } + * }) */ export const updatePaymentCollectionStep = createStep( updatePaymentCollectionStepId, diff --git a/packages/core/core-flows/src/payment-collection/steps/update-refund-reasons.ts b/packages/core/core-flows/src/payment-collection/steps/update-refund-reasons.ts index 1264fee376..3979bfb812 100644 --- a/packages/core/core-flows/src/payment-collection/steps/update-refund-reasons.ts +++ b/packages/core/core-flows/src/payment-collection/steps/update-refund-reasons.ts @@ -9,13 +9,18 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The refund reasons to update. + */ +export type UpdateRefundReasonStepInput = UpdateRefundReasonDTO[] + export const updateRefundReasonStepId = "update-refund-reasons" /** * This step updates one or more refund reasons. */ export const updateRefundReasonsStep = createStep( updateRefundReasonStepId, - async (data: UpdateRefundReasonDTO[], { container }) => { + async (data: UpdateRefundReasonStepInput, { container }) => { const ids = data.map((d) => d.id) const { selects, relations } = getSelectsAndRelationsFromObjectArray(data) const service = container.resolve(Modules.PAYMENT) diff --git a/packages/core/core-flows/src/payment-collection/steps/validate-deleted-payment-sessions.ts b/packages/core/core-flows/src/payment-collection/steps/validate-deleted-payment-sessions.ts index c47958b236..7bd2ab7d0a 100644 --- a/packages/core/core-flows/src/payment-collection/steps/validate-deleted-payment-sessions.ts +++ b/packages/core/core-flows/src/payment-collection/steps/validate-deleted-payment-sessions.ts @@ -1,8 +1,17 @@ import { MedusaError } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to validate that the specified payment session IDs were deleted. + */ export interface ValidateDeletedPaymentSessionsStepInput { + /** + * The payment session IDs that were supposed to be deleted. + */ idsToDelete: string[] + /** + * The payment session IDs that were actually deleted. + */ idsDeleted: string[] } @@ -10,6 +19,13 @@ export const validateDeletedPaymentSessionsStepId = "validate-deleted-payment-sessions" /** * This step validates that the specified payment session IDs were deleted. + * If not all payment sessions were deleted, the step throws an error. + * + * @example + * const data = validateDeletedPaymentSessionsStep({ + * idsDeleted: ["pay_123"], + * idsToDelete: ["pay_123"] + * }) */ export const validateDeletedPaymentSessionsStep = createStep( validateDeletedPaymentSessionsStepId, diff --git a/packages/core/core-flows/src/payment-collection/workflows/create-payment-session.ts b/packages/core/core-flows/src/payment-collection/workflows/create-payment-session.ts index f0bba532ee..53b227caa2 100644 --- a/packages/core/core-flows/src/payment-collection/workflows/create-payment-session.ts +++ b/packages/core/core-flows/src/payment-collection/workflows/create-payment-session.ts @@ -13,16 +13,50 @@ import { useRemoteQueryStep } from "../../common" import { createPaymentSessionStep } from "../steps" import { deletePaymentSessionsWorkflow } from "./delete-payment-sessions" +/** + * The data to create payment sessions. + */ export interface CreatePaymentSessionsWorkflowInput { + /** + * The ID of the payment collection to create payment sessions for. + */ payment_collection_id: string + /** + * The ID of the payment provider that the payment sessions are associated with. + * This provider is used to later process the payment sessions and their payments. + */ provider_id: string + /** + * Custom data relevant for the payment provider to process the payment session. + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/payment/payment-session#data-property). + */ data?: Record + /** + * Additional context that's useful for the payment provider to process the payment session. + */ context?: PaymentProviderContext } export const createPaymentSessionsWorkflowId = "create-payment-sessions" /** - * This workflow creates payment sessions. + * This workflow creates payment sessions. It's used by the + * [Initialize Payment Session Store API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionsidpaymentsessions). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to create payment sessions in your custom flows. + * + * @example + * const { result } = await createPaymentSessionsWorkflow(container) + * .run({ + * input: { + * payment_collection_id: "paycol_123", + * provider_id: "pp_system" + * } + * }) + * + * @summary + * + * Create payment sessions. */ export const createPaymentSessionsWorkflow = createWorkflow( createPaymentSessionsWorkflowId, 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 5b618e7f28..539e82c0a5 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 @@ -9,14 +9,43 @@ import { } from "@medusajs/framework/workflows-sdk" import { createRefundReasonStep } from "../steps/create-refund-reasons" +/** + * The data to create refund reasons. + */ +export type CreateRefundReasonsWorkflowInput = { + /** + * The refund reasons to create. + */ + data: CreateRefundReasonDTO[] +} + export const createRefundReasonsWorkflowId = "create-refund-reasons-workflow" /** * This workflow creates one or more refund reasons. + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to create refund reasons in your custom flows. + * + * @example + * const { result } = await createRefundReasonsWorkflow(container) + * .run({ + * input: { + * data: [ + * { + * label: "damaged", + * } + * ] + * } + * }) + * + * @summary + * + * Create refund reasons. */ export const createRefundReasonsWorkflow = createWorkflow( createRefundReasonsWorkflowId, ( - input: WorkflowData<{ data: CreateRefundReasonDTO[] }> + input: WorkflowData ): WorkflowResponse => { return new WorkflowResponse(createRefundReasonStep(input.data)) } diff --git a/packages/core/core-flows/src/payment-collection/workflows/delete-payment-sessions.ts b/packages/core/core-flows/src/payment-collection/workflows/delete-payment-sessions.ts index 7cc6467edf..ab353cadc4 100644 --- a/packages/core/core-flows/src/payment-collection/workflows/delete-payment-sessions.ts +++ b/packages/core/core-flows/src/payment-collection/workflows/delete-payment-sessions.ts @@ -8,13 +8,35 @@ import { validateDeletedPaymentSessionsStep, } from "../steps" +/** + * The data to delete payment sessions. + */ export interface DeletePaymentSessionsWorkflowInput { + /** + * The IDs of the payment sessions to delete. + */ ids: string[] } export const deletePaymentSessionsWorkflowId = "delete-payment-sessions" /** - * This workflow deletes one or more payment sessions. + * This workflow deletes one or more payment sessions. It's used by other workflows, like + * {@link refreshPaymentCollectionForCartWorkflow} to delete payment sessions when the cart's total changes. + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to delete payment sessions in your custom flows. + * + * @example + * const { result } = await deletePaymentSessionsWorkflow(container) + * .run({ + * input: { + * ids: ["payses_123"] + * } + * }) + * + * @summary + * + * Delete payment sessions. */ export const deletePaymentSessionsWorkflow = createWorkflow( deletePaymentSessionsWorkflowId, 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 44c9c7f07f..c329f1ebc3 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 @@ -9,15 +9,43 @@ import { } from "@medusajs/framework/workflows-sdk" import { updateRefundReasonsStep } from "../steps" +/** + * The refund reasons to update. + */ +export type UpdateRefundReasonsWorkflowInput = UpdateRefundReasonDTO[] + +/** + * The updated refund reasons. + */ +export type UpdateRefundReasonsWorkflowOutput = RefundReasonDTO[] + export const updateRefundReasonsWorkflowId = "update-refund-reasons" /** * This workflow updates one or more refund reasons. + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to update refund reasons in your custom flows. + * + * @example + * const { result } = await updateRefundReasonsWorkflow(container) + * .run({ + * input: [ + * { + * id: "refres_123", + * label: "Damaged", + * } + * ] + * }) + * + * @summary + * + * Update refund reasons. */ export const updateRefundReasonsWorkflow = createWorkflow( updateRefundReasonsWorkflowId, ( - input: WorkflowData - ): WorkflowResponse => { + input: WorkflowData + ): WorkflowResponse => { return new WorkflowResponse(updateRefundReasonsStep(input)) } ) diff --git a/packages/core/core-flows/src/payment/steps/authorize-payment-session.ts b/packages/core/core-flows/src/payment/steps/authorize-payment-session.ts index d706e61b7d..3d94040dd3 100644 --- a/packages/core/core-flows/src/payment/steps/authorize-payment-session.ts +++ b/packages/core/core-flows/src/payment/steps/authorize-payment-session.ts @@ -11,14 +11,30 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to authorize the payment session. + */ export type AuthorizePaymentSessionStepInput = { + /** + * The ID of the payment session to authorize. + */ id: string + /** + * The context to authorize the payment session with. + * This context is passed to the payment provider associated with the payment session. + */ context: Record } export const authorizePaymentSessionStepId = "authorize-payment-session-step" /** * This step authorizes a payment session. + * + * @example + * const data = authorizePaymentSessionStep({ + * id: "payses_123", + * context: {} + * }) */ export const authorizePaymentSessionStep = createStep( authorizePaymentSessionStepId, diff --git a/packages/core/core-flows/src/payment/steps/cancel-payment.ts b/packages/core/core-flows/src/payment/steps/cancel-payment.ts index 7f08ff7b7f..989d6b0c44 100644 --- a/packages/core/core-flows/src/payment/steps/cancel-payment.ts +++ b/packages/core/core-flows/src/payment/steps/cancel-payment.ts @@ -6,7 +6,13 @@ import { } from "@medusajs/framework/utils" import { createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to cancel one or more payments. + */ export type CancelPaymentStepInput = { + /** + * The ID(s) of the payment(s) to cancel. + */ paymentIds: string | string[] } diff --git a/packages/core/core-flows/src/payment/steps/capture-payment.ts b/packages/core/core-flows/src/payment/steps/capture-payment.ts index 0aff0e15d7..75ce6dd0a7 100644 --- a/packages/core/core-flows/src/payment/steps/capture-payment.ts +++ b/packages/core/core-flows/src/payment/steps/capture-payment.ts @@ -5,9 +5,21 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to capture a payment. + */ export type CapturePaymentStepInput = { + /** + * The ID of the payment to capture. + */ payment_id: string + /** + * The ID of the user that captured the payment. + */ captured_by?: string + /** + * The amount to capture. If not provided, the full payment amount will be captured. + */ amount?: BigNumberInput } diff --git a/packages/core/core-flows/src/payment/steps/refund-payment.ts b/packages/core/core-flows/src/payment/steps/refund-payment.ts index a63ac30a7a..e91f8009df 100644 --- a/packages/core/core-flows/src/payment/steps/refund-payment.ts +++ b/packages/core/core-flows/src/payment/steps/refund-payment.ts @@ -5,9 +5,21 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to refund a payment. + */ export type RefundPaymentStepInput = { + /** + * The ID of the payment to refund. + */ payment_id: string + /** + * The ID of the user that refunded the payment. + */ created_by?: string + /** + * The amount to refund. If not provided, the full refundable amount is refunded. + */ amount?: BigNumberInput } diff --git a/packages/core/core-flows/src/payment/steps/refund-payments.ts b/packages/core/core-flows/src/payment/steps/refund-payments.ts index f2ed3cf438..7b16544777 100644 --- a/packages/core/core-flows/src/payment/steps/refund-payments.ts +++ b/packages/core/core-flows/src/payment/steps/refund-payments.ts @@ -12,6 +12,24 @@ import { } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The data to refund one or more payments. + */ +export type RefundPaymentsStepInput = { + /** + * The ID of the payment to refund. + */ + payment_id: string + /** + * The amount to refund. + */ + amount: BigNumberInput + /** + * The ID of the user that refunded the payment. + */ + created_by?: string +}[] + export const refundPaymentsStepId = "refund-payments-step" /** * This step refunds one or more payments. @@ -19,11 +37,7 @@ export const refundPaymentsStepId = "refund-payments-step" export const refundPaymentsStep = createStep( refundPaymentsStepId, async ( - input: { - payment_id: string - amount: BigNumberInput - created_by?: string - }[], + input: RefundPaymentsStepInput, { container } ) => { const logger = container.resolve(ContainerRegistrationKeys.LOGGER) diff --git a/packages/core/core-flows/src/payment/workflows/capture-payment.ts b/packages/core/core-flows/src/payment/workflows/capture-payment.ts index a426d562ae..b188f285d4 100644 --- a/packages/core/core-flows/src/payment/workflows/capture-payment.ts +++ b/packages/core/core-flows/src/payment/workflows/capture-payment.ts @@ -11,18 +11,48 @@ import { emitEventStep, useRemoteQueryStep } from "../../common" import { addOrderTransactionStep } from "../../order/steps/add-order-transaction" import { capturePaymentStep } from "../steps/capture-payment" +/** + * The data to capture a payment. + */ +export type CapturePaymentWorkflowInput = { + /** + * The ID of the payment to capture. + */ + payment_id: string + /** + * The ID of the user that captured the payment. + */ + captured_by?: string + /** + * The amount to capture. If not provided, the full payment amount will be captured. + */ + amount?: BigNumberInput +} + export const capturePaymentWorkflowId = "capture-payment-workflow" /** - * This workflow captures a payment. + * This workflow captures a payment. It's used by the + * [Capture Payment Admin API Route](https://docs.medusajs.com/api/admin#payments_postpaymentsidcapture). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to capture a payment in your custom flows. + * + * @example + * const { result } = await capturePaymentWorkflow(container) + * .run({ + * input: { + * payment_id: "pay_123" + * } + * }) + * + * @summary + * + * Capture a payment. */ export const capturePaymentWorkflow = createWorkflow( capturePaymentWorkflowId, ( - input: WorkflowData<{ - payment_id: string - captured_by?: string - amount?: BigNumberInput - }> + input: WorkflowData ): WorkflowResponse => { const payment = capturePaymentStep(input) diff --git a/packages/core/core-flows/src/payment/workflows/process-payment.ts b/packages/core/core-flows/src/payment/workflows/process-payment.ts index 63b1e903bf..f332729074 100644 --- a/packages/core/core-flows/src/payment/workflows/process-payment.ts +++ b/packages/core/core-flows/src/payment/workflows/process-payment.ts @@ -6,9 +6,36 @@ import { useQueryGraphStep } from "../../common" import { authorizePaymentSessionStep } from "../steps" import { capturePaymentWorkflow } from "./capture-payment" +/** + * The data to process a payment from a webhook action. + */ interface ProcessPaymentWorkflowInput extends WebhookActionResult {} export const processPaymentWorkflowId = "process-payment-workflow" +/** + * This workflow processes a payment to either complete its associated cart, + * capture the payment, or authorize the payment session. It's used when a + * [Webhook Event is received](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to process a payment in your custom flows based on a webhook action. + * + * @example + * const { result } = await processPaymentWorkflow(container) + * .run({ + * input: { + * action: "captured", + * data: { + * session_id: "payses_123", + * amount: 10 + * } + * } + * }) + * + * @summary + * + * Process a payment based on a webhook event. + */ export const processPaymentWorkflow = createWorkflow( processPaymentWorkflowId, (input: ProcessPaymentWorkflowInput) => { diff --git a/packages/core/core-flows/src/payment/workflows/refund-payment.ts b/packages/core/core-flows/src/payment/workflows/refund-payment.ts index 860708f2c9..6a733822e2 100644 --- a/packages/core/core-flows/src/payment/workflows/refund-payment.ts +++ b/packages/core/core-flows/src/payment/workflows/refund-payment.ts @@ -13,7 +13,46 @@ import { addOrderTransactionStep } from "../../order/steps/add-order-transaction import { refundPaymentStep } from "../steps/refund-payment" /** - * This step validates that the refund is valid for the order + * The data to validate whether the refund is valid for the order. + */ +export type ValidateRefundStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order's payment details. + */ + payment: PaymentDTO + /** + * The amound to refund. + */ + amount?: BigNumberInput +} + +/** + * This step validates that the refund is valid for the order. + * If the order does not have an outstanding balance to refund, the step throws an error. + * + * :::note + * + * You can retrieve an order or payment'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 = validateRefundStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * payment: { + * id: "payment_123", + * // other payment details... + * }, + * amount: 10 + * }) */ export const validateRefundStep = createStep( "validate-refund-step", @@ -21,11 +60,7 @@ export const validateRefundStep = createStep( order, payment, amount, - }: { - order: OrderDTO - payment: PaymentDTO - amount?: BigNumberInput - }) { + }: ValidateRefundStepInput) { const pendingDifference = order.summary?.raw_pending_difference! if (MathBN.gte(pendingDifference, 0)) { @@ -47,18 +82,48 @@ export const validateRefundStep = createStep( } ) +/** + * The data to refund a payment. + */ +export type RefundPaymentWorkflowInput = { + /** + * The ID of the payment to refund. + */ + payment_id: string + /** + * The ID of the user that refunded the payment. + */ + created_by?: string + /** + * The amount to refund. If not provided, the full payment amount will be refunded. + */ + amount?: BigNumberInput +} + export const refundPaymentWorkflowId = "refund-payment-workflow" /** - * This workflow refunds a payment. + * This workflow refunds a payment. It's used by the + * [Refund Payment Admin API Route](https://docs.medusajs.com/api/admin#payments_postpaymentsidrefund). + * + * You can use this workflow within your own customizations or custom workflows, allowing you + * to refund a payment in your custom flows. + * + * @example + * const { result } = await refundPaymentWorkflow(container) + * .run({ + * input: { + * payment_id: "payment_123", + * } + * }) + * + * @summary + * + * Refund a payment. */ export const refundPaymentWorkflow = createWorkflow( refundPaymentWorkflowId, ( - input: WorkflowData<{ - payment_id: string - created_by?: string - amount?: BigNumberInput - }> + input: WorkflowData ) => { const payment = useRemoteQueryStep({ entry_point: "payment", diff --git a/packages/core/core-flows/src/payment/workflows/refund-payments.ts b/packages/core/core-flows/src/payment/workflows/refund-payments.ts index 13e3942a6b..c275569375 100644 --- a/packages/core/core-flows/src/payment/workflows/refund-payments.ts +++ b/packages/core/core-flows/src/payment/workflows/refund-payments.ts @@ -11,24 +11,52 @@ import { useQueryGraphStep } from "../../common" import { addOrderTransactionStep } from "../../order" import { refundPaymentsStep } from "../steps/refund-payments" -type RefundPaymentsInput = { - payment_id: string - amount: BigNumberInput - created_by?: string +/** + * The data to validate whether the refund is valid for the payment. + */ +export type ValidatePaymentsRefundStepInput = { + /** + * The payment details. + */ + payments: PaymentDTO[] + /** + * The payments to refund. + */ + input: RefundPaymentsWorkflowInput } /** - * This step validates that the refund is valid for the payment + * This step validates that the refund is valid for the payment. + * If the payment's refundable amount is less than the amount to be refunded, + * the step throws an error. + * + * :::note + * + * You can retrieve a payment'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 = validatePaymentsRefundStep({ + * payment: [{ + * id: "payment_123", + * // other payment details... + * }], + * input: [ + * { + * payment_id: "payment_123", + * amount: 10, + * } + * ] + * }) */ export const validatePaymentsRefundStep = createStep( "validate-payments-refund-step", async function ({ payments, input, - }: { - payments: PaymentDTO[] - input: RefundPaymentsInput[] - }) { + }: ValidatePaymentsRefundStepInput) { const paymentIdAmountMap = new Map( input.map(({ payment_id, amount }) => [payment_id, amount]) ) @@ -57,13 +85,31 @@ export const validatePaymentsRefundStep = createStep( } ) +/** + * The data to refund a payment. + */ +export type RefundPaymentsWorkflowInput = { + /** + * The ID of the payment to refund. + */ + payment_id: string + /** + * The amount to refund. Must be less than the refundable amount of the payment. + */ + amount: BigNumberInput + /** + * The ID of the user that's refunding the payment. + */ + created_by?: string +}[] + export const refundPaymentsWorkflowId = "refund-payments-workflow" /** * This workflow refunds a payment. */ export const refundPaymentsWorkflow = createWorkflow( refundPaymentsWorkflowId, - (input: WorkflowData) => { + (input: WorkflowData) => { const paymentIds = transform({ input }, ({ input }) => input.map((paymentInput) => paymentInput.payment_id) ) diff --git a/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts b/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts index e90ac1c909..e06f88aaf6 100644 --- a/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts +++ b/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts @@ -9,7 +9,7 @@ export const batchLinkProductsToCollectionWorkflowId = * This workflow manages the links between a collection and products. It's used by the * [Manage Products of Collection Admin API Route](https://docs.medusajs.com/api/admin#collections_postcollectionsidproducts). * - * You can use this workflow within your own custom workflows to manage the products in a collection. + * You can use this workflow within your own customizations or custom workflows to manage the products in a collection. * * @example * const { result } = await batchLinkProductsToCollectionWorkflow(container) diff --git a/packages/core/core-flows/src/product/workflows/batch-product-variants.ts b/packages/core/core-flows/src/product/workflows/batch-product-variants.ts index cb823470e2..7aff253522 100644 --- a/packages/core/core-flows/src/product/workflows/batch-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/batch-product-variants.ts @@ -34,7 +34,7 @@ export const batchProductVariantsWorkflowId = "batch-product-variants" * This workflow creates, updates, and deletes product variants. It's used by the * [Manage Variants in a Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsbatch). * - * You can use this workflow within your own custom workflows to manage the variants of a product. You can also + * You can use this workflow within your own customizations or custom workflows to manage the variants of a product. You can also * use this within a [seed script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data) or in a custom import script. * * @example diff --git a/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts b/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts index bf5f95afe6..1ecead3054 100644 --- a/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts +++ b/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts @@ -8,7 +8,7 @@ export const batchLinkProductsToCategoryWorkflowId = * This workflow manages the links between a category and products. It's used by the * [Manage Products of Category Admin API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriesidproducts). * - * You can use this workflow within your own custom workflows to manage the products in a category. + * You can use this workflow within your own customizations or custom workflows to manage the products in a category. * * @example * const { result } = await batchLinkProductsToCategoryWorkflow(container) diff --git a/packages/core/core-flows/src/product/workflows/batch-products.ts b/packages/core/core-flows/src/product/workflows/batch-products.ts index 915f1bac75..66c1879377 100644 --- a/packages/core/core-flows/src/product/workflows/batch-products.ts +++ b/packages/core/core-flows/src/product/workflows/batch-products.ts @@ -29,7 +29,7 @@ export const batchProductsWorkflowId = "batch-products" * This workflow creates, updates, or deletes products. It's used by the * [Manage Products Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsbatch). * - * You can use this workflow within your own custom workflows to manage products in bulk. This is + * You can use this workflow within your own customizations or custom workflows to manage products in bulk. This is * also useful when writing a [seed script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data) or a custom import script. * * @example diff --git a/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts b/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts index 74aa8af7c0..8873ef33d0 100644 --- a/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts +++ b/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts @@ -45,7 +45,7 @@ export const upsertVariantPricesWorkflowId = "upsert-variant-prices" * This workflow creates, updates, or removes variants' prices. It's used by the {@link updateProductsWorkflow} * when updating a variant's prices. * - * You can use this workflow within your own custom workflows to manage the prices of a variant. + * You can use this workflow within your own customizations or custom workflows to manage the prices of a variant. * * @example * const { result } = await upsertVariantPricesWorkflow(container)