@usethrottle/cart 3.7.0 → 3.9.0

package/README.md

@@ -88,15 +88,58 @@ await cart.addItem({ name: 'Premium Widget', unitPrice: 2999, quantity: 2 });
 await cart.applyDiscount('SAVE10');
 await cart.selectShipping({ methodId: 'fedex_ground', displayName: 'FedEx Ground', rateAmount: 599 });
 
+// Set buyer-editable fields. `customerEmail` is what makes a guest cart
+// visible to abandoned-cart recovery. `null` clears a field.
+await cart.update({ customerEmail: 'buyer@example.com', notes: 'Leave at the door' });
+
 // Hand off to hosted/embedded checkout and redirect the buyer.
 const { checkoutUrl } = await cart.checkout({
   returnUrl: 'https://shop.example.com/thanks',
   cancelUrl: 'https://shop.example.com/cart',
+  // Leave the session `active` instead of `converted`, so a buyer who backs
+  // out of checkout returns to a live cart instead of an expired one.
+  keepOpen: true,
 });
 ```
 
+`create()` and `get()` also return a `branding` block (`CartBranding`:
+`logoUrl`, `primaryColor`, `merchantName`, each nullable) so a storefront
+rendering its own cart UI doesn't need a separate call to brand it.
+
+To bind to an existing session without a publishable token — e.g. Throttle's
+own hosted cart page, or a storefront restoring a saved session id — use
+`CartSessionClient.forSession()` instead of `new CartSessionClient()`:
+
+```ts
+const cart = CartSessionClient.forSession(savedCartSessionId);
+await cart.addItem({ name: 'Premium Widget', unitPrice: 2999, quantity: 1 });
+```
+
 The opaque `cart_…` session id is scoped to exactly one cart. See the
-[cart sessions guide](https://docs.usethrottle.dev/developers/cart-sessions).
+[cart sessions guide](https://usethrottle.dev/docs/developers/cart-sessions).
+
+### Hosted cart page
+
+Skip building cart UI entirely and send the buyer to Throttle's own hosted
+cart page with `hostedCartUrl()`:
+
+```ts
+const session = await cart.create({
+  metadata: {
+    returnUrl: 'https://shop.example.com/thanks',
+    cancelUrl: 'https://shop.example.com/cart',
+    storefrontUrl: 'https://shop.example.com',
+  },
+});
+
+location.href = cart.hostedCartUrl(); // https://checkout.usethrottle.dev/cart/cart_...
+```
+
+`returnUrl`, `cancelUrl`, and `storefrontUrl` in `metadata` are all optional.
+Omitting `storefrontUrl` just removes the hosted page's "Continue shopping"
+button — checkout still works. Omitting `returnUrl` or `cancelUrl` falls back
+to Throttle's own `/complete` page and this same hosted cart page,
+respectively.
 
 ## Net-N invoice terms
 
@@ -179,7 +222,7 @@ await client.shippingTax.pushExternalSnapshot({
 
 ## Subscriptions
 
-Pass `type: 'subscription'` and a `recurring` block on the line item:
+Mark a line item with `type: 'subscription'`:
 
 ```ts
 await client.items.add(cart.id, {
@@ -187,12 +230,15 @@ await client.items.add(cart.id, {
   name: 'Pro Plan',
   unitPrice: 1900,
   quantity: 1,
-  recurring: { interval: 'month', count: null }, // count: null = until cancelled
 });
 ```
 
-Then call `client.carts.checkout` as normal. Set `count` to a number to cap
-the billing cycles.
+Then call `client.carts.checkout` as normal.
+
+The billing schedule is **not** settable through this endpoint. The add-item
+body is strict and has no `recurring` field, so sending one is rejected with
+`Unsupported field(s): recurring` — the recurring plan is attached by the
+subscription engine, not by the cart API.
 
 ## Events
 

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   CartNotFoundError: () => CartNotFoundError,
   CartNotOpenError: () => CartNotOpenError,
   CartSessionClient: () => CartSessionClient,
+  CartTimeoutError: () => CartTimeoutError,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
   ThrottleApiError: () => ThrottleApiError,
   ThrottleError: () => import_errors2.ThrottleError,
@@ -53,6 +54,17 @@ var CartNotFoundError = class extends ThrottleApiError {
     this.name = "CartNotFoundError";
   }
 };
+var CartTimeoutError = class extends import_errors.ThrottleError {
+  constructor(args) {
+    super({
+      code: "request_timeout",
+      statusCode: 408,
+      message: `Request timed out after ${args.timeoutMs}ms`,
+      details: { timeoutMs: args.timeoutMs, method: args.method, path: args.path }
+    });
+    this.name = "CartTimeoutError";
+  }
+};
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
     return new CartNotOpenError({ message: args.message, statusCode: args.statusCode, details: args.details });
@@ -76,7 +88,7 @@ var CartClient = class {
     if (!opts.apiKey) throw new Error("CartClient: apiKey is required");
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
-    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 3e4;
   }
   async request(method, path, body) {
@@ -171,13 +183,13 @@ var StorefrontQuoteClient = class {
   origin;
   constructor(opts) {
     if (!opts.applicationId) throw new Error("StorefrontQuoteClient: applicationId is required");
-    if (!opts.quoteToken?.startsWith("pk_")) {
-      throw new Error("StorefrontQuoteClient: quoteToken must be a publishable pk_ token");
+    if (!/^(pk|qt)_/.test(opts.quoteToken ?? "")) {
+      throw new Error("StorefrontQuoteClient: quoteToken must be a publishable qt_ (or legacy pk_) token");
     }
     this.applicationId = opts.applicationId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
-    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 15e3;
     this.origin = opts.origin;
   }
@@ -214,7 +226,7 @@ var StorefrontQuoteClient = class {
 };
 
 // src/cart-session.ts
-var CartSessionClient = class {
+var CartSessionClient = class _CartSessionClient {
   applicationId;
   environmentId;
   quoteToken;
@@ -223,17 +235,18 @@ var CartSessionClient = class {
   timeoutMs;
   origin;
   sessionId = null;
+  isForSessionClient = false;
   constructor(opts) {
     if (!opts.applicationId) throw new Error("CartSessionClient: applicationId is required");
     if (!opts.environmentId) throw new Error("CartSessionClient: environmentId is required");
-    if (!opts.quoteToken?.startsWith("pk_")) {
-      throw new Error("CartSessionClient: quoteToken must be a publishable pk_ token");
+    if (!/^(pk|qt)_/.test(opts.quoteToken ?? "")) {
+      throw new Error("CartSessionClient: quoteToken must be a publishable qt_ (or legacy pk_) token");
     }
     this.applicationId = opts.applicationId;
     this.environmentId = opts.environmentId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
-    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 15e3;
     this.origin = opts.origin;
   }
@@ -248,6 +261,11 @@ var CartSessionClient = class {
   }
   /** Create a new cart session and bind this client to it. */
   async create(input = {}) {
+    if (this.isForSessionClient) {
+      throw new Error(
+        "CartSessionClient: this client was created with forSession() and cannot call create(). Construct a CartSessionClient with a real pk_ publishable token instead."
+      );
+    }
     const data = await this.request("POST", "/api/v1/cart-sessions", {
       applicationId: this.applicationId,
       environmentId: this.environmentId,
@@ -255,17 +273,38 @@ var CartSessionClient = class {
       ...input
     });
     this.sessionId = data.cartSessionId;
-    return data;
+    return {
+      ...data,
+      branding: data.branding ?? { logoUrl: null, primaryColor: null, merchantName: null }
+    };
   }
   /** Read the current session + cart snapshot. */
-  get() {
-    return this.request("GET", this.basePath());
+  async get() {
+    const data = await this.request("GET", this.basePath());
+    return {
+      ...data,
+      branding: data.branding ?? { logoUrl: null, primaryColor: null, merchantName: null }
+    };
+  }
+  /**
+   * Unit count + total for a cart badge, without pulling the whole cart.
+   *
+   * Works on a client built with {@link CartSessionClient.forSession} — a
+   * storefront that restored a `cart_…` id from `localStorage` and holds no
+   * publishable token in the browser.
+   */
+  async summary() {
+    return this.request("GET", `${this.basePath()}/summary`);
   }
   async addItem(input) {
     return (await this.request("POST", `${this.basePath()}/items`, input)).cart;
   }
   async updateItem(itemId, input) {
-    return (await this.request("PATCH", `${this.basePath()}/items/${encodeURIComponent(itemId)}`, input)).cart;
+    return (await this.request(
+      "PATCH",
+      `${this.basePath()}/items/${encodeURIComponent(itemId)}`,
+      input
+    )).cart;
   }
   async removeItem(itemId) {
     return (await this.request("DELETE", `${this.basePath()}/items/${encodeURIComponent(itemId)}`)).cart;
@@ -282,6 +321,38 @@ var CartSessionClient = class {
   async removeDiscount() {
     return (await this.request("DELETE", `${this.basePath()}/discount`)).cart;
   }
+  /** Set buyer-editable cart fields. Pass `null` to clear one. */
+  async update(input) {
+    return (await this.request("PATCH", this.basePath(), input)).cart;
+  }
+  /**
+   * Bind to an existing session without a publishable token.
+   *
+   * `create()` needs a `pk_` token; every other route is authorized by the
+   * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
+   * hosted cart page, or a storefront restoring from localStorage — would
+   * otherwise have to invent a token to satisfy the constructor.
+   */
+  static forSession(cartSessionId, opts = {}) {
+    const client = new _CartSessionClient({
+      applicationId: "session",
+      environmentId: "session",
+      quoteToken: "pk_session",
+      ...opts
+    });
+    client.isForSessionClient = true;
+    return client.resume(cartSessionId);
+  }
+  /**
+   * The Throttle-hosted cart page for this session. Send a buyer here to let
+   * Throttle run the cart UI instead of building one.
+   */
+  hostedCartUrl(baseUrl = "https://checkout.usethrottle.dev") {
+    if (!this.sessionId) {
+      throw new Error("CartSessionClient: no active session \u2014 call create() or resume(id) first");
+    }
+    return `${baseUrl.replace(/\/+$/, "")}/cart/${encodeURIComponent(this.sessionId)}`;
+  }
   /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
   checkout(input) {
     return this.request("POST", `${this.basePath()}/checkout-session`, input);
@@ -294,7 +365,11 @@ var CartSessionClient = class {
   }
   async request(method, path, body) {
     const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ctrl.abort();
+    }, this.timeoutMs);
     try {
       const headers = { "content-type": "application/json" };
       if (this.origin) headers.origin = this.origin;
@@ -314,6 +389,9 @@ var CartSessionClient = class {
         });
       }
       return json.data;
+    } catch (err) {
+      if (timedOut) throw new CartTimeoutError({ timeoutMs: this.timeoutMs, method, path });
+      throw err;
     } finally {
       clearTimeout(timer);
     }
@@ -325,6 +403,7 @@ var CartSessionClient = class {
   CartNotFoundError,
   CartNotOpenError,
   CartSessionClient,
+  CartTimeoutError,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError,

package/dist/index.d.cts

@@ -11,6 +11,8 @@ export { ThrottleError, isThrottleError } from '@usethrottle/errors';
 interface CartAddress {
     firstName?: string;
     lastName?: string;
+    /** Business name. Optional — B2B addresses use it, B2C addresses omit it. */
+    company?: string;
     addressLine1: string;
     addressLine2?: string;
     city: string;
@@ -22,8 +24,14 @@ interface CartAddress {
     email?: string;
 }
 interface Cart {
+    /**
+     * `getById`/`create`/etc. (the `carts` resource) return this shape. See
+     * {@link CartSessionCart} for the browser-facing `CartSessionClient` shape,
+     * which omits `workspaceId` and adds `cartId`.
+     */
     id: string;
     workspaceId: string;
+    cartId?: string;
     applicationId: string;
     customerId: string | null;
     /** Lightweight captured email (no full customer record), or null. */
@@ -39,6 +47,7 @@ interface Cart {
     billingAddress: CartAddress | null;
     shippingAddress: CartAddress | null;
     notes: string | null;
+    metadata: Record<string, unknown>;
     expiresAt: string | null;
     externalRef?: {
         connectionId: string;
@@ -52,6 +61,24 @@ interface Cart {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * The cart as the session (browser, opaque-token) surface returns it —
+ * `CartSessionClient`'s methods. There is no `workspaceId` on this surface
+ * (the browser never needs, and shouldn't see, the internal workspace id);
+ * `cartId` — the same value as `id` — is always present, kept for backward
+ * compatibility with `@usethrottle/cart`'s original (order-snapshot-shaped)
+ * cart-session response.
+ */
+interface CartSessionCart extends Omit<Cart, 'workspaceId'> {
+    cartId: string;
+    /**
+     * Sum of the line-item quantities — 1 stand + 2 notebooks + 1 keyboard is
+     * `4`, not `3`. Present only on this surface; the merchant `carts` resource
+     * does not return it. Named for what it counts because `itemCount` in the
+     * `cart.abandoned` webhook payload means the number of distinct lines.
+     */
+    unitCount: number;
+}
 interface LineItem {
     id: string;
     cartId: string;
@@ -98,6 +125,12 @@ interface TaxLine {
     jurisdictionCode: string;
     jurisdictionName: string | null;
     taxType: 'sales' | 'vat' | 'gst' | 'pst' | 'hst' | 'service' | 'excise' | 'other';
+    /** The VAT code the engine returned, verbatim — AvaTax's `vatCode`. */
+    vatCode?: string | null;
+    /** The engine's own name for the tax ('Standard'); `taxType` is our slug for it. */
+    taxName?: string | null;
+    /** Engine rate classification: 'S' standard, 'R' reduced, 'Z' zero. */
+    rateTypeCode?: string | null;
     rate: number;
     amount: number;
     currency: string;
@@ -307,6 +340,20 @@ interface ShippingTaxCalculationResponse {
         taxTotal: number;
         total: number;
     };
+    /**
+     * Verbatim messaging the tax engine returned about this transaction. In
+     * several EU member states the engine's own wording is what makes the
+     * invoice compliant, so it is carried through rather than paraphrased.
+     */
+    providerMessages?: Array<{
+        summary: string;
+        details?: string;
+        /** The engine's identifier for the citation, e.g. 'Article138.1'. */
+        citationCode?: string;
+        refersTo?: string;
+        severity?: string;
+        source?: string;
+    }>;
     prompts: Array<{
         code: 'missing_info';
         field: string;
@@ -441,17 +488,63 @@ interface CreateCartSessionInput {
     netN?: number;
     metadata?: Record<string, unknown>;
 }
+interface CartBranding {
+    logoUrl: string | null;
+    primaryColor: string | null;
+    merchantName: string | null;
+}
+/** Buyer-editable cart fields. `null` clears a value. */
+interface UpdateCartSessionInput {
+    customerEmail?: string | null;
+    notes?: string | null;
+}
 interface CartSession {
     cartSessionId: string;
     status: string;
     expiresAt: string;
-    cart: Cart;
+    branding: CartBranding;
+    /**
+     * Whatever the storefront passed to `create()`. Write-once — unlike the copy
+     * on `cart.metadata`, which the merchant API can change — so this is the one
+     * to read the buyer's return/cancel/storefront URLs from.
+     */
+    metadata: Record<string, unknown>;
+    cart: CartSessionCart;
+}
+/**
+ * The badge-sized read: what a storefront header needs to draw a cart count,
+ * and nothing more. No line items, no addresses, no buyer email or notes.
+ */
+interface CartSessionSummary {
+    cartSessionId: string;
+    /**
+     * `active` while the cart can still be edited. `expired` (past its TTL) or
+     * `converted` (handed off to checkout) once the session is finished — those
+     * come back as a normal 200 with a zeroed summary, not an error, so a badge
+     * can render a zero without a try/catch.
+     */
+    status: 'active' | 'expired' | 'converted';
+    /**
+     * Sum of the line-item quantities — 1 stand + 2 notebooks + 1 keyboard is
+     * `4`, not `3`. Named for what it counts because `itemCount` elsewhere in
+     * Throttle (the `cart.abandoned` payload) means the number of distinct lines.
+     */
+    unitCount: number;
+    /** Cart total in minor units, or `0` on a finished session. */
+    total: number;
+    /** `null` on a finished session — there is no live cart to price. */
+    currency: string | null;
 }
 interface CheckoutHandoffInput {
     returnUrl: string;
     cancelUrl: string;
     customerEmail?: string;
     allowedMethods?: string[];
+    /**
+     * Leave the cart session open after handing off, so a buyer who backs out of
+     * checkout returns to a live cart. Throttle's own hosted cart page sets this.
+     */
+    keepOpen?: boolean;
 }
 interface CheckoutHandoff {
     cartSessionId: string;
@@ -468,6 +561,7 @@ declare class CartSessionClient {
     private readonly timeoutMs;
     private readonly origin?;
     private sessionId;
+    private isForSessionClient;
     constructor(opts: CartSessionClientOptions);
     /** The current bound session id (after `create()`/`resume()`), or null. */
     get cartSessionId(): string | null;
@@ -477,13 +571,42 @@ declare class CartSessionClient {
     create(input?: CreateCartSessionInput): Promise<CartSession>;
     /** Read the current session + cart snapshot. */
     get(): Promise<CartSession>;
-    addItem(input: AddLineItemInput): Promise<Cart>;
-    updateItem(itemId: string, input: UpdateLineItemInput): Promise<Cart>;
-    removeItem(itemId: string): Promise<Cart>;
-    selectShipping(input: SelectShippingInput): Promise<Cart>;
-    clearShipping(): Promise<Cart>;
-    applyDiscount(code: string): Promise<Cart>;
-    removeDiscount(): Promise<Cart>;
+    /**
+     * Unit count + total for a cart badge, without pulling the whole cart.
+     *
+     * Works on a client built with {@link CartSessionClient.forSession} — a
+     * storefront that restored a `cart_…` id from `localStorage` and holds no
+     * publishable token in the browser.
+     */
+    summary(): Promise<CartSessionSummary>;
+    addItem(input: AddLineItemInput): Promise<CartSessionCart>;
+    updateItem(itemId: string, input: UpdateLineItemInput): Promise<CartSessionCart>;
+    removeItem(itemId: string): Promise<CartSessionCart>;
+    selectShipping(input: SelectShippingInput): Promise<CartSessionCart>;
+    clearShipping(): Promise<CartSessionCart>;
+    applyDiscount(code: string): Promise<CartSessionCart>;
+    removeDiscount(): Promise<CartSessionCart>;
+    /** Set buyer-editable cart fields. Pass `null` to clear one. */
+    update(input: UpdateCartSessionInput): Promise<CartSessionCart>;
+    /**
+     * Bind to an existing session without a publishable token.
+     *
+     * `create()` needs a `pk_` token; every other route is authorized by the
+     * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
+     * hosted cart page, or a storefront restoring from localStorage — would
+     * otherwise have to invent a token to satisfy the constructor.
+     */
+    static forSession(cartSessionId: string, opts?: {
+        baseUrl?: string;
+        fetch?: typeof globalThis.fetch;
+        timeoutMs?: number;
+        origin?: string;
+    }): CartSessionClient;
+    /**
+     * The Throttle-hosted cart page for this session. Send a buyer here to let
+     * Throttle run the cart UI instead of building one.
+     */
+    hostedCartUrl(baseUrl?: string): string;
     /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
     checkout(input: CheckoutHandoffInput): Promise<CheckoutHandoff>;
     private basePath;
@@ -534,6 +657,25 @@ declare class CartNotFoundError extends ThrottleApiError {
         details?: Record<string, unknown>;
     });
 }
+/**
+ * Thrown when a request is aborted by the client's own timeout — the server
+ * never answered within `timeoutMs`.
+ *
+ * It exists because the alternative is worse than useless: aborting an
+ * AbortController without a reason produces a DOMException whose message is
+ * "signal is aborted without reason", and that string was reaching shoppers as
+ * a page-level alert on the hosted cart.
+ *
+ * `statusCode` is 408 (Request Timeout) so the error keeps the same shape as
+ * every other Cart SDK error, even though no server sent it.
+ */
+declare class CartTimeoutError extends ThrottleError {
+    constructor(args: {
+        timeoutMs: number;
+        method?: string;
+        path?: string;
+    });
+}
 /**
  * Map a raw API error envelope to the most specific Cart SDK error class.
  * Falls back to {@link ThrottleApiError} for everything unrecognised.
@@ -545,4 +687,4 @@ declare function cartErrorFromResponse(args: {
     details?: Record<string, unknown>;
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, CartSessionClient, type CartSessionClientOptions, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LineItem, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, StorefrontQuoteClient, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateLineItemInput, cartErrorFromResponse };
+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 LineItem, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, StorefrontQuoteClient, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export { ThrottleError, isThrottleError } from '@usethrottle/errors';
 interface CartAddress {
     firstName?: string;
     lastName?: string;
+    /** Business name. Optional — B2B addresses use it, B2C addresses omit it. */
+    company?: string;
     addressLine1: string;
     addressLine2?: string;
     city: string;
@@ -22,8 +24,14 @@ interface CartAddress {
     email?: string;
 }
 interface Cart {
+    /**
+     * `getById`/`create`/etc. (the `carts` resource) return this shape. See
+     * {@link CartSessionCart} for the browser-facing `CartSessionClient` shape,
+     * which omits `workspaceId` and adds `cartId`.
+     */
     id: string;
     workspaceId: string;
+    cartId?: string;
     applicationId: string;
     customerId: string | null;
     /** Lightweight captured email (no full customer record), or null. */
@@ -39,6 +47,7 @@ interface Cart {
     billingAddress: CartAddress | null;
     shippingAddress: CartAddress | null;
     notes: string | null;
+    metadata: Record<string, unknown>;
     expiresAt: string | null;
     externalRef?: {
         connectionId: string;
@@ -52,6 +61,24 @@ interface Cart {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * The cart as the session (browser, opaque-token) surface returns it —
+ * `CartSessionClient`'s methods. There is no `workspaceId` on this surface
+ * (the browser never needs, and shouldn't see, the internal workspace id);
+ * `cartId` — the same value as `id` — is always present, kept for backward
+ * compatibility with `@usethrottle/cart`'s original (order-snapshot-shaped)
+ * cart-session response.
+ */
+interface CartSessionCart extends Omit<Cart, 'workspaceId'> {
+    cartId: string;
+    /**
+     * Sum of the line-item quantities — 1 stand + 2 notebooks + 1 keyboard is
+     * `4`, not `3`. Present only on this surface; the merchant `carts` resource
+     * does not return it. Named for what it counts because `itemCount` in the
+     * `cart.abandoned` webhook payload means the number of distinct lines.
+     */
+    unitCount: number;
+}
 interface LineItem {
     id: string;
     cartId: string;
@@ -98,6 +125,12 @@ interface TaxLine {
     jurisdictionCode: string;
     jurisdictionName: string | null;
     taxType: 'sales' | 'vat' | 'gst' | 'pst' | 'hst' | 'service' | 'excise' | 'other';
+    /** The VAT code the engine returned, verbatim — AvaTax's `vatCode`. */
+    vatCode?: string | null;
+    /** The engine's own name for the tax ('Standard'); `taxType` is our slug for it. */
+    taxName?: string | null;
+    /** Engine rate classification: 'S' standard, 'R' reduced, 'Z' zero. */
+    rateTypeCode?: string | null;
     rate: number;
     amount: number;
     currency: string;
@@ -307,6 +340,20 @@ interface ShippingTaxCalculationResponse {
         taxTotal: number;
         total: number;
     };
+    /**
+     * Verbatim messaging the tax engine returned about this transaction. In
+     * several EU member states the engine's own wording is what makes the
+     * invoice compliant, so it is carried through rather than paraphrased.
+     */
+    providerMessages?: Array<{
+        summary: string;
+        details?: string;
+        /** The engine's identifier for the citation, e.g. 'Article138.1'. */
+        citationCode?: string;
+        refersTo?: string;
+        severity?: string;
+        source?: string;
+    }>;
     prompts: Array<{
         code: 'missing_info';
         field: string;
@@ -441,17 +488,63 @@ interface CreateCartSessionInput {
     netN?: number;
     metadata?: Record<string, unknown>;
 }
+interface CartBranding {
+    logoUrl: string | null;
+    primaryColor: string | null;
+    merchantName: string | null;
+}
+/** Buyer-editable cart fields. `null` clears a value. */
+interface UpdateCartSessionInput {
+    customerEmail?: string | null;
+    notes?: string | null;
+}
 interface CartSession {
     cartSessionId: string;
     status: string;
     expiresAt: string;
-    cart: Cart;
+    branding: CartBranding;
+    /**
+     * Whatever the storefront passed to `create()`. Write-once — unlike the copy
+     * on `cart.metadata`, which the merchant API can change — so this is the one
+     * to read the buyer's return/cancel/storefront URLs from.
+     */
+    metadata: Record<string, unknown>;
+    cart: CartSessionCart;
+}
+/**
+ * The badge-sized read: what a storefront header needs to draw a cart count,
+ * and nothing more. No line items, no addresses, no buyer email or notes.
+ */
+interface CartSessionSummary {
+    cartSessionId: string;
+    /**
+     * `active` while the cart can still be edited. `expired` (past its TTL) or
+     * `converted` (handed off to checkout) once the session is finished — those
+     * come back as a normal 200 with a zeroed summary, not an error, so a badge
+     * can render a zero without a try/catch.
+     */
+    status: 'active' | 'expired' | 'converted';
+    /**
+     * Sum of the line-item quantities — 1 stand + 2 notebooks + 1 keyboard is
+     * `4`, not `3`. Named for what it counts because `itemCount` elsewhere in
+     * Throttle (the `cart.abandoned` payload) means the number of distinct lines.
+     */
+    unitCount: number;
+    /** Cart total in minor units, or `0` on a finished session. */
+    total: number;
+    /** `null` on a finished session — there is no live cart to price. */
+    currency: string | null;
 }
 interface CheckoutHandoffInput {
     returnUrl: string;
     cancelUrl: string;
     customerEmail?: string;
     allowedMethods?: string[];
+    /**
+     * Leave the cart session open after handing off, so a buyer who backs out of
+     * checkout returns to a live cart. Throttle's own hosted cart page sets this.
+     */
+    keepOpen?: boolean;
 }
 interface CheckoutHandoff {
     cartSessionId: string;
@@ -468,6 +561,7 @@ declare class CartSessionClient {
     private readonly timeoutMs;
     private readonly origin?;
     private sessionId;
+    private isForSessionClient;
     constructor(opts: CartSessionClientOptions);
     /** The current bound session id (after `create()`/`resume()`), or null. */
     get cartSessionId(): string | null;
@@ -477,13 +571,42 @@ declare class CartSessionClient {
     create(input?: CreateCartSessionInput): Promise<CartSession>;
     /** Read the current session + cart snapshot. */
     get(): Promise<CartSession>;
-    addItem(input: AddLineItemInput): Promise<Cart>;
-    updateItem(itemId: string, input: UpdateLineItemInput): Promise<Cart>;
-    removeItem(itemId: string): Promise<Cart>;
-    selectShipping(input: SelectShippingInput): Promise<Cart>;
-    clearShipping(): Promise<Cart>;
-    applyDiscount(code: string): Promise<Cart>;
-    removeDiscount(): Promise<Cart>;
+    /**
+     * Unit count + total for a cart badge, without pulling the whole cart.
+     *
+     * Works on a client built with {@link CartSessionClient.forSession} — a
+     * storefront that restored a `cart_…` id from `localStorage` and holds no
+     * publishable token in the browser.
+     */
+    summary(): Promise<CartSessionSummary>;
+    addItem(input: AddLineItemInput): Promise<CartSessionCart>;
+    updateItem(itemId: string, input: UpdateLineItemInput): Promise<CartSessionCart>;
+    removeItem(itemId: string): Promise<CartSessionCart>;
+    selectShipping(input: SelectShippingInput): Promise<CartSessionCart>;
+    clearShipping(): Promise<CartSessionCart>;
+    applyDiscount(code: string): Promise<CartSessionCart>;
+    removeDiscount(): Promise<CartSessionCart>;
+    /** Set buyer-editable cart fields. Pass `null` to clear one. */
+    update(input: UpdateCartSessionInput): Promise<CartSessionCart>;
+    /**
+     * Bind to an existing session without a publishable token.
+     *
+     * `create()` needs a `pk_` token; every other route is authorized by the
+     * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
+     * hosted cart page, or a storefront restoring from localStorage — would
+     * otherwise have to invent a token to satisfy the constructor.
+     */
+    static forSession(cartSessionId: string, opts?: {
+        baseUrl?: string;
+        fetch?: typeof globalThis.fetch;
+        timeoutMs?: number;
+        origin?: string;
+    }): CartSessionClient;
+    /**
+     * The Throttle-hosted cart page for this session. Send a buyer here to let
+     * Throttle run the cart UI instead of building one.
+     */
+    hostedCartUrl(baseUrl?: string): string;
     /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
     checkout(input: CheckoutHandoffInput): Promise<CheckoutHandoff>;
     private basePath;
@@ -534,6 +657,25 @@ declare class CartNotFoundError extends ThrottleApiError {
         details?: Record<string, unknown>;
     });
 }
+/**
+ * Thrown when a request is aborted by the client's own timeout — the server
+ * never answered within `timeoutMs`.
+ *
+ * It exists because the alternative is worse than useless: aborting an
+ * AbortController without a reason produces a DOMException whose message is
+ * "signal is aborted without reason", and that string was reaching shoppers as
+ * a page-level alert on the hosted cart.
+ *
+ * `statusCode` is 408 (Request Timeout) so the error keeps the same shape as
+ * every other Cart SDK error, even though no server sent it.
+ */
+declare class CartTimeoutError extends ThrottleError {
+    constructor(args: {
+        timeoutMs: number;
+        method?: string;
+        path?: string;
+    });
+}
 /**
  * Map a raw API error envelope to the most specific Cart SDK error class.
  * Falls back to {@link ThrottleApiError} for everything unrecognised.
@@ -545,4 +687,4 @@ declare function cartErrorFromResponse(args: {
     details?: Record<string, unknown>;
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, CartSessionClient, type CartSessionClientOptions, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LineItem, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, StorefrontQuoteClient, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateLineItemInput, cartErrorFromResponse };
+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 LineItem, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, StorefrontQuoteClient, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.js

@@ -19,6 +19,17 @@ var CartNotFoundError = class extends ThrottleApiError {
     this.name = "CartNotFoundError";
   }
 };
+var CartTimeoutError = class extends ThrottleError {
+  constructor(args) {
+    super({
+      code: "request_timeout",
+      statusCode: 408,
+      message: `Request timed out after ${args.timeoutMs}ms`,
+      details: { timeoutMs: args.timeoutMs, method: args.method, path: args.path }
+    });
+    this.name = "CartTimeoutError";
+  }
+};
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
     return new CartNotOpenError({ message: args.message, statusCode: args.statusCode, details: args.details });
@@ -42,7 +53,7 @@ var CartClient = class {
     if (!opts.apiKey) throw new Error("CartClient: apiKey is required");
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
-    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 3e4;
   }
   async request(method, path, body) {
@@ -137,13 +148,13 @@ var StorefrontQuoteClient = class {
   origin;
   constructor(opts) {
     if (!opts.applicationId) throw new Error("StorefrontQuoteClient: applicationId is required");
-    if (!opts.quoteToken?.startsWith("pk_")) {
-      throw new Error("StorefrontQuoteClient: quoteToken must be a publishable pk_ token");
+    if (!/^(pk|qt)_/.test(opts.quoteToken ?? "")) {
+      throw new Error("StorefrontQuoteClient: quoteToken must be a publishable qt_ (or legacy pk_) token");
     }
     this.applicationId = opts.applicationId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
-    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 15e3;
     this.origin = opts.origin;
   }
@@ -180,7 +191,7 @@ var StorefrontQuoteClient = class {
 };
 
 // src/cart-session.ts
-var CartSessionClient = class {
+var CartSessionClient = class _CartSessionClient {
   applicationId;
   environmentId;
   quoteToken;
@@ -189,17 +200,18 @@ var CartSessionClient = class {
   timeoutMs;
   origin;
   sessionId = null;
+  isForSessionClient = false;
   constructor(opts) {
     if (!opts.applicationId) throw new Error("CartSessionClient: applicationId is required");
     if (!opts.environmentId) throw new Error("CartSessionClient: environmentId is required");
-    if (!opts.quoteToken?.startsWith("pk_")) {
-      throw new Error("CartSessionClient: quoteToken must be a publishable pk_ token");
+    if (!/^(pk|qt)_/.test(opts.quoteToken ?? "")) {
+      throw new Error("CartSessionClient: quoteToken must be a publishable qt_ (or legacy pk_) token");
     }
     this.applicationId = opts.applicationId;
     this.environmentId = opts.environmentId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
-    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 15e3;
     this.origin = opts.origin;
   }
@@ -214,6 +226,11 @@ var CartSessionClient = class {
   }
   /** Create a new cart session and bind this client to it. */
   async create(input = {}) {
+    if (this.isForSessionClient) {
+      throw new Error(
+        "CartSessionClient: this client was created with forSession() and cannot call create(). Construct a CartSessionClient with a real pk_ publishable token instead."
+      );
+    }
     const data = await this.request("POST", "/api/v1/cart-sessions", {
       applicationId: this.applicationId,
       environmentId: this.environmentId,
@@ -221,17 +238,38 @@ var CartSessionClient = class {
       ...input
     });
     this.sessionId = data.cartSessionId;
-    return data;
+    return {
+      ...data,
+      branding: data.branding ?? { logoUrl: null, primaryColor: null, merchantName: null }
+    };
   }
   /** Read the current session + cart snapshot. */
-  get() {
-    return this.request("GET", this.basePath());
+  async get() {
+    const data = await this.request("GET", this.basePath());
+    return {
+      ...data,
+      branding: data.branding ?? { logoUrl: null, primaryColor: null, merchantName: null }
+    };
+  }
+  /**
+   * Unit count + total for a cart badge, without pulling the whole cart.
+   *
+   * Works on a client built with {@link CartSessionClient.forSession} — a
+   * storefront that restored a `cart_…` id from `localStorage` and holds no
+   * publishable token in the browser.
+   */
+  async summary() {
+    return this.request("GET", `${this.basePath()}/summary`);
   }
   async addItem(input) {
     return (await this.request("POST", `${this.basePath()}/items`, input)).cart;
   }
   async updateItem(itemId, input) {
-    return (await this.request("PATCH", `${this.basePath()}/items/${encodeURIComponent(itemId)}`, input)).cart;
+    return (await this.request(
+      "PATCH",
+      `${this.basePath()}/items/${encodeURIComponent(itemId)}`,
+      input
+    )).cart;
   }
   async removeItem(itemId) {
     return (await this.request("DELETE", `${this.basePath()}/items/${encodeURIComponent(itemId)}`)).cart;
@@ -248,6 +286,38 @@ var CartSessionClient = class {
   async removeDiscount() {
     return (await this.request("DELETE", `${this.basePath()}/discount`)).cart;
   }
+  /** Set buyer-editable cart fields. Pass `null` to clear one. */
+  async update(input) {
+    return (await this.request("PATCH", this.basePath(), input)).cart;
+  }
+  /**
+   * Bind to an existing session without a publishable token.
+   *
+   * `create()` needs a `pk_` token; every other route is authorized by the
+   * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
+   * hosted cart page, or a storefront restoring from localStorage — would
+   * otherwise have to invent a token to satisfy the constructor.
+   */
+  static forSession(cartSessionId, opts = {}) {
+    const client = new _CartSessionClient({
+      applicationId: "session",
+      environmentId: "session",
+      quoteToken: "pk_session",
+      ...opts
+    });
+    client.isForSessionClient = true;
+    return client.resume(cartSessionId);
+  }
+  /**
+   * The Throttle-hosted cart page for this session. Send a buyer here to let
+   * Throttle run the cart UI instead of building one.
+   */
+  hostedCartUrl(baseUrl = "https://checkout.usethrottle.dev") {
+    if (!this.sessionId) {
+      throw new Error("CartSessionClient: no active session \u2014 call create() or resume(id) first");
+    }
+    return `${baseUrl.replace(/\/+$/, "")}/cart/${encodeURIComponent(this.sessionId)}`;
+  }
   /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
   checkout(input) {
     return this.request("POST", `${this.basePath()}/checkout-session`, input);
@@ -260,7 +330,11 @@ var CartSessionClient = class {
   }
   async request(method, path, body) {
     const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ctrl.abort();
+    }, this.timeoutMs);
     try {
       const headers = { "content-type": "application/json" };
       if (this.origin) headers.origin = this.origin;
@@ -280,6 +354,9 @@ var CartSessionClient = class {
         });
       }
       return json.data;
+    } catch (err) {
+      if (timedOut) throw new CartTimeoutError({ timeoutMs: this.timeoutMs, method, path });
+      throw err;
     } finally {
       clearTimeout(timer);
     }
@@ -290,6 +367,7 @@ export {
   CartNotFoundError,
   CartNotOpenError,
   CartSessionClient,
+  CartTimeoutError,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError2 as ThrottleError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/cart",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,8 +17,13 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
-    "@usethrottle/errors": "^1.0.0"
+    "@usethrottle/errors": "workspace:^"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
@@ -27,10 +32,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
   }
-}
+}