@usethrottle/cart 3.12.0 → 3.13.0

package/README.md

@@ -144,6 +144,127 @@ button — checkout still works. Omitting `returnUrl` or `cancelUrl` falls back
 to Throttle's own `/complete` page and this same hosted cart page,
 respectively.
 
+### Resolved carts
+
+A resolved cart's lines are priced by an installed app (a line resolver, such
+as Product Catalog), never by the browser. Create the session with
+`lineResolver` and the environment's `currency`, then add lines by
+`referenceId`. Throttle asks the app for the price, stock and limits on every
+add, quantity change, sign-in merge and checkout.
+
+```ts
+import {
+  QuantityUnavailableError,
+  LineNotPurchasableError,
+  LineResolverUnavailableError,
+  CartPricesChangedError,
+} from '@usethrottle/cart';
+
+await cart.create({
+  currency: 'USD', // required with lineResolver; must be the environment's currency
+  lineResolver: { extensionId: '0b6a3c1e-8d2f-4a5b-9c7d-1e2f3a4b5c6d' },
+  locale: 'en-US', // optional, passed to the app
+});
+
+try {
+  await cart.addResolvedItem({ referenceId: 'TSHIRT-BLUE-M', quantity: 2 });
+} catch (e) {
+  if (e instanceof QuantityUnavailableError) showMessage(`Only ${e.maxQuantity ?? 0} available`);
+  else if (e instanceof LineNotPurchasableError) showMessage('No longer available');
+  else if (e instanceof LineResolverUnavailableError) showMessage('Try again in a moment');
+  else throw e;
+}
+
+// Re-check every owned line (for example when the buyer comes back to the cart).
+const { changed, ...current } = await cart.refresh();
+
+try {
+  const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
+  location.href = checkoutUrl;
+} catch (e) {
+  if (e instanceof CartPricesChangedError) {
+    // The new prices are already applied; show them, then check out again.
+    if (e.cart) render(e.cart);
+  } else throw e;
+}
+```
+
+`addResolvedItem()` sends only `referenceId`, `quantity` (default 1) and
+`metadata`. The app sets the name, price and image: sending `unitPrice`,
+`name`, `imageUrl`, `taxAmount`, `discountAmount`, a reserved metadata key
+(`lineResolver`, `requiresShipping`) or a metadata key that changes a shipping
+or tax quote answers `400 price_locked` (`PriceLockedError.fields` names them).
+`updateItem()` keeps working for quantity and other metadata; a quantity change
+is re-checked by the app.
+
+A resolved cart carries `lineResolver: { extensionId }` (`extensionId` is
+`null` if the app's installation is gone), and each line carries `resolution`:
+`null` on a line the app does not own, otherwise `{ status, code, maxQuantity,
+minQuantity }`. `status` is `resolved`, `refused` (the app refused the line;
+`code` says why, for example `OUT_OF_STOCK`) or `stale` (the last re-check
+failed; checkout re-checks it). Carts created without `lineResolver` have
+neither key.
+
+Shipping on a resolved cart is priced by Throttle, not the browser: pick a
+method Throttle quotes for the cart with
+`cart.selectShippingMethod({ methodId })`, which sends only the method id (the
+cart needs a shipping address first). A method Throttle does not quote answers
+`422 shipping_method_unavailable`. If you use `selectShipping()` instead, a
+`rateAmount` or `currency` different from the quote answers `400
+price_locked`. There is no flat-rate fallback (no selection means shipping
+is not calculated yet). The checkout hand-off re-checks every line and
+re-quotes shipping; any change answers `409 cart_prices_changed` with the
+updated `cart` and, when shipping moved, `shipping: { methodId,
+previousAmount, amount, reason? }` (`amount` is `null` with `reason`
+`method_unavailable` or `quote_unavailable`).
+
+#### From your server (`CartClient`)
+
+Other apps can integrate the same way with a secret key. Create the cart with
+`lineResolver` (and the environment's `currency`), optionally pricing up to 50
+lines in one call with `lineItems` (all or nothing), then add lines by
+`referenceId`:
+
+```ts
+const cart = await client.carts.create({
+  applicationId,
+  currency: 'USD',
+  lineResolver: { extensionId: '0b6a3c1e-8d2f-4a5b-9c7d-1e2f3a4b5c6d' },
+  locale: 'en-GB',
+  lineItems: [{ referenceId: 'TSHIRT-BLUE-M', quantity: 2 }],
+});
+const line = await client.items.addResolvedItem(cart.id, { referenceId: 'MUG-WHITE', quantity: 1 });
+```
+
+A server cart has no refresh: `refresh()` exists only on a browser cart
+session (`CartSessionClient`). From the server, a line is re-checked with the
+app when you change its quantity with `items.update(cartId, itemId,
+{ quantity })`. To re-check the whole cart, mint a hosted-cart session for it
+(`POST /api/v1/carts/{id}/sessions`, which answers `{ sessionId, cartUrl,
+expiresAt }`) and call `CartSessionClient.forSession(sessionId).refresh()`. An
+owned line's `unitPrice`, `taxAmount`, `discountAmount` and reserved metadata
+keys answer `400 price_locked` for every caller. Both clients throw the same
+typed errors:
+
+| Error class | Status / code | Typed fields (`details`) |
+| --- | --- | --- |
+| `PriceLockedError` | `400 price_locked` | `fields` |
+| `QuantityUnavailableError` | `409 quantity_unavailable` | `reason`, `maxQuantity` (or `null`) |
+| `LineNotPurchasableError` | `422 line_not_purchasable` | `reason` on an add; `lines` at checkout |
+| `LineResolverUnavailableError` | `503 line_resolver_unavailable` | `reason` (or `null`); nothing changed, retry |
+| `LineResolverNotAvailableError` | `422 line_resolver_not_available` | `reason`; the app is not installed |
+| `CurrencyNotEnabledError` | `422 currency_not_enabled` | `details.currency`, `details.enabledCurrencies` |
+| `ResolvedLinesRequiredError` | `422 resolved_lines_required` | the store only accepts resolved lines |
+| `LineLimitReachedError` | `422 line_limit_reached` | `details.maxLines` (50 per app) |
+| `CartPricesChangedError` | `409 cart_prices_changed` | `cart`, `shipping` (or `null`) |
+| `ShippingMethodUnavailableError` | `422 shipping_method_unavailable` | |
+| `ShippingQuoteUnavailableError` | `503 shipping_quote_unavailable` | nothing changed, retry |
+| `AmountTooLargeError` | `422 amount_too_large` | lower the quantity |
+| `CartChangedError` | `409 cart_changed` | the cart changed during the add; retry |
+
+Every class extends `ThrottleApiError` (and so `ThrottleError`), so existing
+`instanceof ThrottleApiError` and `e.code` checks keep working.
+
 ## Net-N invoice terms
 
 Cart-level invoice terms are optional. Pass `netN` on cart create or update to

package/dist/index.cjs

@@ -20,11 +20,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AmountTooLargeError: () => AmountTooLargeError,
+  CartChangedError: () => CartChangedError,
   CartClient: () => CartClient,
   CartNotFoundError: () => CartNotFoundError,
   CartNotOpenError: () => CartNotOpenError,
+  CartPricesChangedError: () => CartPricesChangedError,
   CartSessionClient: () => CartSessionClient,
   CartTimeoutError: () => CartTimeoutError,
+  CurrencyNotEnabledError: () => CurrencyNotEnabledError,
+  LineLimitReachedError: () => LineLimitReachedError,
+  LineNotPurchasableError: () => LineNotPurchasableError,
+  LineResolverNotAvailableError: () => LineResolverNotAvailableError,
+  LineResolverUnavailableError: () => LineResolverUnavailableError,
+  PriceLockedError: () => PriceLockedError,
+  QuantityUnavailableError: () => QuantityUnavailableError,
+  ResolvedLinesRequiredError: () => ResolvedLinesRequiredError,
+  ShippingMethodUnavailableError: () => ShippingMethodUnavailableError,
+  ShippingQuoteUnavailableError: () => ShippingQuoteUnavailableError,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
   ThrottleApiError: () => ThrottleApiError,
   ThrottleError: () => import_errors2.ThrottleError,
@@ -77,6 +90,130 @@ var CartTimeoutError = class extends import_errors.ThrottleError {
     this.name = "CartTimeoutError";
   }
 };
+function coded(code, statusCode, args) {
+  return {
+    code,
+    statusCode: args.statusCode ?? statusCode,
+    message: args.message,
+    details: args.details,
+    responseHeaders: args.responseHeaders
+  };
+}
+var str = (v) => typeof v === "string" ? v : null;
+var num = (v) => typeof v === "number" ? v : null;
+var PriceLockedError = class extends ThrottleApiError {
+  /** The refused fields, e.g. `['unitPrice', 'metadata.lineResolver']`. */
+  fields;
+  constructor(args) {
+    super(coded("price_locked", 400, args));
+    this.name = "PriceLockedError";
+    this.fields = Array.isArray(args.details?.fields) ? args.details.fields : [];
+  }
+};
+var QuantityUnavailableError = class extends ThrottleApiError {
+  reason;
+  maxQuantity;
+  constructor(args) {
+    super(coded("quantity_unavailable", 409, args));
+    this.name = "QuantityUnavailableError";
+    this.reason = str(args.details?.reason);
+    this.maxQuantity = num(args.details?.maxQuantity);
+  }
+};
+var LineNotPurchasableError = class extends ThrottleApiError {
+  reason;
+  lines;
+  constructor(args) {
+    super(coded("line_not_purchasable", 422, args));
+    this.name = "LineNotPurchasableError";
+    this.reason = str(args.details?.reason);
+    this.lines = Array.isArray(args.details?.lines) ? args.details.lines : null;
+  }
+};
+var LineResolverUnavailableError = class extends ThrottleApiError {
+  reason;
+  constructor(args) {
+    super(coded("line_resolver_unavailable", 503, args));
+    this.name = "LineResolverUnavailableError";
+    this.reason = str(args.details?.reason);
+  }
+};
+var LineResolverNotAvailableError = class extends ThrottleApiError {
+  reason;
+  constructor(args) {
+    super(coded("line_resolver_not_available", 422, args));
+    this.name = "LineResolverNotAvailableError";
+    this.reason = str(args.details?.reason);
+  }
+};
+var CurrencyNotEnabledError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("currency_not_enabled", 422, args));
+    this.name = "CurrencyNotEnabledError";
+  }
+};
+var ResolvedLinesRequiredError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("resolved_lines_required", 422, args));
+    this.name = "ResolvedLinesRequiredError";
+  }
+};
+var LineLimitReachedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("line_limit_reached", 422, args));
+    this.name = "LineLimitReachedError";
+  }
+};
+var CartPricesChangedError = class extends ThrottleApiError {
+  cart;
+  shipping;
+  constructor(args) {
+    super(coded("cart_prices_changed", 409, args));
+    this.name = "CartPricesChangedError";
+    const d = args.details;
+    this.cart = d?.cart && typeof d.cart === "object" ? d.cart : null;
+    this.shipping = d?.shipping && typeof d.shipping === "object" ? d.shipping : null;
+  }
+};
+var ShippingMethodUnavailableError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("shipping_method_unavailable", 422, args));
+    this.name = "ShippingMethodUnavailableError";
+  }
+};
+var ShippingQuoteUnavailableError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("shipping_quote_unavailable", 503, args));
+    this.name = "ShippingQuoteUnavailableError";
+  }
+};
+var AmountTooLargeError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("amount_too_large", 422, args));
+    this.name = "AmountTooLargeError";
+  }
+};
+var CartChangedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("cart_changed", 409, args));
+    this.name = "CartChangedError";
+  }
+};
+var RESOLVED_CART_ERRORS = {
+  price_locked: PriceLockedError,
+  quantity_unavailable: QuantityUnavailableError,
+  line_not_purchasable: LineNotPurchasableError,
+  line_resolver_unavailable: LineResolverUnavailableError,
+  line_resolver_not_available: LineResolverNotAvailableError,
+  currency_not_enabled: CurrencyNotEnabledError,
+  resolved_lines_required: ResolvedLinesRequiredError,
+  line_limit_reached: LineLimitReachedError,
+  cart_prices_changed: CartPricesChangedError,
+  shipping_method_unavailable: ShippingMethodUnavailableError,
+  shipping_quote_unavailable: ShippingQuoteUnavailableError,
+  amount_too_large: AmountTooLargeError,
+  cart_changed: CartChangedError
+};
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
     return new CartNotOpenError({
@@ -94,6 +231,15 @@ function cartErrorFromResponse(args) {
       responseHeaders: args.responseHeaders
     });
   }
+  const ResolvedCartError = Object.prototype.hasOwnProperty.call(RESOLVED_CART_ERRORS, args.code) ? RESOLVED_CART_ERRORS[args.code] : void 0;
+  if (ResolvedCartError) {
+    return new ResolvedCartError({
+      message: args.message,
+      statusCode: args.statusCode,
+      details: args.details,
+      responseHeaders: args.responseHeaders
+    });
+  }
   return new ThrottleApiError(args);
 }
 
@@ -151,6 +297,17 @@ var CartClient = class {
   get items() {
     return {
       add: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, input),
+      /**
+       * 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, input) => {
+        const body = { referenceId: input.referenceId };
+        if (input.quantity !== void 0) body.quantity = input.quantity;
+        if (input.metadata !== void 0) body.metadata = input.metadata;
+        return this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, body);
+      },
       update: (cartId, itemId, input) => this.request("PATCH", `/api/v1/carts/${segment(cartId)}/items/${segment(itemId)}`, input),
       remove: (cartId, itemId) => this.request("DELETE", `/api/v1/carts/${segment(cartId)}/items/${segment(itemId)}`)
     };
@@ -323,6 +480,32 @@ var CartSessionClient = class _CartSessionClient {
   async addItem(input) {
     return (await this.request("POST", `${this.basePath()}/items`, input)).cart;
   }
+  /**
+   * 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`.
+   */
+  async addResolvedItem(input) {
+    const body = { referenceId: input.referenceId };
+    if (input.quantity !== void 0) body.quantity = input.quantity;
+    if (input.metadata !== void 0) body.metadata = input.metadata;
+    return (await this.request("POST", `${this.basePath()}/items`, body)).cart;
+  }
+  /**
+   * 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.
+   */
+  async refresh() {
+    const data = await this.request(
+      "POST",
+      `${this.basePath()}/refresh`,
+      {}
+    );
+    return { ...data.cart, changed: data.changed };
+  }
   async updateItem(itemId, input) {
     return (await this.request(
       "PATCH",
@@ -336,6 +519,17 @@ var CartSessionClient = class _CartSessionClient {
   async selectShipping(input) {
     return (await this.request("POST", `${this.basePath()}/shipping`, input)).cart;
   }
+  /**
+   * 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`.
+   */
+  async selectShippingMethod(input) {
+    return (await this.request("POST", `${this.basePath()}/shipping`, {
+      methodId: input.methodId
+    })).cart;
+  }
   async clearShipping() {
     return (await this.request("DELETE", `${this.basePath()}/shipping`)).cart;
   }
@@ -424,11 +618,24 @@ var CartSessionClient = class _CartSessionClient {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AmountTooLargeError,
+  CartChangedError,
   CartClient,
   CartNotFoundError,
   CartNotOpenError,
+  CartPricesChangedError,
   CartSessionClient,
   CartTimeoutError,
+  CurrencyNotEnabledError,
+  LineLimitReachedError,
+  LineNotPurchasableError,
+  LineResolverNotAvailableError,
+  LineResolverUnavailableError,
+  PriceLockedError,
+  QuantityUnavailableError,
+  ResolvedLinesRequiredError,
+  ShippingMethodUnavailableError,
+  ShippingQuoteUnavailableError,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError,

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 —
@@ -165,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;
@@ -219,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;
@@ -478,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>;
     };
@@ -567,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;
@@ -660,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>;
@@ -759,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.
@@ -771,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 };

package/dist/index.d.ts

@@ -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 —
@@ -165,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;
@@ -219,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;
@@ -478,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>;
     };
@@ -567,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;
@@ -660,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>;
@@ -759,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.
@@ -771,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 };

package/dist/index.js

@@ -42,6 +42,130 @@ var CartTimeoutError = class extends ThrottleError {
     this.name = "CartTimeoutError";
   }
 };
+function coded(code, statusCode, args) {
+  return {
+    code,
+    statusCode: args.statusCode ?? statusCode,
+    message: args.message,
+    details: args.details,
+    responseHeaders: args.responseHeaders
+  };
+}
+var str = (v) => typeof v === "string" ? v : null;
+var num = (v) => typeof v === "number" ? v : null;
+var PriceLockedError = class extends ThrottleApiError {
+  /** The refused fields, e.g. `['unitPrice', 'metadata.lineResolver']`. */
+  fields;
+  constructor(args) {
+    super(coded("price_locked", 400, args));
+    this.name = "PriceLockedError";
+    this.fields = Array.isArray(args.details?.fields) ? args.details.fields : [];
+  }
+};
+var QuantityUnavailableError = class extends ThrottleApiError {
+  reason;
+  maxQuantity;
+  constructor(args) {
+    super(coded("quantity_unavailable", 409, args));
+    this.name = "QuantityUnavailableError";
+    this.reason = str(args.details?.reason);
+    this.maxQuantity = num(args.details?.maxQuantity);
+  }
+};
+var LineNotPurchasableError = class extends ThrottleApiError {
+  reason;
+  lines;
+  constructor(args) {
+    super(coded("line_not_purchasable", 422, args));
+    this.name = "LineNotPurchasableError";
+    this.reason = str(args.details?.reason);
+    this.lines = Array.isArray(args.details?.lines) ? args.details.lines : null;
+  }
+};
+var LineResolverUnavailableError = class extends ThrottleApiError {
+  reason;
+  constructor(args) {
+    super(coded("line_resolver_unavailable", 503, args));
+    this.name = "LineResolverUnavailableError";
+    this.reason = str(args.details?.reason);
+  }
+};
+var LineResolverNotAvailableError = class extends ThrottleApiError {
+  reason;
+  constructor(args) {
+    super(coded("line_resolver_not_available", 422, args));
+    this.name = "LineResolverNotAvailableError";
+    this.reason = str(args.details?.reason);
+  }
+};
+var CurrencyNotEnabledError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("currency_not_enabled", 422, args));
+    this.name = "CurrencyNotEnabledError";
+  }
+};
+var ResolvedLinesRequiredError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("resolved_lines_required", 422, args));
+    this.name = "ResolvedLinesRequiredError";
+  }
+};
+var LineLimitReachedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("line_limit_reached", 422, args));
+    this.name = "LineLimitReachedError";
+  }
+};
+var CartPricesChangedError = class extends ThrottleApiError {
+  cart;
+  shipping;
+  constructor(args) {
+    super(coded("cart_prices_changed", 409, args));
+    this.name = "CartPricesChangedError";
+    const d = args.details;
+    this.cart = d?.cart && typeof d.cart === "object" ? d.cart : null;
+    this.shipping = d?.shipping && typeof d.shipping === "object" ? d.shipping : null;
+  }
+};
+var ShippingMethodUnavailableError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("shipping_method_unavailable", 422, args));
+    this.name = "ShippingMethodUnavailableError";
+  }
+};
+var ShippingQuoteUnavailableError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("shipping_quote_unavailable", 503, args));
+    this.name = "ShippingQuoteUnavailableError";
+  }
+};
+var AmountTooLargeError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("amount_too_large", 422, args));
+    this.name = "AmountTooLargeError";
+  }
+};
+var CartChangedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("cart_changed", 409, args));
+    this.name = "CartChangedError";
+  }
+};
+var RESOLVED_CART_ERRORS = {
+  price_locked: PriceLockedError,
+  quantity_unavailable: QuantityUnavailableError,
+  line_not_purchasable: LineNotPurchasableError,
+  line_resolver_unavailable: LineResolverUnavailableError,
+  line_resolver_not_available: LineResolverNotAvailableError,
+  currency_not_enabled: CurrencyNotEnabledError,
+  resolved_lines_required: ResolvedLinesRequiredError,
+  line_limit_reached: LineLimitReachedError,
+  cart_prices_changed: CartPricesChangedError,
+  shipping_method_unavailable: ShippingMethodUnavailableError,
+  shipping_quote_unavailable: ShippingQuoteUnavailableError,
+  amount_too_large: AmountTooLargeError,
+  cart_changed: CartChangedError
+};
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
     return new CartNotOpenError({
@@ -59,6 +183,15 @@ function cartErrorFromResponse(args) {
       responseHeaders: args.responseHeaders
     });
   }
+  const ResolvedCartError = Object.prototype.hasOwnProperty.call(RESOLVED_CART_ERRORS, args.code) ? RESOLVED_CART_ERRORS[args.code] : void 0;
+  if (ResolvedCartError) {
+    return new ResolvedCartError({
+      message: args.message,
+      statusCode: args.statusCode,
+      details: args.details,
+      responseHeaders: args.responseHeaders
+    });
+  }
   return new ThrottleApiError(args);
 }
 
@@ -116,6 +249,17 @@ var CartClient = class {
   get items() {
     return {
       add: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, input),
+      /**
+       * 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, input) => {
+        const body = { referenceId: input.referenceId };
+        if (input.quantity !== void 0) body.quantity = input.quantity;
+        if (input.metadata !== void 0) body.metadata = input.metadata;
+        return this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, body);
+      },
       update: (cartId, itemId, input) => this.request("PATCH", `/api/v1/carts/${segment(cartId)}/items/${segment(itemId)}`, input),
       remove: (cartId, itemId) => this.request("DELETE", `/api/v1/carts/${segment(cartId)}/items/${segment(itemId)}`)
     };
@@ -288,6 +432,32 @@ var CartSessionClient = class _CartSessionClient {
   async addItem(input) {
     return (await this.request("POST", `${this.basePath()}/items`, input)).cart;
   }
+  /**
+   * 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`.
+   */
+  async addResolvedItem(input) {
+    const body = { referenceId: input.referenceId };
+    if (input.quantity !== void 0) body.quantity = input.quantity;
+    if (input.metadata !== void 0) body.metadata = input.metadata;
+    return (await this.request("POST", `${this.basePath()}/items`, body)).cart;
+  }
+  /**
+   * 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.
+   */
+  async refresh() {
+    const data = await this.request(
+      "POST",
+      `${this.basePath()}/refresh`,
+      {}
+    );
+    return { ...data.cart, changed: data.changed };
+  }
   async updateItem(itemId, input) {
     return (await this.request(
       "PATCH",
@@ -301,6 +471,17 @@ var CartSessionClient = class _CartSessionClient {
   async selectShipping(input) {
     return (await this.request("POST", `${this.basePath()}/shipping`, input)).cart;
   }
+  /**
+   * 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`.
+   */
+  async selectShippingMethod(input) {
+    return (await this.request("POST", `${this.basePath()}/shipping`, {
+      methodId: input.methodId
+    })).cart;
+  }
   async clearShipping() {
     return (await this.request("DELETE", `${this.basePath()}/shipping`)).cart;
   }
@@ -388,11 +569,24 @@ var CartSessionClient = class _CartSessionClient {
   }
 };
 export {
+  AmountTooLargeError,
+  CartChangedError,
   CartClient,
   CartNotFoundError,
   CartNotOpenError,
+  CartPricesChangedError,
   CartSessionClient,
   CartTimeoutError,
+  CurrencyNotEnabledError,
+  LineLimitReachedError,
+  LineNotPurchasableError,
+  LineResolverNotAvailableError,
+  LineResolverUnavailableError,
+  PriceLockedError,
+  QuantityUnavailableError,
+  ResolvedLinesRequiredError,
+  ShippingMethodUnavailableError,
+  ShippingQuoteUnavailableError,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError2 as ThrottleError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/cart",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",