@acmekit/core-flows 2.13.1

package/dist/cart/workflows/confirm-variant-inventory.d.ts

@@ -0,0 +1,138 @@
+import type { ConfirmVariantInventoryWorkflowInputDTO } from "@acmekit/framework/types";
+import type { BigNumberInput } from "@acmekit/framework/types";
+/**
+ * The details of the cart items with inventory result computed for the specified input.
+ */
+export interface ConfirmVariantInventoryWorkflowOutput {
+    /**
+     * The cart's line items with the computed inventory result.
+     */
+    items: {
+        /**
+         * The line item's ID.
+         */
+        id?: string;
+        /**
+         * The ID of the inventory item used to retrieve the item's available quantity.
+         */
+        inventory_item_id: string;
+        /**
+         * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, AcmeKit checks the availability of the quantity multiplied by the
+         * value set for `required_quantity`. When the customer orders the quantity, AcmeKit reserves the ordered quantity multiplied by the value set for `required_quantity`.
+         */
+        required_quantity: number;
+        /**
+         * Whether the variant can be ordered even if it's out of stock. If a variant has this enabled, the workflow doesn't throw an error.
+         */
+        allow_backorder: boolean;
+        /**
+         * The quantity in the cart. If you provided `itemsToUpdate` in the input, this will be the updated quantity.
+         */
+        quantity: BigNumberInput;
+        /**
+         * The ID of the stock locations that the computed inventory quantity is available in.
+         */
+        location_ids: string[];
+    }[];
+}
+export declare const confirmVariantInventoryWorkflowId = "confirm-item-inventory";
+/**
+ * This workflow validates that product variants are in-stock at the specified sales channel, before adding them or updating their quantity in the cart. If a variant doesn't have sufficient quantity in-stock,
+ * the workflow throws an error. If all variants have sufficient inventory, the workflow returns the cart's items with their inventory details.
+ *
+ * This workflow is useful when confirming that a product variant has sufficient quantity to be added to or updated in the cart. It's executed
+ * by other cart-related workflows, such as {@link addToCartWorkflow}, to confirm that a product variant can be added to the cart at the specified quantity.
+ *
+ * :::note
+ *
+ * Learn more about the links between the product variant and sales channels and inventory items in [this documentation](https://docs.acmekit.com/resources/commerce-modules/product/links-to-other-modules).
+ *
+ * :::
+ *
+ * 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.acmekit.com/learn/fundamentals/module-links/query):
+ *
+ * ```ts workflow={false}
+ * const { data: variants } = await query.graph({
+ *   entity: "variant",
+ *   fields: [
+ *     "id",
+ *     "manage_inventory",
+ *     "inventory_items.inventory_item_id",
+ *     "inventory_items.required_quantity",
+ *     "inventory_items.inventory.requires_shipping",
+ *     "inventory_items.inventory.location_levels.stocked_quantity",
+ *     "inventory_items.inventory.location_levels.reserved_quantity",
+ *     "inventory_items.inventory.location_levels.raw_stocked_quantity",
+ *     "inventory_items.inventory.location_levels.raw_reserved_quantity",
+ *     "inventory_items.inventory.location_levels.stock_locations.id",
+ *     "inventory_items.inventory.location_levels.stock_locations.name",
+ *     "inventory_items.inventory.location_levels.stock_locations.sales_channels.id",
+ *     "inventory_items.inventory.location_levels.stock_locations.sales_channels.name",
+ *   ],
+ *   filters: {
+ *     id: ["variant_123"]
+ *   }
+ * })
+ * ```
+ *
+ * :::note
+ *
+ * In a workflow, use [useQueryGraphStep](https://docs.acmekit.com/resources/references/acmekit-workflows/steps/useQueryGraphStep) instead.
+ *
+ * :::
+ *
+ * Then, pass the variant's data with the other required data to the workflow:
+ *
+ * ```ts
+ * const { result } = await confirmVariantInventoryWorkflow(container)
+ *   .run({
+ *     input: {
+ *       sales_channel_id: "sc_123",
+ *       // @ts-ignore
+ *       variants,
+ *       items: [
+ *         {
+ *           variant_id: "variant_123",
+ *           quantity: 1
+ *         }
+ *       ]
+ *     }
+ *   })
+ * ```
+ *
+ * When updating an item quantity:
+ *
+ * ```ts
+ * const { result } = await confirmVariantInventoryWorkflow(container)
+ *  .run({
+ *    input: {
+ *      sales_channel_id: "sc_123",
+ *      // @ts-ignore
+ *      variants,
+ *      items: [
+ *        {
+ *          variant_id: "variant_123",
+ *          quantity: 1
+ *        }
+ *      ],
+ *      itemsToUpdate: [
+ *        {
+ *          data: {
+ *            variant_id: "variant_123",
+ *            quantity: 2
+ *          }
+ *        }
+ *      ]
+ *    }
+ *  })
+ * ```
+ *
+ * @summary
+ *
+ * Validate that a variant is in-stock before adding to the cart.
+ */
+export declare const confirmVariantInventoryWorkflow: import("@acmekit/framework/workflows-sdk").ReturnWorkflow<ConfirmVariantInventoryWorkflowInputDTO, ConfirmVariantInventoryWorkflowOutput, []>;
+//# sourceMappingURL=confirm-variant-inventory.d.ts.map

package/dist/cart/workflows/confirm-variant-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-variant-inventory.d.ts","sourceRoot":"","sources":["../../../src/cart/workflows/confirm-variant-inventory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,0BAA0B,CAAA;AAOvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAI9D;;GAEG;AACH,MAAM,WAAW,qCAAqC;IACpD;;OAEG;IACH,KAAK,EAAE;QACL;;WAEG;QACH,EAAE,CAAC,EAAE,MAAM,CAAA;QACX;;WAEG;QACH,iBAAiB,EAAE,MAAM,CAAA;QACzB;;;WAGG;QACH,iBAAiB,EAAE,MAAM,CAAA;QACzB;;WAEG;QACH,eAAe,EAAE,OAAO,CAAA;QACxB;;WAEG;QACH,QAAQ,EAAE,cAAc,CAAA;QACxB;;WAEG;QACH,YAAY,EAAE,MAAM,EAAE,CAAA;KACvB,EAAE,CAAA;CACJ;AAED,eAAO,MAAM,iCAAiC,2BAA2B,CAAA;AACzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,eAAO,MAAM,+BAA+B,+IAc3C,CAAA"}

package/dist/cart/workflows/confirm-variant-inventory.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmVariantInventoryWorkflow = exports.confirmVariantInventoryWorkflowId = void 0;
+const workflows_sdk_1 = require("@acmekit/framework/workflows-sdk");
+const steps_1 = require("../steps");
+const prepare_confirm_inventory_input_1 = require("../utils/prepare-confirm-inventory-input");
+exports.confirmVariantInventoryWorkflowId = "confirm-item-inventory";
+/**
+ * This workflow validates that product variants are in-stock at the specified sales channel, before adding them or updating their quantity in the cart. If a variant doesn't have sufficient quantity in-stock,
+ * the workflow throws an error. If all variants have sufficient inventory, the workflow returns the cart's items with their inventory details.
+ *
+ * This workflow is useful when confirming that a product variant has sufficient quantity to be added to or updated in the cart. It's executed
+ * by other cart-related workflows, such as {@link addToCartWorkflow}, to confirm that a product variant can be added to the cart at the specified quantity.
+ *
+ * :::note
+ *
+ * Learn more about the links between the product variant and sales channels and inventory items in [this documentation](https://docs.acmekit.com/resources/commerce-modules/product/links-to-other-modules).
+ *
+ * :::
+ *
+ * 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.acmekit.com/learn/fundamentals/module-links/query):
+ *
+ * ```ts workflow={false}
+ * const { data: variants } = await query.graph({
+ *   entity: "variant",
+ *   fields: [
+ *     "id",
+ *     "manage_inventory",
+ *     "inventory_items.inventory_item_id",
+ *     "inventory_items.required_quantity",
+ *     "inventory_items.inventory.requires_shipping",
+ *     "inventory_items.inventory.location_levels.stocked_quantity",
+ *     "inventory_items.inventory.location_levels.reserved_quantity",
+ *     "inventory_items.inventory.location_levels.raw_stocked_quantity",
+ *     "inventory_items.inventory.location_levels.raw_reserved_quantity",
+ *     "inventory_items.inventory.location_levels.stock_locations.id",
+ *     "inventory_items.inventory.location_levels.stock_locations.name",
+ *     "inventory_items.inventory.location_levels.stock_locations.sales_channels.id",
+ *     "inventory_items.inventory.location_levels.stock_locations.sales_channels.name",
+ *   ],
+ *   filters: {
+ *     id: ["variant_123"]
+ *   }
+ * })
+ * ```
+ *
+ * :::note
+ *
+ * In a workflow, use [useQueryGraphStep](https://docs.acmekit.com/resources/references/acmekit-workflows/steps/useQueryGraphStep) instead.
+ *
+ * :::
+ *
+ * Then, pass the variant's data with the other required data to the workflow:
+ *
+ * ```ts
+ * const { result } = await confirmVariantInventoryWorkflow(container)
+ *   .run({
+ *     input: {
+ *       sales_channel_id: "sc_123",
+ *       // @ts-ignore
+ *       variants,
+ *       items: [
+ *         {
+ *           variant_id: "variant_123",
+ *           quantity: 1
+ *         }
+ *       ]
+ *     }
+ *   })
+ * ```
+ *
+ * When updating an item quantity:
+ *
+ * ```ts
+ * const { result } = await confirmVariantInventoryWorkflow(container)
+ *  .run({
+ *    input: {
+ *      sales_channel_id: "sc_123",
+ *      // @ts-ignore
+ *      variants,
+ *      items: [
+ *        {
+ *          variant_id: "variant_123",
+ *          quantity: 1
+ *        }
+ *      ],
+ *      itemsToUpdate: [
+ *        {
+ *          data: {
+ *            variant_id: "variant_123",
+ *            quantity: 2
+ *          }
+ *        }
+ *      ]
+ *    }
+ *  })
+ * ```
+ *
+ * @summary
+ *
+ * Validate that a variant is in-stock before adding to the cart.
+ */
+exports.confirmVariantInventoryWorkflow = (0, workflows_sdk_1.createWorkflow)(exports.confirmVariantInventoryWorkflowId, (input) => {
+    const confirmInventoryInput = (0, workflows_sdk_1.transform)({ input }, prepare_confirm_inventory_input_1.prepareConfirmInventoryInput);
+    (0, steps_1.confirmInventoryStep)(confirmInventoryInput);
+    return new workflows_sdk_1.WorkflowResponse(confirmInventoryInput);
+});
+//# sourceMappingURL=confirm-variant-inventory.js.map

package/dist/cart/workflows/confirm-variant-inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-variant-inventory.js","sourceRoot":"","sources":["../../../src/cart/workflows/confirm-variant-inventory.ts"],"names":[],"mappings":";;;AACA,oEAKyC;AAEzC,oCAA+C;AAC/C,8FAAuF;AAsC1E,QAAA,iCAAiC,GAAG,wBAAwB,CAAA;AACzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACU,QAAA,+BAA+B,GAAG,IAAA,8BAAc,EAC3D,yCAAiC,EACjC,CACE,KAA4D,EACH,EAAE;IAC3D,MAAM,qBAAqB,GAAG,IAAA,yBAAS,EACrC,EAAE,KAAK,EAAE,EACT,8DAA4B,CAC7B,CAAA;IAED,IAAA,4BAAoB,EAAC,qBAAqB,CAAC,CAAA;IAE3C,OAAO,IAAI,gCAAgB,CAAC,qBAAqB,CAAC,CAAA;AACpD,CAAC,CACF,CAAA"}

package/dist/cart/workflows/create-cart-credit-lines.d.ts

@@ -0,0 +1,21 @@
+import { CartCreditLineDTO, CreateCartCreditLinesWorkflowInput } from "@acmekit/framework/types";
+export declare const createCartCreditLinesWorkflowId = "create-cart-credit-lines";
+/**
+ * This workflow creates one or more credit lines for a cart.
+ *
+ * @example
+ * const { result } = await createCartCreditLinesWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     amount: 10,
+ *     reference: "payment",
+ *     reference_id: "payment_123",
+ *     metadata: {
+ *       key: "value",
+ *     },
+ *   }
+ * })
+ */
+export declare const createCartCreditLinesWorkflow: import("@acmekit/framework/workflows-sdk").ReturnWorkflow<CreateCartCreditLinesWorkflowInput, CartCreditLineDTO[], []>;
+//# sourceMappingURL=create-cart-credit-lines.d.ts.map

package/dist/cart/workflows/create-cart-credit-lines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cart-credit-lines.d.ts","sourceRoot":"","sources":["../../../src/cart/workflows/create-cart-credit-lines.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kCAAkC,EACnC,MAAM,0BAA0B,CAAA;AASjC,eAAO,MAAM,+BAA+B,6BAA6B,CAAA;AACzE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,6BAA6B,wHAczC,CAAA"}

package/dist/cart/workflows/create-cart-credit-lines.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCartCreditLinesWorkflow = exports.createCartCreditLinesWorkflowId = void 0;
+const utils_1 = require("@acmekit/framework/utils");
+const workflows_sdk_1 = require("@acmekit/framework/workflows-sdk");
+const create_entities_1 = require("../../common/steps/create-entities");
+exports.createCartCreditLinesWorkflowId = "create-cart-credit-lines";
+/**
+ * This workflow creates one or more credit lines for a cart.
+ *
+ * @example
+ * const { result } = await createCartCreditLinesWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     amount: 10,
+ *     reference: "payment",
+ *     reference_id: "payment_123",
+ *     metadata: {
+ *       key: "value",
+ *     },
+ *   }
+ * })
+ */
+exports.createCartCreditLinesWorkflow = (0, workflows_sdk_1.createWorkflow)(exports.createCartCreditLinesWorkflowId, (input) => {
+    const creditLines = (0, create_entities_1.createEntitiesStep)({
+        moduleRegistrationName: utils_1.Modules.CART,
+        invokeMethod: "createCreditLines",
+        compensateMethod: "deleteCreditLines",
+        data: input,
+    });
+    return new workflows_sdk_1.WorkflowResponse(creditLines);
+});
+//# sourceMappingURL=create-cart-credit-lines.js.map

package/dist/cart/workflows/create-cart-credit-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cart-credit-lines.js","sourceRoot":"","sources":["../../../src/cart/workflows/create-cart-credit-lines.ts"],"names":[],"mappings":";;;AAIA,oDAAkD;AAClD,oEAIyC;AACzC,wEAAuE;AAE1D,QAAA,+BAA+B,GAAG,0BAA0B,CAAA;AACzE;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,6BAA6B,GAAG,IAAA,8BAAc,EACzD,uCAA+B,EAC/B,CACE,KAAuD,EAChB,EAAE;IACzC,MAAM,WAAW,GAAG,IAAA,oCAAkB,EAAC;QACrC,sBAAsB,EAAE,eAAO,CAAC,IAAI;QACpC,YAAY,EAAE,mBAAmB;QACjC,gBAAgB,EAAE,mBAAmB;QACrC,IAAI,EAAE,KAAK;KACZ,CAAC,CAAA;IAEF,OAAO,IAAI,gCAAgB,CAAC,WAAW,CAAC,CAAA;AAC1C,CAAC,CACF,CAAA"}

package/dist/cart/workflows/create-carts.d.ts

@@ -0,0 +1,106 @@
+import { AdditionalData, CreateCartDTO, CreateCartWorkflowInputDTO } from "@acmekit/framework/types";
+import { WorkflowData } from "@acmekit/framework/workflows-sdk";
+/**
+ * The data to create the cart, along with custom data that's passed to the workflow's hooks.
+ */
+export type CreateCartWorkflowInput = CreateCartWorkflowInputDTO & AdditionalData;
+export declare const createCartWorkflowId = "create-cart";
+/**
+ * This workflow creates and returns a cart. You can set the cart's items, region, customer, and other details. This workflow is executed by the
+ * [Create Cart Store API Route](https://docs.acmekit.com/api/store#carts_postcarts).
+ *
+ * This workflow has a hook that allows you to perform custom actions on the created cart. You can see an example in [this guide](https://docs.acmekit.com/resources/commerce-modules/cart/extend#step-4-consume-cartcreated-workflow-hook).
+ *
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around cart creation.
+ *
+ * @example
+ * const { result } = await createCartWorkflow(container)
+ *   .run({
+ *     input: {
+ *       region_id: "reg_123",
+ *       items: [
+ *         {
+ *           variant_id: "var_123",
+ *           quantity: 1,
+ *         }
+ *       ],
+ *       customer_id: "cus_123",
+ *       additional_data: {
+ *         external_id: "123"
+ *       }
+ *     }
+ *   })
+ *
+ * @summary
+ *
+ * Create a cart specifying region, items, and more.
+ *
+ * @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 "@acmekit/acmekit/core-flows";
+ * import { StepResponse } from "@acmekit/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.acmekit.com/resources/commerce-modules/pricing/price-calculation) documentation.
+ *
+ * :::
+ */
+export declare const createCartWorkflow: import("@acmekit/framework/workflows-sdk").ReturnWorkflow<CreateCartWorkflowInput, import("@acmekit/framework/types").CartDTO, [import("@acmekit/framework/workflows-sdk").Hook<"validate", {
+    input: WorkflowData<CreateCartDTO>;
+    cart: WorkflowData<CreateCartDTO>;
+}, unknown>, import("@acmekit/framework/workflows-sdk").Hook<"cartCreated", {
+    cart: WorkflowData<import("@acmekit/framework/types").CartDTO>;
+    additional_data: ((Record<string, unknown> | WorkflowData<Record<string, unknown> | undefined>) & Record<string, unknown>) | undefined;
+}, unknown>, import("@acmekit/framework/workflows-sdk").Hook<"setPricingContext", {
+    region: any;
+    variantIds: WorkflowData<string[]>;
+    salesChannel: {
+        id: string | WorkflowData<string>;
+        name: string | WorkflowData<string>;
+        description: string | WorkflowData<string | null> | null;
+        is_disabled: boolean | WorkflowData<boolean>;
+        metadata: Record<string, unknown> | WorkflowData<Record<string, unknown> | null> | null;
+        locations?: import("@acmekit/framework/types").SalesChannelLocationDTO[] | WorkflowData<import("@acmekit/framework/types").SalesChannelLocationDTO[] | undefined> | undefined;
+    } & import("@acmekit/framework/types").SalesChannelDTO & import("@acmekit/framework/workflows-sdk").WorkflowDataProperties<import("@acmekit/framework/types").SalesChannelDTO | null> & {
+        config(config: {
+            name?: string;
+        } & Omit<import("@acmekit/orchestration").TransactionStepsDefinition, "next" | "uuid" | "action">): WorkflowData<import("@acmekit/framework/types").SalesChannelDTO | null>;
+    } & import("@acmekit/framework/workflows-sdk").StepFunctionReturnConfig<import("@acmekit/framework/types").SalesChannelDTO | null>;
+    customerData: {
+        customer?: import("@acmekit/framework/types").CustomerDTO | WorkflowData<import("@acmekit/framework/types").CustomerDTO | null | undefined> | null | undefined;
+        email?: string | WorkflowData<string | null | undefined> | null | undefined;
+    } & import("../steps").FindOrCreateCustomerOutputStepOutput & import("@acmekit/framework/workflows-sdk").WorkflowDataProperties<import("../steps").FindOrCreateCustomerOutputStepOutput> & {
+        config(config: {
+            name?: string;
+        } & Omit<import("@acmekit/orchestration").TransactionStepsDefinition, "next" | "uuid" | "action">): WorkflowData<import("../steps").FindOrCreateCustomerOutputStepOutput>;
+    } & import("@acmekit/framework/workflows-sdk").StepFunctionReturnConfig<import("../steps").FindOrCreateCustomerOutputStepOutput>;
+    additional_data: ((Record<string, unknown> | WorkflowData<Record<string, unknown> | undefined>) & Record<string, unknown>) | undefined;
+}, Record<string, any> | undefined>]>;
+//# sourceMappingURL=create-carts.d.ts.map

package/dist/cart/workflows/create-carts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-carts.d.ts","sourceRoot":"","sources":["../../../src/cart/workflows/create-carts.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAEd,aAAa,EACb,0BAA0B,EAE3B,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EAKL,YAAY,EAEb,MAAM,kCAAkC,CAAA;AAmBzC;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,0BAA0B,GAC9D,cAAc,CAAA;AAEhB,eAAO,MAAM,oBAAoB,gBAAgB,CAAA;AACjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;gBA/CV,CAAC;;;;;;;;gBAAD,CAAC;;;;qCAoNrB,CAAA"}

package/dist/cart/workflows/create-carts.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCartWorkflow = exports.createCartWorkflowId = void 0;
+const utils_1 = require("@acmekit/framework/utils");
+const workflows_sdk_1 = require("@acmekit/framework/workflows-sdk");
+const emit_event_1 = require("../../common/steps/emit-event");
+const steps_1 = require("../steps");
+const validate_sales_channel_1 = require("../steps/validate-sales-channel");
+const fields_1 = require("../utils/fields");
+const prepare_confirm_inventory_input_1 = require("../utils/prepare-confirm-inventory-input");
+const schemas_1 = require("../utils/schemas");
+const confirm_variant_inventory_1 = require("./confirm-variant-inventory");
+const get_variants_and_items_with_prices_1 = require("./get-variants-and-items-with-prices");
+const refresh_payment_collection_1 = require("./refresh-payment-collection");
+const update_cart_promotions_1 = require("./update-cart-promotions");
+const update_tax_lines_1 = require("./update-tax-lines");
+const common_1 = require("../../common");
+exports.createCartWorkflowId = "create-cart";
+/**
+ * This workflow creates and returns a cart. You can set the cart's items, region, customer, and other details. This workflow is executed by the
+ * [Create Cart Store API Route](https://docs.acmekit.com/api/store#carts_postcarts).
+ *
+ * This workflow has a hook that allows you to perform custom actions on the created cart. You can see an example in [this guide](https://docs.acmekit.com/resources/commerce-modules/cart/extend#step-4-consume-cartcreated-workflow-hook).
+ *
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around cart creation.
+ *
+ * @example
+ * const { result } = await createCartWorkflow(container)
+ *   .run({
+ *     input: {
+ *       region_id: "reg_123",
+ *       items: [
+ *         {
+ *           variant_id: "var_123",
+ *           quantity: 1,
+ *         }
+ *       ],
+ *       customer_id: "cus_123",
+ *       additional_data: {
+ *         external_id: "123"
+ *       }
+ *     }
+ *   })
+ *
+ * @summary
+ *
+ * Create a cart specifying region, items, and more.
+ *
+ * @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 "@acmekit/acmekit/core-flows";
+ * import { StepResponse } from "@acmekit/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.acmekit.com/resources/commerce-modules/pricing/price-calculation) documentation.
+ *
+ * :::
+ */
+exports.createCartWorkflow = (0, workflows_sdk_1.createWorkflow)(exports.createCartWorkflowId, (input) => {
+    const variantIds = (0, workflows_sdk_1.transform)({ input }, (data) => {
+        return (data.input.items ?? [])
+            .map((i) => i.variant_id)
+            .filter((v) => !!v);
+    });
+    const [salesChannel, region, customerData] = (0, workflows_sdk_1.parallelize)((0, steps_1.findSalesChannelStep)({
+        salesChannelId: input.sales_channel_id,
+    }), (0, steps_1.findOneOrAnyRegionStep)({
+        regionId: input.region_id,
+    }), (0, steps_1.findOrCreateCustomerStep)({
+        customerId: input.customer_id,
+        email: input.email,
+    }));
+    (0, validate_sales_channel_1.validateSalesChannelStep)({ salesChannel });
+    const setPricingContext = (0, workflows_sdk_1.createHook)("setPricingContext", {
+        region,
+        variantIds,
+        salesChannel,
+        customerData,
+        additional_data: input.additional_data,
+    }, {
+        resultValidator: schemas_1.pricingContextResult,
+    });
+    const setPricingContextResult = setPricingContext.getResult();
+    const { variants, lineItems } = get_variants_and_items_with_prices_1.getVariantsAndItemsWithPrices.runAsStep({
+        input: {
+            cart: {
+                currency_code: input.currency_code,
+                region,
+                region_id: region.id,
+                customer_id: customerData.customer?.id,
+            },
+            items: input.items,
+            setPricingContextResult: setPricingContextResult,
+            variants: {
+                id: variantIds,
+                fields: (0, utils_1.deduplicate)([
+                    ...fields_1.productVariantsFields,
+                    ...prepare_confirm_inventory_input_1.requiredVariantFieldsForInventoryConfirmation,
+                ]),
+            },
+        },
+    });
+    confirm_variant_inventory_1.confirmVariantInventoryWorkflow.runAsStep({
+        input: {
+            sales_channel_id: salesChannel.id,
+            variants: variants,
+            items: input.items,
+        },
+    });
+    const cartInput = (0, workflows_sdk_1.transform)({ input, region, customerData, salesChannel }, (data) => {
+        if (!data.region) {
+            throw new utils_1.AcmeKitError(utils_1.AcmeKitError.Types.NOT_FOUND, "No regions found");
+        }
+        const data_ = {
+            ...data.input,
+            currency_code: data.input.currency_code ?? data.region.currency_code,
+            region_id: data.region.id,
+        };
+        if (data.customerData.customer?.id) {
+            data_.customer_id = data.customerData.customer.id;
+            data_.email = data.input?.email ?? data.customerData.customer.email;
+        }
+        data_.sales_channel_id = data.salesChannel.id;
+        // If there is only one country in the region, we prepare a shipping address with that country's code.
+        if (!data.input.shipping_address &&
+            data.region.countries.length === 1) {
+            data_.shipping_address = {
+                country_code: data.region.countries[0].iso_2,
+            };
+        }
+        return data_;
+    });
+    const itemsToCreate = (0, workflows_sdk_1.transform)({ lineItems }, (data) => {
+        return data.lineItems.map((i) => i.data);
+    });
+    const translatedItems = (0, common_1.getTranslatedLineItemsStep)({
+        items: itemsToCreate,
+        variants,
+        locale: input.locale,
+    });
+    const cartToCreate = (0, workflows_sdk_1.transform)({ cartInput, translatedItems }, (data) => {
+        data.cartInput.items = data.translatedItems;
+        return data.cartInput;
+    });
+    const validate = (0, workflows_sdk_1.createHook)("validate", {
+        input: cartInput,
+        cart: cartToCreate,
+    });
+    const carts = (0, steps_1.createCartsStep)([cartToCreate]);
+    const cart = (0, workflows_sdk_1.transform)({ carts }, (data) => data.carts?.[0]);
+    update_tax_lines_1.updateTaxLinesWorkflow.runAsStep({
+        input: {
+            cart_id: cart.id,
+        },
+    });
+    update_cart_promotions_1.updateCartPromotionsWorkflow.runAsStep({
+        input: {
+            cart_id: cart.id,
+            promo_codes: input.promo_codes,
+            force_refresh_payment_collection: false,
+        },
+    });
+    (0, workflows_sdk_1.parallelize)(refresh_payment_collection_1.refreshPaymentCollectionForCartWorkflow.runAsStep({
+        input: {
+            cart: cart,
+        },
+    }), (0, emit_event_1.emitEventStep)({
+        eventName: utils_1.CartWorkflowEvents.CREATED,
+        data: { id: cart.id },
+    }));
+    const cartCreated = (0, workflows_sdk_1.createHook)("cartCreated", {
+        cart,
+        additional_data: input.additional_data,
+    });
+    return new workflows_sdk_1.WorkflowResponse(cart, {
+        hooks: [validate, cartCreated, setPricingContext],
+    });
+});
+//# sourceMappingURL=create-carts.js.map

package/dist/cart/workflows/create-carts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-carts.js","sourceRoot":"","sources":["../../../src/cart/workflows/create-carts.ts"],"names":[],"mappings":"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"}