@usethrottle/cart 3.12.0 → 3.14.0

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,25 @@ 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`: the environment's currency or one of its extra cart
+     * currencies (`cartCurrencies`).
+     */
+    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 +554,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 +649,17 @@ 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`: the environment's currency or one of its extra cart
+     * currencies (`cartCurrencies`).
+     */
+    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 +753,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 +875,200 @@ 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 or one of its extra cart currencies (`enabledCurrencies` lists them).
+ */
+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), `quote_unavailable` (could not be
+ * quoted now; kept for the next hand-off) or `shipping_currency_unsupported`
+ * (on a cart in an extra currency, its rate is a non-zero amount in another
+ * currency; kept, and the buyer must choose another method).
+ */
+type CartShippingChange = {
+    methodId: string;
+    previousAmount: number;
+    amount: number | null;
+    reason?: 'method_unavailable' | 'quote_unavailable' | 'shipping_currency_unsupported';
+};
+/** `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);
+}
+/**
+ * `422 discount_currency_unsupported`: a fixed-amount discount can't be used
+ * on a resolved cart in an extra currency. Nothing is applied; a percentage
+ * discount works.
+ */
+declare class DiscountCurrencyUnsupportedError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/**
+ * `422 shipping_currency_unsupported`: on a resolved cart in an extra
+ * currency, a non-zero shipping rate in another currency. Nothing new is
+ * selected; choose a zero-rate method. At the checkout hand-off, `shipping`
+ * is the kept selection.
+ */
+declare class ShippingCurrencyUnsupportedError extends ThrottleApiError {
+    readonly details?: {
+        shipping?: CartShippingChange;
+    };
+    readonly shipping: CartShippingChange | null;
+    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 +1081,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, DiscountCurrencyUnsupportedError, 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, ShippingCurrencyUnsupportedError, 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,147 @@ 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 DiscountCurrencyUnsupportedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("discount_currency_unsupported", 422, args));
+    this.name = "DiscountCurrencyUnsupportedError";
+  }
+};
+var ShippingCurrencyUnsupportedError = class extends ThrottleApiError {
+  shipping;
+  constructor(args) {
+    super(coded("shipping_currency_unsupported", 422, args));
+    this.name = "ShippingCurrencyUnsupportedError";
+    const d = args.details;
+    this.shipping = d?.shipping && typeof d.shipping === "object" ? d.shipping : null;
+  }
+};
+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,
+  discount_currency_unsupported: DiscountCurrencyUnsupportedError,
+  shipping_currency_unsupported: ShippingCurrencyUnsupportedError
+};
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
     return new CartNotOpenError({
@@ -59,6 +200,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 +266,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 +449,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 +488,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 +586,26 @@ var CartSessionClient = class _CartSessionClient {
   }
 };
 export {
+  AmountTooLargeError,
+  CartChangedError,
   CartClient,
   CartNotFoundError,
   CartNotOpenError,
+  CartPricesChangedError,
   CartSessionClient,
   CartTimeoutError,
+  CurrencyNotEnabledError,
+  DiscountCurrencyUnsupportedError,
+  LineLimitReachedError,
+  LineNotPurchasableError,
+  LineResolverNotAvailableError,
+  LineResolverUnavailableError,
+  PriceLockedError,
+  QuantityUnavailableError,
+  ResolvedLinesRequiredError,
+  ShippingCurrencyUnsupportedError,
+  ShippingMethodUnavailableError,
+  ShippingQuoteUnavailableError,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError2 as ThrottleError,

package/package.json

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