@usethrottle/cart 3.3.0 → 3.5.0

package/README.md

@@ -2,7 +2,6 @@
   <img src="https://raw.githubusercontent.com/Epic-Design-Labs/app-throttle/main/packages/brand/assets/throttle-logo.png" alt="Throttle" height="56" />
 </p>
 
-
 # @usethrottle/cart
 
 Typed Node.js REST client for the Throttle Cart API.
@@ -62,6 +61,43 @@ are rejected by the API.
 
 All monetary values are integers in the smallest currency unit (cents for USD).
 
+## Browser carts (backend-less)
+
+`CartClient` carries a secret `sk_` key and must run on your server. For
+JAMstack / frontend-only storefronts that have no backend, use
+`CartSessionClient` instead — it creates and owns a Throttle cart directly from
+the browser, authorized by a publishable `pk_` quote token (the same token used
+by `StorefrontQuoteClient`) plus your application's origin allowlist.
+
+Set your allowed origins first (`PUT /api/v1/embed-config`), then:
+
+```ts
+import { CartSessionClient } from '@usethrottle/cart';
+
+const cart = new CartSessionClient({
+  applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
+  environmentId: 'a1b2c3d4-...',
+  quoteToken: 'pk_live_...',
+});
+
+// Create a new session (store cart.cartSessionId in localStorage),
+// or resume one you saved: cart.resume(savedId)
+await cart.create({ currency: 'USD' });
+
+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 });
+
+// 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',
+});
+```
+
+The opaque `cart_…` session id is scoped to exactly one cart. See the
+[cart sessions guide](https://docs.usethrottle.dev/developers/cart-sessions).
+
 ## Net-N invoice terms
 
 Cart-level invoice terms are optional. Pass `netN` on cart create or update to
@@ -223,12 +259,12 @@ resolvable base returns `400 image_url_unresolvable`.
 
 ## Client options
 
-| Option      | Default                       | Description                                                 |
-| ----------- | ----------------------------- | ----------------------------------------------------------- |
-| `apiKey`    | —                             | **Required.** Your Throttle secret key (`sk_…`).            |
-| `baseUrl`   | `https://api.usethrottle.dev` | Optional override for a dedicated Throttle API environment. |
-| `timeoutMs` | `30000`                       | Per-request abort timeout in ms.                            |
-| `fetch`     | `globalThis.fetch`            | Custom fetch implementation (e.g. `node-fetch`).            |
+| Option      | Default                       | Description                                                                                                               |
+| ----------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`    | —                             | **Required.** Your Throttle secret key (`sk_…`).                                                                          |
+| `baseUrl`   | `https://api.usethrottle.dev` | Optional Throttle API host override for self-hosted/proxy setups. Workspace environment selection comes from the API key. |
+| `timeoutMs` | `30000`                       | Per-request abort timeout in ms.                                                                                          |
+| `fetch`     | `globalThis.fetch`            | Custom fetch implementation (e.g. `node-fetch`).                                                                          |
 
 ## See also
 

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CartClient: () => CartClient,
+  CartSessionClient: () => CartSessionClient,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
   ThrottleApiError: () => ThrottleApiError,
   ThrottleError: () => import_errors2.ThrottleError,
@@ -187,9 +188,117 @@ var StorefrontQuoteClient = class {
     }
   }
 };
+
+// src/cart-session.ts
+var CartSessionClient = class {
+  applicationId;
+  environmentId;
+  quoteToken;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  origin;
+  sessionId = null;
+  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");
+    }
+    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.timeoutMs = opts.timeoutMs ?? 15e3;
+    this.origin = opts.origin;
+  }
+  /** The current bound session id (after `create()`/`resume()`), or null. */
+  get cartSessionId() {
+    return this.sessionId;
+  }
+  /** Bind to an existing session id — e.g. one restored from `localStorage`. */
+  resume(cartSessionId) {
+    this.sessionId = cartSessionId;
+    return this;
+  }
+  /** Create a new cart session and bind this client to it. */
+  async create(input = {}) {
+    const data = await this.request("POST", "/api/v1/cart-sessions", {
+      applicationId: this.applicationId,
+      environmentId: this.environmentId,
+      quoteToken: this.quoteToken,
+      ...input
+    });
+    this.sessionId = data.cartSessionId;
+    return data;
+  }
+  /** Read the current session + cart snapshot. */
+  get() {
+    return this.request("GET", this.basePath());
+  }
+  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;
+  }
+  async removeItem(itemId) {
+    return (await this.request("DELETE", `${this.basePath()}/items/${encodeURIComponent(itemId)}`)).cart;
+  }
+  async selectShipping(input) {
+    return (await this.request("POST", `${this.basePath()}/shipping`, input)).cart;
+  }
+  async clearShipping() {
+    return (await this.request("DELETE", `${this.basePath()}/shipping`)).cart;
+  }
+  async applyDiscount(code) {
+    return (await this.request("POST", `${this.basePath()}/discount`, { code })).cart;
+  }
+  async removeDiscount() {
+    return (await this.request("DELETE", `${this.basePath()}/discount`)).cart;
+  }
+  /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
+  checkout(input) {
+    return this.request("POST", `${this.basePath()}/checkout-session`, input);
+  }
+  basePath() {
+    if (!this.sessionId) {
+      throw new Error("CartSessionClient: no active session \u2014 call create() or resume(id) first");
+    }
+    return `/api/v1/cart-sessions/${encodeURIComponent(this.sessionId)}`;
+  }
+  async request(method, path, body) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const headers = { "content-type": "application/json" };
+      if (this.origin) headers.origin = this.origin;
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: ctrl.signal
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new ThrottleApiError({
+          code: json?.error?.code ?? "unknown_error",
+          message: json?.error?.message ?? `HTTP ${res.status}`,
+          statusCode: res.status,
+          details: json?.error?.details
+        });
+      }
+      return json.data;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CartClient,
+  CartSessionClient,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError,

package/dist/index.d.cts

@@ -119,6 +119,13 @@ interface AddLineItemInput {
         count: number | null;
     } | null;
     imageUrl?: string;
+    /**
+     * Whether this item is physically shippable. For external/ad-hoc catalogs
+     * with no Throttle product behind the item. Omit to infer from `type`
+     * (everything except `service` ships); set explicitly to force-include or
+     * force-exclude the item from `calculated` shipping.
+     */
+    requiresShipping?: boolean;
     metadata?: Record<string, unknown>;
 }
 interface UpdateLineItemInput {
@@ -199,6 +206,14 @@ interface ShippingTaxCartCalculateInput {
     kind?: 'cart_estimate' | 'checkout_final';
     selectedShippingMethodId?: string | null;
     persist?: boolean;
+    /**
+     * Inline shipping address. When set it is persisted to the cart (like
+     * `carts.update`) before calculation, so you can set the destination and get
+     * rates in a single request instead of a separate update + calculate.
+     */
+    shippingAddress?: ShippingTaxAddress | null;
+    /** Inline billing address; persisted to the cart before calculation. */
+    billingAddress?: ShippingTaxAddress | null;
 }
 interface ShippingTaxMethod {
     id: string;
@@ -362,6 +377,93 @@ declare class StorefrontQuoteClient {
     quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
 }
 
+/**
+ * Browser client for backend-less cart ownership. Unlike {@link CartClient}
+ * (which needs a server-side `sk_` key), `CartSessionClient` runs in the browser:
+ * it creates and mutates a Throttle cart authorized by a publishable quote token
+ * (`pk_…`, the same token used by {@link StorefrontQuoteClient}) plus the
+ * application origin allowlist, and an opaque `cart_…` session id scoped to that
+ * one cart.
+ *
+ * Typical use:
+ * ```ts
+ * const cart = new CartSessionClient({ applicationId, environmentId, quoteToken });
+ * await cart.create();                 // or cart.resume(savedId)
+ * await cart.addItem({ name: 'Widget', unitPrice: 2999, quantity: 1 });
+ * const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
+ * ```
+ */
+interface CartSessionClientOptions {
+    /** Application UUID. */
+    applicationId: string;
+    /** Workspace environment UUID the publishable token was minted for. */
+    environmentId: string;
+    /** Publishable storefront quote token (`pk_…`). */
+    quoteToken: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /**
+     * Origin to send. Browsers set the `Origin` header automatically (and it can't
+     * be overridden from JS), so this is only needed for non-browser callers
+     * (SSR, tests). It must be on the application's allowlist.
+     */
+    origin?: string;
+}
+interface CreateCartSessionInput {
+    currency?: string;
+    netN?: number;
+    metadata?: Record<string, unknown>;
+}
+interface CartSession {
+    cartSessionId: string;
+    status: string;
+    expiresAt: string;
+    cart: Cart;
+}
+interface CheckoutHandoffInput {
+    returnUrl: string;
+    cancelUrl: string;
+    customerEmail?: string;
+    allowedMethods?: string[];
+}
+interface CheckoutHandoff {
+    cartSessionId: string;
+    checkoutSessionId: string;
+    checkoutUrl: string;
+    expiresAt: string;
+}
+declare class CartSessionClient {
+    private readonly applicationId;
+    private readonly environmentId;
+    private readonly quoteToken;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly origin?;
+    private sessionId;
+    constructor(opts: CartSessionClientOptions);
+    /** The current bound session id (after `create()`/`resume()`), or null. */
+    get cartSessionId(): string | null;
+    /** Bind to an existing session id — e.g. one restored from `localStorage`. */
+    resume(cartSessionId: string): this;
+    /** Create a new cart session and bind this client to it. */
+    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>;
+    /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
+    checkout(input: CheckoutHandoffInput): Promise<CheckoutHandoff>;
+    private basePath;
+    private request;
+}
+
 /**
  * Thrown on a non-2xx response from the Throttle Cart API.
  *
@@ -379,4 +481,4 @@ declare class ThrottleApiError extends ThrottleError {
     });
 }
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, type CheckoutInput, type CreateCartInput, 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 };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, 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 };

package/dist/index.d.ts

@@ -119,6 +119,13 @@ interface AddLineItemInput {
         count: number | null;
     } | null;
     imageUrl?: string;
+    /**
+     * Whether this item is physically shippable. For external/ad-hoc catalogs
+     * with no Throttle product behind the item. Omit to infer from `type`
+     * (everything except `service` ships); set explicitly to force-include or
+     * force-exclude the item from `calculated` shipping.
+     */
+    requiresShipping?: boolean;
     metadata?: Record<string, unknown>;
 }
 interface UpdateLineItemInput {
@@ -199,6 +206,14 @@ interface ShippingTaxCartCalculateInput {
     kind?: 'cart_estimate' | 'checkout_final';
     selectedShippingMethodId?: string | null;
     persist?: boolean;
+    /**
+     * Inline shipping address. When set it is persisted to the cart (like
+     * `carts.update`) before calculation, so you can set the destination and get
+     * rates in a single request instead of a separate update + calculate.
+     */
+    shippingAddress?: ShippingTaxAddress | null;
+    /** Inline billing address; persisted to the cart before calculation. */
+    billingAddress?: ShippingTaxAddress | null;
 }
 interface ShippingTaxMethod {
     id: string;
@@ -362,6 +377,93 @@ declare class StorefrontQuoteClient {
     quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
 }
 
+/**
+ * Browser client for backend-less cart ownership. Unlike {@link CartClient}
+ * (which needs a server-side `sk_` key), `CartSessionClient` runs in the browser:
+ * it creates and mutates a Throttle cart authorized by a publishable quote token
+ * (`pk_…`, the same token used by {@link StorefrontQuoteClient}) plus the
+ * application origin allowlist, and an opaque `cart_…` session id scoped to that
+ * one cart.
+ *
+ * Typical use:
+ * ```ts
+ * const cart = new CartSessionClient({ applicationId, environmentId, quoteToken });
+ * await cart.create();                 // or cart.resume(savedId)
+ * await cart.addItem({ name: 'Widget', unitPrice: 2999, quantity: 1 });
+ * const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
+ * ```
+ */
+interface CartSessionClientOptions {
+    /** Application UUID. */
+    applicationId: string;
+    /** Workspace environment UUID the publishable token was minted for. */
+    environmentId: string;
+    /** Publishable storefront quote token (`pk_…`). */
+    quoteToken: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /**
+     * Origin to send. Browsers set the `Origin` header automatically (and it can't
+     * be overridden from JS), so this is only needed for non-browser callers
+     * (SSR, tests). It must be on the application's allowlist.
+     */
+    origin?: string;
+}
+interface CreateCartSessionInput {
+    currency?: string;
+    netN?: number;
+    metadata?: Record<string, unknown>;
+}
+interface CartSession {
+    cartSessionId: string;
+    status: string;
+    expiresAt: string;
+    cart: Cart;
+}
+interface CheckoutHandoffInput {
+    returnUrl: string;
+    cancelUrl: string;
+    customerEmail?: string;
+    allowedMethods?: string[];
+}
+interface CheckoutHandoff {
+    cartSessionId: string;
+    checkoutSessionId: string;
+    checkoutUrl: string;
+    expiresAt: string;
+}
+declare class CartSessionClient {
+    private readonly applicationId;
+    private readonly environmentId;
+    private readonly quoteToken;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly origin?;
+    private sessionId;
+    constructor(opts: CartSessionClientOptions);
+    /** The current bound session id (after `create()`/`resume()`), or null. */
+    get cartSessionId(): string | null;
+    /** Bind to an existing session id — e.g. one restored from `localStorage`. */
+    resume(cartSessionId: string): this;
+    /** Create a new cart session and bind this client to it. */
+    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>;
+    /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
+    checkout(input: CheckoutHandoffInput): Promise<CheckoutHandoff>;
+    private basePath;
+    private request;
+}
+
 /**
  * Thrown on a non-2xx response from the Throttle Cart API.
  *
@@ -379,4 +481,4 @@ declare class ThrottleApiError extends ThrottleError {
     });
 }
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, type CheckoutInput, type CreateCartInput, 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 };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, 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 };

package/dist/index.js

@@ -157,8 +157,116 @@ var StorefrontQuoteClient = class {
     }
   }
 };
+
+// src/cart-session.ts
+var CartSessionClient = class {
+  applicationId;
+  environmentId;
+  quoteToken;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  origin;
+  sessionId = null;
+  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");
+    }
+    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.timeoutMs = opts.timeoutMs ?? 15e3;
+    this.origin = opts.origin;
+  }
+  /** The current bound session id (after `create()`/`resume()`), or null. */
+  get cartSessionId() {
+    return this.sessionId;
+  }
+  /** Bind to an existing session id — e.g. one restored from `localStorage`. */
+  resume(cartSessionId) {
+    this.sessionId = cartSessionId;
+    return this;
+  }
+  /** Create a new cart session and bind this client to it. */
+  async create(input = {}) {
+    const data = await this.request("POST", "/api/v1/cart-sessions", {
+      applicationId: this.applicationId,
+      environmentId: this.environmentId,
+      quoteToken: this.quoteToken,
+      ...input
+    });
+    this.sessionId = data.cartSessionId;
+    return data;
+  }
+  /** Read the current session + cart snapshot. */
+  get() {
+    return this.request("GET", this.basePath());
+  }
+  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;
+  }
+  async removeItem(itemId) {
+    return (await this.request("DELETE", `${this.basePath()}/items/${encodeURIComponent(itemId)}`)).cart;
+  }
+  async selectShipping(input) {
+    return (await this.request("POST", `${this.basePath()}/shipping`, input)).cart;
+  }
+  async clearShipping() {
+    return (await this.request("DELETE", `${this.basePath()}/shipping`)).cart;
+  }
+  async applyDiscount(code) {
+    return (await this.request("POST", `${this.basePath()}/discount`, { code })).cart;
+  }
+  async removeDiscount() {
+    return (await this.request("DELETE", `${this.basePath()}/discount`)).cart;
+  }
+  /** Hand off to hosted/embedded checkout. Marks the session converted (no more edits). */
+  checkout(input) {
+    return this.request("POST", `${this.basePath()}/checkout-session`, input);
+  }
+  basePath() {
+    if (!this.sessionId) {
+      throw new Error("CartSessionClient: no active session \u2014 call create() or resume(id) first");
+    }
+    return `/api/v1/cart-sessions/${encodeURIComponent(this.sessionId)}`;
+  }
+  async request(method, path, body) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const headers = { "content-type": "application/json" };
+      if (this.origin) headers.origin = this.origin;
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: ctrl.signal
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new ThrottleApiError({
+          code: json?.error?.code ?? "unknown_error",
+          message: json?.error?.message ?? `HTTP ${res.status}`,
+          statusCode: res.status,
+          details: json?.error?.details
+        });
+      }
+      return json.data;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
 export {
   CartClient,
+  CartSessionClient,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError2 as ThrottleError,

package/package.json

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