@usethrottle/cart 3.2.0 → 3.4.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
@@ -194,14 +230,41 @@ try {
 }
 ```
 
+`ThrottleApiError` extends the shared **`ThrottleError`** from
+[`@usethrottle/errors`](https://www.npmjs.com/package/@usethrottle/errors),
+re-exported here. If you use more than one Throttle SDK you can catch all of
+their errors with a single check — `instanceof ThrottleApiError` keeps working:
+
+```ts
+import { ThrottleError } from '@usethrottle/cart'; // same class across every SDK
+
+try {
+  await cart.items.add(cartId, item);
+  await checkout.completeSession(sessionId, payment);
+} catch (e) {
+  if (e instanceof ThrottleError) {
+    console.error(e.statusCode, e.code, e.message);
+  }
+}
+```
+
+### Line item `imageUrl`
+
+`imageUrl` accepts an absolute `http(s)` URL **or** a relative path like
+`/images/x.png`. Relative paths are resolved to an absolute URL against your
+application's storefront base URL so the image renders on the hosted checkout —
+set it with `PUT /v1/embed-config { "storefrontBaseUrl": "https://yourstore.com" }`
+(the first `allowedOrigin` is used as a fallback). A relative path with no
+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,22 +21,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CartClient: () => CartClient,
+  CartSessionClient: () => CartSessionClient,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
-  ThrottleApiError: () => ThrottleApiError
+  ThrottleApiError: () => ThrottleApiError,
+  ThrottleError: () => import_errors2.ThrottleError,
+  isThrottleError: () => import_errors2.isThrottleError
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var ThrottleApiError = class extends Error {
-  code;
-  statusCode;
-  details;
+var import_errors = require("@usethrottle/errors");
+var import_errors2 = require("@usethrottle/errors");
+var ThrottleApiError = class extends import_errors.ThrottleError {
   constructor(args) {
-    super(args.message);
+    super(args);
     this.name = "ThrottleApiError";
-    this.code = args.code;
-    this.statusCode = args.statusCode;
-    this.details = args.details;
   }
 };
 
@@ -189,9 +188,119 @@ 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
+  ThrottleApiError,
+  ThrottleError,
+  isThrottleError
 });

package/dist/index.d.cts

@@ -1,3 +1,6 @@
+import { ThrottleError } from '@usethrottle/errors';
+export { ThrottleError, isThrottleError } from '@usethrottle/errors';
+
 interface Cart {
     id: string;
     workspaceId: string;
@@ -116,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 {
@@ -359,9 +369,101 @@ declare class StorefrontQuoteClient {
     quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
 }
 
-declare class ThrottleApiError extends Error {
-    readonly code: string;
-    readonly statusCode: number;
+/**
+ * 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.
+ *
+ * Extends the shared {@link ThrottleError} so a single
+ * `catch (e) { if (e instanceof ThrottleError) … }` covers errors from every
+ * Throttle SDK. `instanceof ThrottleApiError` keeps working for existing code.
+ */
+declare class ThrottleApiError extends ThrottleError {
     readonly details?: Record<string, unknown>;
     constructor(args: {
         code: string;
@@ -371,4 +473,4 @@ declare class ThrottleApiError extends Error {
     });
 }
 
-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

@@ -1,3 +1,6 @@
+import { ThrottleError } from '@usethrottle/errors';
+export { ThrottleError, isThrottleError } from '@usethrottle/errors';
+
 interface Cart {
     id: string;
     workspaceId: string;
@@ -116,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 {
@@ -359,9 +369,101 @@ declare class StorefrontQuoteClient {
     quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
 }
 
-declare class ThrottleApiError extends Error {
-    readonly code: string;
-    readonly statusCode: number;
+/**
+ * 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.
+ *
+ * Extends the shared {@link ThrottleError} so a single
+ * `catch (e) { if (e instanceof ThrottleError) … }` covers errors from every
+ * Throttle SDK. `instanceof ThrottleApiError` keeps working for existing code.
+ */
+declare class ThrottleApiError extends ThrottleError {
     readonly details?: Record<string, unknown>;
     constructor(args: {
         code: string;
@@ -371,4 +473,4 @@ declare class ThrottleApiError extends Error {
     });
 }
 
-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

@@ -1,14 +1,10 @@
 // src/errors.ts
-var ThrottleApiError = class extends Error {
-  code;
-  statusCode;
-  details;
+import { ThrottleError } from "@usethrottle/errors";
+import { ThrottleError as ThrottleError2, isThrottleError } from "@usethrottle/errors";
+var ThrottleApiError = class extends ThrottleError {
   constructor(args) {
-    super(args.message);
+    super(args);
     this.name = "ThrottleApiError";
-    this.code = args.code;
-    this.statusCode = args.statusCode;
-    this.details = args.details;
   }
 };
 
@@ -161,8 +157,118 @@ 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
+  ThrottleApiError,
+  ThrottleError2 as ThrottleError,
+  isThrottleError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/cart",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,6 +17,9 @@
     "dist",
     "README.md"
   ],
+  "dependencies": {
+    "@usethrottle/errors": "^1.0.0"
+  },
   "devDependencies": {
     "tsup": "^8.0.0",
     "vitest": "^2.1.9",