@usethrottle/cart 3.11.1 → 3.13.0

package/dist/index.d.cts

@@ -60,6 +60,14 @@ interface Cart {
     lineItems?: LineItem[];
     createdAt: string;
     updatedAt: string;
+    /**
+     * Resolved carts only: the installed app that prices the cart's owned
+     * lines. `extensionId` is null when the installation can no longer be
+     * found. Absent on a cart created without `lineResolver`.
+     */
+    lineResolver?: {
+        extensionId: string | null;
+    };
 }
 /**
  * The cart as the session (browser, opaque-token) surface returns it —
@@ -97,6 +105,19 @@ interface LineRecurringInput {
     intervalCount?: number;
     totalPayments?: number;
     trialDays?: number;
+    /**
+     * Custom installment schedule: 2-60 payments that differ in amount (per unit,
+     * minor units) and in the gap before each one. Row 0 has no gap. Replaces
+     * `interval`/`intervalUnit`/`intervalCount`/`totalPayments`/`trialDays`, which
+     * must be omitted or agree with it. The line's `unitPrice` must equal row 0.
+     */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit?: SubscriptionIntervalUnit;
+        intervalCount?: number;
+    }>;
+    /** Read-only echo on responses: the sum of every row's per-unit amount. Ignored on input. */
+    scheduleUnitTotal?: number;
 }
 /** A merchant-declared subscription line's stored terms (it carries `plan`). */
 interface StoredLineRecurring {
@@ -111,6 +132,14 @@ interface StoredLineRecurring {
     amount: number | null;
     /** Display mirror of `totalPayments`. */
     count: number | null;
+    /** Present only on a custom installment schedule line. */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit: string | null;
+        intervalCount: number | null;
+    }>;
+    /** Present only on a schedule line: the sum of every row's per-unit amount. */
+    scheduleUnitTotal?: number;
 }
 /** The plan line Throttle adds for a checkout session `recurring` intent. */
 interface LegacyLineRecurring {
@@ -144,6 +173,55 @@ interface LineItem {
     imageUrl: string | null;
     position: number;
     metadata: Record<string, unknown>;
+    /**
+     * Resolved carts only: the app's last answer for this line, or null on a
+     * line the app does not own. Absent on an unresolved cart.
+     */
+    resolution?: LineResolution | null;
+}
+/**
+ * An owned line's state on a resolved cart.
+ *
+ * - `resolved`: the app priced the line on its last answer.
+ * - `refused`: the app refused the line on its last answer; `code` says why
+ *   (`OUT_OF_STOCK`, `QUANTITY_UNAVAILABLE`, `BELOW_MIN`, `ABOVE_MAX`,
+ *   `NOT_FOUND`, `NOT_PURCHASABLE`, `NO_PRICE_IN_CURRENCY`,
+ *   `PRICE_SOURCE_MISMATCH`).
+ * - `stale`: the last re-resolve failed; the line keeps its earlier price and
+ *   `code` keeps any earlier refusal. Checkout re-resolves it.
+ *
+ * `maxQuantity` / `minQuantity` are the limits from the app's last answer
+ * (a refusal's own `maxQuantity` wins), or null.
+ */
+interface LineResolution {
+    status: 'resolved' | 'refused' | 'stale';
+    code: string | null;
+    maxQuantity: number | null;
+    minQuantity: number | null;
+}
+/**
+ * A line of a resolved cart: the app sets its name, price and image, so the
+ * browser sends only which item and how many.
+ */
+interface AddResolvedLineItemInput {
+    /** The app's id for the item (for Product Catalog, the variant SKU). */
+    referenceId: string;
+    /** 1 to 10,000. Defaults to 1. */
+    quantity?: number;
+    /**
+     * Buyer metadata. The reserved keys (`lineResolver`, `requiresShipping`)
+     * and the keys that change a shipping or tax quote are set by the app and
+     * answer `400 price_locked`.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pick a shipping method on a resolved cart (or in an environment where
+ * browser carts may only hold resolved lines): Throttle quotes the amount,
+ * so only the method id is sent.
+ */
+interface SelectShippingMethodInput {
+    methodId: string;
 }
 interface SelectedShipping {
     methodId: string;
@@ -198,6 +276,24 @@ interface CreateCartInput {
     currency?: string;
     netN?: number | null;
     metadata?: Record<string, unknown>;
+    /**
+     * Make this a resolved cart: the installed app with this extension id
+     * prices its lines (add them with `items.addResolvedItem()`). Requires
+     * `currency`, which must be the environment's currency.
+     */
+    lineResolver?: {
+        extensionId: string;
+    };
+    /** Buyer locale passed to the app that prices the lines (BCP 47, e.g. `en-GB`). */
+    locale?: string;
+    /**
+     * Resolved lines to add at create (requires `lineResolver`): 1 to 50, each
+     * `referenceId` at most once, priced in one call to the app, all or nothing.
+     */
+    lineItems?: Array<{
+        referenceId: string;
+        quantity?: number;
+    }>;
 }
 interface UpdateCartInput {
     customerId?: string;
@@ -457,6 +553,12 @@ declare class CartClient {
     };
     get items(): {
         add: (cartId: string, input: AddLineItemInput) => Promise<LineItem>;
+        /**
+         * Add a line to a resolved cart (one created with `lineResolver`). Only
+         * the item, quantity and metadata are sent; the app sets the name, price
+         * and image. Refusals throw the typed resolver errors.
+         */
+        addResolvedItem: (cartId: string, input: AddResolvedLineItemInput) => Promise<LineItem>;
         update: (cartId: string, itemId: string, input: UpdateLineItemInput) => Promise<LineItem>;
         remove: (cartId: string, itemId: string) => Promise<void>;
     };
@@ -546,6 +648,16 @@ interface CreateCartSessionInput {
     currency?: string;
     netN?: number;
     metadata?: Record<string, unknown>;
+    /**
+     * Make this a resolved cart: the installed app with this extension id
+     * prices its lines (add them with `addResolvedItem()`). Requires
+     * `currency`, which must be the environment's currency.
+     */
+    lineResolver?: {
+        extensionId: string;
+    };
+    /** Buyer locale passed to the app that prices the lines (BCP 47, e.g. `en-US`). */
+    locale?: string;
 }
 interface CartBranding {
     logoUrl: string | null;
@@ -639,9 +751,32 @@ declare class CartSessionClient {
      */
     summary(): Promise<CartSessionSummary>;
     addItem(input: AddLineItemInput): Promise<CartSessionCart>;
+    /**
+     * Add a line to a resolved cart (one created with `lineResolver`). Only the
+     * item, quantity and metadata are sent; the app sets the name, price and
+     * image. A refusal throws `QuantityUnavailableError`,
+     * `LineNotPurchasableError` or `LineResolverUnavailableError`.
+     */
+    addResolvedItem(input: AddResolvedLineItemInput): Promise<CartSessionCart>;
+    /**
+     * Ask the app that prices a resolved cart to re-check every line it owns.
+     * `changed` is true when a price, name or refusal changed. An unresolved
+     * cart comes back unchanged. Throws `LineResolverUnavailableError` (nothing
+     * changed) when the app does not answer.
+     */
+    refresh(): Promise<CartSessionCart & {
+        changed: boolean;
+    }>;
     updateItem(itemId: string, input: UpdateLineItemInput): Promise<CartSessionCart>;
     removeItem(itemId: string): Promise<CartSessionCart>;
     selectShipping(input: SelectShippingInput): Promise<CartSessionCart>;
+    /**
+     * Pick a shipping method on a resolved cart. Throttle quotes the amount, so
+     * only `methodId` is sent. A method Throttle does not quote for the cart
+     * (it needs a shipping address first) throws `ShippingMethodUnavailableError`;
+     * a failed quote throws `ShippingQuoteUnavailableError`.
+     */
+    selectShippingMethod(input: SelectShippingMethodInput): Promise<CartSessionCart>;
     clearShipping(): Promise<CartSessionCart>;
     applyDiscount(code: string): Promise<CartSessionCart>;
     removeDiscount(): Promise<CartSessionCart>;
@@ -738,6 +873,174 @@ declare class CartTimeoutError extends ThrottleError {
         path?: string;
     });
 }
+/** Constructor arguments shared by the resolved-cart error classes. */
+interface CartErrorArgs {
+    message: string;
+    statusCode?: number;
+    details?: Record<string, unknown>;
+    responseHeaders?: ThrottleErrorArgs['responseHeaders'];
+}
+/** `details` of `400 price_locked`: the request fields the app sets. */
+type PriceLockedDetails = {
+    fields: string[];
+};
+/**
+ * `400 price_locked`: the request sent a field the pricing app owns (a
+ * price, name, image, or a reserved or quote-affecting metadata key). On a
+ * resolved cart, add lines with `addResolvedItem()`.
+ */
+declare class PriceLockedError extends ThrottleApiError {
+    readonly details?: PriceLockedDetails;
+    /** The refused fields, e.g. `['unitPrice', 'metadata.lineResolver']`. */
+    readonly fields: string[];
+    constructor(args: CartErrorArgs);
+}
+/** `details` of `409 quantity_unavailable`. */
+type QuantityUnavailableDetails = {
+    /** `OUT_OF_STOCK`, `QUANTITY_UNAVAILABLE`, `BELOW_MIN`, `ABOVE_MAX` or `MAX_LINE_ITEM_QUANTITY`. */
+    reason: string;
+    maxQuantity?: number;
+    referenceId?: string;
+    itemId?: string;
+};
+/**
+ * `409 quantity_unavailable`: the app refused the quantity. Nothing in the
+ * cart changed. `maxQuantity` is how many can be ordered, when known.
+ */
+declare class QuantityUnavailableError extends ThrottleApiError {
+    readonly details?: QuantityUnavailableDetails;
+    readonly reason: string | null;
+    readonly maxQuantity: number | null;
+    constructor(args: CartErrorArgs);
+}
+/** A line refused at checkout hand-off (`line_not_purchasable` `details.lines`). */
+type RefusedCartLine = {
+    itemId: string;
+    referenceId: string;
+    code: string;
+    maxQuantity?: number;
+};
+/**
+ * `details` of `422 line_not_purchasable`: `{ reason, referenceId, itemId? }`
+ * on an add or quantity change, `{ lines }` at the checkout hand-off.
+ */
+type LineNotPurchasableDetails = {
+    /** `NOT_FOUND`, `NOT_PURCHASABLE`, `NO_PRICE_IN_CURRENCY` or `PRICE_SOURCE_MISMATCH`. */
+    reason?: string;
+    referenceId?: string;
+    itemId?: string;
+    lines?: RefusedCartLine[];
+};
+/**
+ * `422 line_not_purchasable`: the app refused the item (`reason`), or, at
+ * checkout, some lines cannot be bought (`lines`; remove them or change their
+ * quantity, then check out again).
+ */
+declare class LineNotPurchasableError extends ThrottleApiError {
+    readonly details?: LineNotPurchasableDetails;
+    readonly reason: string | null;
+    readonly lines: RefusedCartLine[] | null;
+    constructor(args: CartErrorArgs);
+}
+/** `details` of `503 line_resolver_unavailable`. */
+type LineResolverUnavailableDetails = {
+    reason?: string;
+};
+/**
+ * `503 line_resolver_unavailable`: the app that prices the cart did not
+ * answer (or answered badly). Nothing in the cart changed; retry later.
+ */
+declare class LineResolverUnavailableError extends ThrottleApiError {
+    readonly details?: LineResolverUnavailableDetails;
+    readonly reason: string | null;
+    constructor(args: CartErrorArgs);
+}
+/** `details` of `422 line_resolver_not_available`. */
+type LineResolverNotAvailableDetails = {
+    reason?: string;
+};
+/**
+ * `422 line_resolver_not_available`: the app named in `lineResolver` is not
+ * installed (or cannot price carts) in this environment, so no cart was created.
+ */
+declare class LineResolverNotAvailableError extends ThrottleApiError {
+    readonly details?: LineResolverNotAvailableDetails;
+    readonly reason: string | null;
+    constructor(args: CartErrorArgs);
+}
+/** `details` of `422 currency_not_enabled`. */
+type CurrencyNotEnabledDetails = {
+    currency: string;
+    enabledCurrencies: string[];
+};
+/** `422 currency_not_enabled`: a resolved cart must use the environment's currency. */
+declare class CurrencyNotEnabledError extends ThrottleApiError {
+    readonly details?: CurrencyNotEnabledDetails;
+    constructor(args: CartErrorArgs);
+}
+/**
+ * `422 resolved_lines_required`: the store only accepts cart lines priced by
+ * an installed app; create the cart session with `lineResolver`.
+ */
+declare class ResolvedLinesRequiredError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/** `details` of `422 line_limit_reached`. */
+type LineLimitReachedDetails = {
+    maxLines: number;
+};
+/** `422 line_limit_reached`: a cart holds at most `maxLines` lines priced by one app. */
+declare class LineLimitReachedError extends ThrottleApiError {
+    readonly details?: LineLimitReachedDetails;
+    constructor(args: CartErrorArgs);
+}
+/**
+ * The stored shipping selection after the checkout hand-off re-quoted it.
+ * `amount` is the new quote, or null with a `reason`: `method_unavailable`
+ * (no longer offered, so cleared) or `quote_unavailable` (could not be
+ * quoted now; kept for the next hand-off).
+ */
+type CartShippingChange = {
+    methodId: string;
+    previousAmount: number;
+    amount: number | null;
+    reason?: 'method_unavailable' | 'quote_unavailable';
+};
+/** `details` of `409 cart_prices_changed`. */
+type CartPricesChangedDetails = {
+    cart: CartSessionCart;
+    shipping?: CartShippingChange;
+};
+/**
+ * `409 cart_prices_changed` at checkout: prices (or shipping) changed since
+ * the buyer last saw the cart. The new prices are already applied; show
+ * `cart`, then check out again. `cart` is null when the response carried none.
+ */
+declare class CartPricesChangedError extends ThrottleApiError {
+    readonly details?: CartPricesChangedDetails;
+    readonly cart: CartSessionCart | null;
+    readonly shipping: CartShippingChange | null;
+    constructor(args: CartErrorArgs);
+}
+/**
+ * `422 shipping_method_unavailable`: on a resolved cart shipping is priced by
+ * Throttle; the method is not one Throttle quotes for this cart.
+ */
+declare class ShippingMethodUnavailableError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/** `503 shipping_quote_unavailable`: shipping cannot be priced right now. Nothing changed. */
+declare class ShippingQuoteUnavailableError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/** `422 amount_too_large`: the line or cart amount is larger than a cart can hold. */
+declare class AmountTooLargeError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/** `409 cart_changed`: the cart changed while the item was being added; nothing was added. Retry. */
+declare class CartChangedError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
 /**
  * Map a raw API error envelope to the most specific Cart SDK error class.
  * Falls back to {@link ThrottleApiError} for everything unrecognised.
@@ -750,4 +1053,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineRecurringInput, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AddResolvedLineItemInput, AmountTooLargeError, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartChangedError, CartClient, type CartErrorArgs, type CartEvent, CartNotFoundError, CartNotOpenError, type CartPricesChangedDetails, CartPricesChangedError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, type CartShippingChange, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type CurrencyNotEnabledDetails, CurrencyNotEnabledError, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineLimitReachedDetails, LineLimitReachedError, type LineNotPurchasableDetails, LineNotPurchasableError, type LineRecurringInput, type LineResolution, type LineResolverNotAvailableDetails, LineResolverNotAvailableError, type LineResolverUnavailableDetails, LineResolverUnavailableError, type Order, type PriceLockedDetails, PriceLockedError, type QuantityUnavailableDetails, QuantityUnavailableError, type RefusedCartLine, ResolvedLinesRequiredError, type SelectShippingInput, type SelectShippingMethodInput, type SelectedShipping, ShippingMethodUnavailableError, ShippingQuoteUnavailableError, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };