@viu/emporix-sdk 4.0.1 → 4.2.0

package/dist/cart.d.cts

@@ -739,6 +739,54 @@ type CreatedCart = {
     cartId: string;
     yrn: Yrn;
 };
+type Discount = {
+    /**
+     * Discount unique identifier.
+     */
+    id?: string;
+    couponYrn?: Yrn;
+    /**
+     * Discount code generated when a discount coupon is created through the Coupon Service.
+     */
+    code: string;
+    /**
+     * Three-letter currency code, compliant with the ISO 4217 standard.
+     */
+    currency?: string;
+    /**
+     * Discount expressed as fixed amount.
+     */
+    amount?: number;
+    /**
+     * Discount displayed name.
+     */
+    name?: string;
+    /**
+     * Discount expressed as a percentage of the price.
+     */
+    discountRate?: number;
+    /**
+     * Determines whether the coupon is applied to the total or subtotal value of the order.
+     */
+    discountCalculationType?: 'SUBTOTAL' | 'TOTAL';
+    /**
+     * Links to Coupon Service endpoints used to validate and redeem the discount.
+     */
+    links?: Array<Link>;
+    /**
+     * Calculation type specifies how the discount should be calculated. It can be set to one of the following:
+     * * `ApplyDiscountBeforeTax`
+     * * `ApplyDiscountAfterTax`
+     *
+     * The field is **deprecated** and is not used in calculatedPrice fields. The calculated price takes into account site's settings
+     * where:
+     * * `includesTax=true` results in `ApplyDiscountAfterTax`
+     * * `includesTax=false` results in `ApplyDiscountBeforeTax`
+     *
+     * @deprecated
+     */
+    calculationType?: 'ApplyDiscountBeforeTax' | 'ApplyDiscountAfterTax';
+};
 /**
  * Discount details.
  */
@@ -1287,6 +1335,186 @@ type CartItemsBatchUpdateRequest = Array<CartItemRequest & {
     [key: string]: unknown;
 }>;
 type BatchResponse = Array<SingleBatchResponse>;
+/**
+ * Body of `POST /cart/{tenant}/carts/{cartId}/execute`. Between 1 and 10 commands.
+ */
+type ExecuteRequest = {
+    /**
+     * Commands to run sequentially. Maximum 10. Request duration is approximately the sum of the chained commands.
+     *
+     * Each item needs `type`. `data` is the REST request body and is omitted for commands that have no body. The cart id is the path parameter. `options` holds remaining path and query equivalents (`itemId`, `partial`, `expandCalculation`, `zipCode`, `countryCode`, `resourceVersion`, `codes`, `discountIndex`).
+     *
+     */
+    commands: Array<ExecuteCommand>;
+};
+/**
+ * One operation in the execute chain. `type` selects the REST equivalent. `data` is that endpoint’s request body. The cart id is the execute path parameter. `options` fields are remaining path and query equivalents (`itemId`, `partial`, `expandCalculation`, `zipCode`, `countryCode`, `resourceVersion`, `codes`, `discountIndex`).
+ *
+ * Session and legal-entity identity are request headers, not command fields.
+ *
+ */
+type ExecuteCommand = {
+    /**
+     * Operation to run.
+     *
+     * Possible values:
+     * * `AddCartItem`
+     * * `UpdateCartItem`
+     * * `DeleteCartItem`
+     * * `DeleteCartItems`
+     * * `GetCart`
+     * * `AddCartItemsBatch`
+     * * `UpdateCartItemsBatch`
+     * * `UpdateCart`
+     * * `ApplyCartDiscount`
+     * * `GetCartDiscounts`
+     * * `DeleteCartDiscounts`
+     * * `DeleteCartDiscount`
+     * * `RefreshCart`
+     * * `ValidateCart`
+     *
+     */
+    type: 'AddCartItem' | 'UpdateCartItem' | 'DeleteCartItem' | 'DeleteCartItems' | 'GetCart' | 'AddCartItemsBatch' | 'UpdateCartItemsBatch' | 'UpdateCart' | 'ApplyCartDiscount' | 'GetCartDiscounts' | 'DeleteCartDiscounts' | 'DeleteCartDiscount' | 'RefreshCart' | 'ValidateCart';
+    /**
+     * Request body of the equivalent REST operation.
+     *
+     * * `AddCartItem` – cart item body
+     * * `UpdateCartItem` – cart item update body
+     * * `AddCartItemsBatch` – list of cart item bodies
+     * * `UpdateCartItemsBatch` – list of cart item updates (maximum 50)
+     * * `UpdateCart` – cart update body
+     * * `ApplyCartDiscount` – discount body
+     *
+     * Omit `data` for `GetCart`, `RefreshCart`, `ValidateCart`, deletes, `GetCartDiscounts`, `DeleteCartDiscounts`, and `DeleteCartDiscount`.
+     *
+     * The service selects the body type from `type`. A single item body is an object. Batch commands send an array.
+     *
+     */
+    data?: {
+        [key: string]: unknown;
+    } | Array<{
+        [key: string]: unknown;
+    }>;
+    options?: ExecuteCommandOptions;
+};
+/**
+ * Remaining path and query equivalents for the command. Required fields depend on `type`. The cart id is the execute path parameter, not an option.
+ */
+type ExecuteCommandOptions = {
+    /**
+     * Cart item unique identifier generated when the product is added to the cart.
+     *
+     * Required for `UpdateCartItem` and `DeleteCartItem`.
+     *
+     */
+    itemId?: string;
+    /**
+     * When `true`, only the provided item or batch fields are updated. Same default as the REST `partial` query parameter (`false`).
+     *
+     * Used by `UpdateCartItem` and `UpdateCartItemsBatch`.
+     *
+     */
+    partial?: boolean;
+    /**
+     * When `true`, `GetCart` returns a fully calculated cart. Same default as the REST `expandCalculation` query parameter (`true`).
+     *
+     * Used by `GetCart`.
+     *
+     */
+    expandCalculation?: boolean;
+    /**
+     * Zip code of the shipping address, used for tax calculations, shipping cost estimations, and pricing. Provide together with `countryCode` if either is specified.
+     *
+     * Used by `GetCart`.
+     *
+     */
+    zipCode?: string;
+    /**
+     * Two-letter country code of the shipping address. Provide together with `zipCode` if either is specified.
+     *
+     * Used by `GetCart`.
+     *
+     */
+    countryCode?: string;
+    /**
+     * Cart resource version used as If-Match for participating writes (`AddCartItem`, `UpdateCartItem`, `UpdateCart`, `ApplyCartDiscount`).
+     *
+     * * `versioning=skip` – ignored
+     * * `versioning=explicit` – required on every participating command (whole-request preflight)
+     * * `versioning=follow` – required to seed the first participating write; omit on later writes
+     *
+     * Extra `resourceVersion` on `GetCart`, `ValidateCart`, `RefreshCart`, deletes, and itemsBatch is ignored.
+     *
+     */
+    resourceVersion?: number;
+    /**
+     * Discount codes to remove. If omitted, `DeleteCartDiscounts` removes all discounts. Same meaning as the REST `codes` query parameter.
+     *
+     * Used by `DeleteCartDiscounts`.
+     *
+     */
+    codes?: Array<string>;
+    /**
+     * Index of the discount in the cart discounts array.
+     *
+     * Required for `DeleteCartDiscount`.
+     *
+     */
+    discountIndex?: string;
+};
+/**
+ * Body of a 207 execute response. Present only when the chain was accepted and executed.
+ */
+type ExecuteResponse = {
+    /**
+     * Ordered results for commands that ran. With `onError=fail`, the array stops after the first non-2xx command.
+     *
+     */
+    results: Array<ExecuteCommandResult>;
+};
+/**
+ * Result of one command in the execute chain. `data` matches the REST response body for that command.
+ */
+type ExecuteCommandResult = {
+    /**
+     * Zero-based index of the command in the request `commands` array.
+     */
+    index: number;
+    /**
+     * Command type that produced this result.
+     */
+    type: string;
+    /**
+     * HTTP status code of the equivalent REST operation.
+     */
+    code: number;
+    /**
+     * HTTP reason phrase that matches `code`.
+     */
+    status: string;
+    /**
+     * Response body of the equivalent REST operation. Omitted when that endpoint returns 204.
+     *
+     * A single-object body (`AddCartItem`, `GetCart`, `ApplyCartDiscount`, `ValidateCart`, or an error) is an object. `GetCartDiscounts`, `AddCartItemsBatch`, and `UpdateCartItemsBatch` return an array. Failures use the same error shape as REST (`code`, `status`, `message`).
+     *
+     */
+    data?: {
+        [key: string]: unknown;
+    } | Array<{
+        [key: string]: unknown;
+    }> | null;
+    /**
+     * Response headers for this command.
+     *
+     * When a participating write applied If-Match, this object contains `hybris-resource-version` set to the version after the write. `versioning=skip` does not send If-Match, so the header is absent.
+     *
+     * `AddCartItemsBatch` does not use this object for item locations. Each created item's `data[].headers.location` uses the same location as REST `POST .../itemsBatch`.
+     *
+     */
+    headers?: {
+        [key: string]: string;
+    };
+};
 /**
  * YRN
  *
@@ -1916,6 +2144,60 @@ type ValidationError = {
      */
     field?: string;
 };
+type PostCartExecuteData = {
+    body: ExecuteRequest;
+    headers?: {
+        /**
+         * Anonymous customer unique session identifier. Shared by every command in the chain. Commands cannot override this header.
+         *
+         */
+        'session-id'?: string;
+        /**
+         * Legal entity of the shopper context. Shared by every command in the chain. Commands cannot override this header. To act as a different legal entity, send another request.
+         *
+         */
+        'legal-entity-id'?: string;
+    };
+    path: {
+        /**
+         * Cart unique identifier generated when a cart is created.
+         */
+        cartId: string;
+        /**
+         * Your Emporix tenant name.
+         *
+         * **Note**: The tenant should always be written in lowercase.
+         *
+         */
+        tenant: string;
+    };
+    query?: {
+        /**
+         * Controls whether the chain stops after the first non-2xx command.
+         *
+         * Possible values:
+         * * `fail` – Stop after the first non-2xx command. `results` contains only the commands that ran, including the failed one.
+         * * `resume` – Run every command. Later commands still see earlier successful mutations.
+         *
+         * An invalid value returns **400** for the whole request before any command runs.
+         *
+         */
+        onError?: 'fail' | 'resume';
+        /**
+         * If-Match strategy for participating writes (`AddCartItem`, `UpdateCartItem`, `UpdateCart`, `ApplyCartDiscount`).
+         *
+         * Possible values:
+         * * `skip` – Never pass a version. Ignore `options.resourceVersion` if present.
+         * * `explicit` – Every participating command must send `options.resourceVersion`. Missing version on any participating write returns **400** for the whole request (preflight). This is not `skip`.
+         * * `follow` – Seed from the first participating write, then use that cursor for later writes. After the cursor exists, a successful `RefreshCart`, delete, or itemsBatch also bumps it.
+         *
+         * An invalid value returns **400** for the whole request before any command runs.
+         *
+         */
+        versioning?: 'skip' | 'explicit' | 'follow';
+    };
+    url: '/cart/{tenant}/carts/{cartId}/execute';
+};
 
 /** A cart as returned by the Cart service (all generated fields). */
 type Cart = Cart$1;
@@ -1949,6 +2231,50 @@ type CartUpdateInput = UpdateCart;
 type CartDiscount = DiscountResponse;
 /** Lead-time and non-delivery-time restrictions for a cart (`GET …/dtRestrictions`). */
 type CartDeliveryRestrictions = CartDtRestrictions;
+/** Body for applying a discount (`POST /carts/{id}/discounts`, generated). */
+type CartDiscountInput = Discount;
+/**
+ * Request body per command type of {@link CartService.execute}. The spec states
+ * this only in prose — its `data` is an untyped object — so it is the one
+ * hand-written piece. A command type missing here (one Emporix adds after this
+ * was written) keeps the spec's untyped `data` and still works.
+ */
+interface CartCommandBodies {
+    AddCartItem: CartItemInput;
+    UpdateCartItem: CartItemUpdate;
+    AddCartItemsBatch: CartItemInput[];
+    UpdateCartItemsBatch: CartItemsBatchUpdateInput;
+    UpdateCart: CartUpdateInput;
+    ApplyCartDiscount: CartDiscountInput;
+}
+/**
+ * One command of a {@link CartService.execute} chain: `type` picks the REST
+ * operation, `data` is that operation's request body, `options` holds its
+ * remaining path and query parameters (`itemId`, `partial`, `expandCalculation`,
+ * `zipCode`, `countryCode`, `resourceVersion`, `codes`, `discountIndex`). The
+ * cart id is the `execute` path parameter, never a command field.
+ *
+ * `options` is the generated type, where every field is optional: `itemId`
+ * (`UpdateCartItem`, `DeleteCartItem`) and `discountIndex` (`DeleteCartDiscount`)
+ * are required by the server, which reports a missing one on that command.
+ */
+type CartCommand = {
+    [T in ExecuteCommand["type"]]: Omit<ExecuteCommand, "type" | "data"> & {
+        type: T;
+    } & (T extends keyof CartCommandBodies ? {
+        data: CartCommandBodies[T];
+    } : Pick<ExecuteCommand, "data">);
+}[ExecuteCommand["type"]];
+/** `onError` and `versioning` of {@link CartService.execute} — both query parameters (generated). */
+type CartExecuteOptions = NonNullable<PostCartExecuteData["query"]>;
+/** The `207` body of {@link CartService.execute}: one result per command that ran, in order (generated). */
+type CartExecuteResult = ExecuteResponse;
+/**
+ * One entry of {@link CartExecuteResult}`.results`: `code`/`status` of the
+ * equivalent REST call, and as `data` its response body — or its error body
+ * when `code` is not 2xx; absent for a 204 (generated).
+ */
+type CartCommandResult = ExecuteCommandResult;
 /** Cart operations. Every method requires an explicit customer/anonymous context. */
 declare class CartService {
     private readonly ctx;
@@ -2116,6 +2442,31 @@ declare class CartService {
     removeDiscountByIndex(cartId: string, discountIndex: string, auth: AuthContext): Promise<Cart>;
     /** Retrieves the cart's lead-time and non-delivery-time restrictions (`GET /carts/{cartId}/dtRestrictions`). */
     getDeliveryRestrictions(cartId: string, auth: AuthContext): Promise<CartDeliveryRestrictions>;
+    /**
+     * Runs up to 10 cart commands on this cart in one request, in order
+     * (`POST /carts/{cartId}/execute`). The typical chain is `AddCartItem` then
+     * `GetCart`: the calculated cart comes back without a second round trip.
+     *
+     * - `onError: "fail"` (default) stops at the first command that does not
+     *   answer 2xx and **throws the error that command's REST call would have
+     *   thrown** — an `EmporixNotFoundError` for a 404, … — with the command's
+     *   error body. The commands before it **have already been applied**.
+     * - `onError: "resume"` runs every command and resolves with all results;
+     *   check each `code`.
+     * - A `400` for the whole request (no commands or more than 10, an unknown
+     *   type, `versioning: "explicit"` without a `resourceVersion`) means no
+     *   command ran.
+     *
+     * The request takes about as long as its commands together — size the
+     * client's `timeouts.readMs` for long chains. It is never retried: a replay
+     * would apply the writes twice.
+     *
+     * `auth` is forwarded unguarded: a customer or anonymous token works on the
+     * shopper's own cart; a service token needs `cart.cart_manage`, plus
+     * `cart.cart_manage_external_prices` when a command carries an external
+     * price, product, fee or discount.
+     */
+    execute(cartId: string, commands: CartCommand[], auth: AuthContext, opts?: CartExecuteOptions): Promise<CartExecuteResult>;
 }
 
-export { type Cart, type CartAddress, type CartCreated, type CartDeliveryRestrictions, type CartDiscount, type CartItem, type CartItemBatchEntry, type CartItemInput, type CartItemUpdate, type CartItemsBatchResponse, type CartItemsBatchUpdateInput, type CartItemsBatchUpdateResult, type CartSearchInput, CartService, type CartSummary, type CartUpdateInput, type CartValidationResult, type CreateCartInput };
+export { type Cart, type CartAddress, type CartCommand, type CartCommandBodies, type CartCommandResult, type CartCreated, type CartDeliveryRestrictions, type CartDiscount, type CartDiscountInput, type CartExecuteOptions, type CartExecuteResult, type CartItem, type CartItemBatchEntry, type CartItemInput, type CartItemUpdate, type CartItemsBatchResponse, type CartItemsBatchUpdateInput, type CartItemsBatchUpdateResult, type CartSearchInput, CartService, type CartSummary, type CartUpdateInput, type CartValidationResult, type CreateCartInput };