@usethrottle/cart 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @usethrottle/cart
+
+Typed Node.js REST client for the Throttle Cart API.
+
+## Install
+
+```bash
+npm install @usethrottle/cart
+```
+
+## Quickstart
+
+End-to-end: create a cart, build it out, and convert it to an order.
+
+```ts
+import { CartClient } from '@usethrottle/cart';
+
+const client = new CartClient({ apiKey: process.env.THROTTLE_API_KEY! });
+
+// 1. Create a cart
+const cart = await client.carts.create({ storeId: 'store_abc', currency: 'USD' });
+
+// 2. Add a line item
+await client.items.add(cart.id, {
+  type: 'product',
+  name: 'Premium Widget',
+  unitPrice: 2999,
+  quantity: 2,
+});
+
+// 3. Select a shipping method
+await client.shipping.select(cart.id, {
+  methodId: 'fedex_ground',
+  displayName: 'FedEx Ground',
+  rateAmount: 599,
+});
+
+// 4. Apply a discount code
+await client.discounts.apply(cart.id, 'SAVE10');
+
+// 5. Set tax lines
+await client.taxLines.set(cart.id, [
+  { lineItemId: '...', jurisdictionCode: 'US-NY', taxType: 'sales', rate: 0.04, amount: 400 },
+]);
+
+// 6. Checkout → Order
+const order = await client.carts.checkout(cart.id, { paymentMethod: 'card' });
+console.log(order.id, order.status);
+```
+
+All monetary values are integers in the smallest currency unit (cents for USD).
+
+## Subscriptions
+
+Pass `type: 'subscription'` and a `recurring` block on the line item:
+
+```ts
+await client.items.add(cart.id, {
+  type: 'subscription',
+  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.
+
+## Events
+
+Every mutation appends an immutable event to the cart's event log. Fetch it with:
+
+```ts
+const events = await client.events.list(cart.id);
+// [{ eventType: 'cart.created', sequence: 1, ... }, ...]
+
+// Poll only new events since the last sequence you saw
+const newEvents = await client.events.list(cart.id, { sinceSequence: 5, limit: 50 });
+```
+
+For real-time delivery, subscribe to Throttle's outbound webhooks from your
+merchant dashboard. Webhooks are signed with HMAC-SHA256 and fire from
+Throttle's servers to your backend over HTTPS.
+
+## Errors
+
+All non-2xx responses throw `ThrottleApiError`. Inspect `code` for the
+machine-readable reason and `statusCode` for the HTTP status:
+
+```ts
+import { ThrottleApiError } from '@usethrottle/cart';
+
+try {
+  await client.discounts.apply(cart.id, 'EXPIRED');
+} catch (e) {
+  if (e instanceof ThrottleApiError && e.code === 'discount_invalid') {
+    // surface a user-friendly message
+  }
+  if (e instanceof ThrottleApiError) {
+    console.error(e.statusCode, e.code, e.message);
+  }
+}
+```
+
+## Client options
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey` | — | **Required.** Your Throttle secret key (`sk_…`). |
+| `baseUrl` | `https://throttle-api-gff1.onrender.com` | Override for local dev or staging. |
+| `timeoutMs` | `30000` | Per-request abort timeout in ms. |
+| `fetch` | `globalThis.fetch` | Custom fetch implementation (e.g. `node-fetch`). |
+
+## See also
+
+- [API client (auto-generated): `@usethrottle/api-client`](https://www.npmjs.com/package/@usethrottle/api-client)
+- [React embed components: `@usethrottle/checkout-react`](https://www.npmjs.com/package/@usethrottle/checkout-react)

package/dist/index.cjs

@@ -0,0 +1,130 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CartClient: () => CartClient,
+  ThrottleApiError: () => ThrottleApiError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ThrottleApiError = class extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(args) {
+    super(args.message);
+    this.name = "ThrottleApiError";
+    this.code = args.code;
+    this.statusCode = args.statusCode;
+    this.details = args.details;
+  }
+};
+
+// src/client.ts
+var CartClient = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("CartClient: apiKey is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://throttle-api-gff1.onrender.com").replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(method, path, body) {
+    const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: { "x-api-key": this.apiKey, "content-type": "application/json" },
+        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);
+    }
+  }
+  get carts() {
+    return {
+      create: (input) => this.request("POST", "/api/v1/carts", input),
+      get: (id) => this.request("GET", `/api/v1/carts/${id}`),
+      update: (id, input) => this.request("PATCH", `/api/v1/carts/${id}`, input),
+      checkout: (id, input) => this.request("POST", `/api/v1/carts/${id}/checkout`, input ?? {}),
+      merge: (id, customerId) => this.request("POST", `/api/v1/carts/${id}/merge`, { customerId })
+    };
+  }
+  get items() {
+    return {
+      add: (cartId, input) => this.request("POST", `/api/v1/carts/${cartId}/items`, input),
+      update: (cartId, itemId, input) => this.request("PATCH", `/api/v1/carts/${cartId}/items/${itemId}`, input),
+      remove: (cartId, itemId) => this.request("DELETE", `/api/v1/carts/${cartId}/items/${itemId}`)
+    };
+  }
+  get shipping() {
+    return {
+      select: (cartId, input) => this.request("POST", `/api/v1/carts/${cartId}/shipping`, input),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/shipping`)
+    };
+  }
+  get discounts() {
+    return {
+      apply: (cartId, code) => this.request("POST", `/api/v1/carts/${cartId}/apply-discount`, { code }),
+      remove: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/discount`)
+    };
+  }
+  get taxLines() {
+    return {
+      set: (cartId, lines) => this.request("PUT", `/api/v1/carts/${cartId}/tax-lines`, { lines }),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/tax-lines`)
+    };
+  }
+  get events() {
+    return {
+      list: (cartId, opts) => {
+        const params = new URLSearchParams();
+        if (opts?.sinceSequence !== void 0) params.set("sinceSequence", String(opts.sinceSequence));
+        if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+        const qs = params.toString();
+        return this.request("GET", `/api/v1/carts/${cartId}/events${qs ? "?" + qs : ""}`);
+      }
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CartClient,
+  ThrottleApiError
+});

package/dist/index.d.cts

@@ -0,0 +1,214 @@
+interface Cart {
+    id: string;
+    merchantId: string;
+    storeId: string | null;
+    customerId: string | null;
+    status: 'open' | 'checkout' | 'converted' | 'abandoned';
+    currency: string;
+    subtotal: number;
+    taxTotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    total: number;
+    billingAddress: Record<string, unknown> | null;
+    shippingAddress: Record<string, unknown> | null;
+    notes: string | null;
+    expiresAt: string | null;
+    externalRef?: {
+        connectionId: string;
+        externalCartId: string;
+        externalMetadata: Record<string, unknown>;
+    };
+    selectedShipping?: SelectedShipping | null;
+    appliedDiscount?: AppliedDiscount | null;
+    taxLines?: TaxLine[];
+    lineItems?: LineItem[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface LineItem {
+    id: string;
+    cartId: string;
+    type: 'product' | 'subscription' | 'service' | 'ticket' | 'donation' | 'custom';
+    referenceId: string | null;
+    name: string;
+    description: string | null;
+    unitPrice: number;
+    quantity: number;
+    subtotal: number;
+    taxAmount: number;
+    discountAmount: number;
+    total: number;
+    recurring: {
+        interval: string;
+        count: number | null;
+    } | null;
+    imageUrl: string | null;
+    position: number;
+    metadata: Record<string, unknown>;
+}
+interface SelectedShipping {
+    methodId: string;
+    carrier: string | null;
+    serviceCode: string | null;
+    displayName: string;
+    rateAmount: number;
+    currency: string;
+    estimatedDeliveryDays: number | null;
+}
+interface AppliedDiscount {
+    code: string;
+    type: 'percentage' | 'fixed_amount' | 'free_shipping';
+    amount: number;
+    currency: string;
+    freeShipping: boolean;
+    validUntil: string | null;
+    snapshotHash: string;
+}
+interface TaxLine {
+    id: string;
+    lineItemId: string;
+    jurisdictionCode: string;
+    jurisdictionName: string | null;
+    taxType: 'sales' | 'vat' | 'gst' | 'pst' | 'hst' | 'service' | 'excise' | 'other';
+    rate: number;
+    amount: number;
+    currency: string;
+}
+interface CartEvent {
+    id: string;
+    cartId: string;
+    eventType: string;
+    sequence: number;
+    payload: Record<string, unknown>;
+    actorType: 'system' | 'merchant' | 'buyer' | 'connector';
+    actorId: string | null;
+    createdAt: string;
+}
+interface CreateCartInput {
+    storeId: string;
+    customerId?: string;
+    currency?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCartInput {
+    customerId?: string;
+    billingAddress?: Record<string, unknown>;
+    shippingAddress?: Record<string, unknown>;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AddLineItemInput {
+    type?: LineItem['type'];
+    referenceId?: string;
+    name: string;
+    description?: string;
+    unitPrice: number;
+    quantity?: number;
+    taxAmount?: number;
+    discountAmount?: number;
+    recurring?: {
+        interval: string;
+        count: number | null;
+    } | null;
+    imageUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateLineItemInput {
+    quantity?: number;
+    unitPrice?: number;
+    taxAmount?: number;
+    discountAmount?: number;
+    metadata?: Record<string, unknown>;
+}
+interface SelectShippingInput {
+    methodId: string;
+    displayName: string;
+    rateAmount: number;
+    currency?: string;
+    carrier?: string;
+    serviceCode?: string;
+    estimatedDeliveryDays?: number;
+}
+interface TaxLineInput {
+    lineItemId: string;
+    jurisdictionCode: string;
+    jurisdictionName?: string;
+    taxType: TaxLine['taxType'];
+    rate: number;
+    amount: number;
+    currency?: string;
+}
+interface CheckoutInput {
+    paymentMethod?: string;
+    netDays?: number;
+    termsAccepted?: boolean;
+    termsSnapshot?: string;
+    invoiceNumber?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Order {
+    id: string;
+    status: string;
+    total: number;
+    currency: string;
+}
+
+interface CartClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+declare class CartClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: CartClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    get carts(): {
+        create: (input: CreateCartInput) => Promise<Cart>;
+        get: (id: string) => Promise<Cart>;
+        update: (id: string, input: UpdateCartInput) => Promise<Cart>;
+        checkout: (id: string, input?: CheckoutInput) => Promise<Order>;
+        merge: (id: string, customerId: string) => Promise<Cart>;
+    };
+    get items(): {
+        add: (cartId: string, input: AddLineItemInput) => Promise<LineItem>;
+        update: (cartId: string, itemId: string, input: UpdateLineItemInput) => Promise<LineItem>;
+        remove: (cartId: string, itemId: string) => Promise<void>;
+    };
+    get shipping(): {
+        select: (cartId: string, input: SelectShippingInput) => Promise<Cart>;
+        clear: (cartId: string) => Promise<Cart>;
+    };
+    get discounts(): {
+        apply: (cartId: string, code: string) => Promise<Cart>;
+        remove: (cartId: string) => Promise<Cart>;
+    };
+    get taxLines(): {
+        set: (cartId: string, lines: TaxLineInput[]) => Promise<Cart>;
+        clear: (cartId: string) => Promise<Cart>;
+    };
+    get events(): {
+        list: (cartId: string, opts?: {
+            sinceSequence?: number;
+            limit?: number;
+        }) => Promise<CartEvent[]>;
+    };
+}
+
+declare class ThrottleApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: Record<string, unknown>;
+    constructor(args: {
+        code: string;
+        message: string;
+        statusCode: number;
+        details?: Record<string, unknown>;
+    });
+}
+
+export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, type CheckoutInput, type CreateCartInput, type LineItem, type Order, type SelectShippingInput, type SelectedShipping, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateLineItemInput };

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+interface Cart {
+    id: string;
+    merchantId: string;
+    storeId: string | null;
+    customerId: string | null;
+    status: 'open' | 'checkout' | 'converted' | 'abandoned';
+    currency: string;
+    subtotal: number;
+    taxTotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    total: number;
+    billingAddress: Record<string, unknown> | null;
+    shippingAddress: Record<string, unknown> | null;
+    notes: string | null;
+    expiresAt: string | null;
+    externalRef?: {
+        connectionId: string;
+        externalCartId: string;
+        externalMetadata: Record<string, unknown>;
+    };
+    selectedShipping?: SelectedShipping | null;
+    appliedDiscount?: AppliedDiscount | null;
+    taxLines?: TaxLine[];
+    lineItems?: LineItem[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface LineItem {
+    id: string;
+    cartId: string;
+    type: 'product' | 'subscription' | 'service' | 'ticket' | 'donation' | 'custom';
+    referenceId: string | null;
+    name: string;
+    description: string | null;
+    unitPrice: number;
+    quantity: number;
+    subtotal: number;
+    taxAmount: number;
+    discountAmount: number;
+    total: number;
+    recurring: {
+        interval: string;
+        count: number | null;
+    } | null;
+    imageUrl: string | null;
+    position: number;
+    metadata: Record<string, unknown>;
+}
+interface SelectedShipping {
+    methodId: string;
+    carrier: string | null;
+    serviceCode: string | null;
+    displayName: string;
+    rateAmount: number;
+    currency: string;
+    estimatedDeliveryDays: number | null;
+}
+interface AppliedDiscount {
+    code: string;
+    type: 'percentage' | 'fixed_amount' | 'free_shipping';
+    amount: number;
+    currency: string;
+    freeShipping: boolean;
+    validUntil: string | null;
+    snapshotHash: string;
+}
+interface TaxLine {
+    id: string;
+    lineItemId: string;
+    jurisdictionCode: string;
+    jurisdictionName: string | null;
+    taxType: 'sales' | 'vat' | 'gst' | 'pst' | 'hst' | 'service' | 'excise' | 'other';
+    rate: number;
+    amount: number;
+    currency: string;
+}
+interface CartEvent {
+    id: string;
+    cartId: string;
+    eventType: string;
+    sequence: number;
+    payload: Record<string, unknown>;
+    actorType: 'system' | 'merchant' | 'buyer' | 'connector';
+    actorId: string | null;
+    createdAt: string;
+}
+interface CreateCartInput {
+    storeId: string;
+    customerId?: string;
+    currency?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCartInput {
+    customerId?: string;
+    billingAddress?: Record<string, unknown>;
+    shippingAddress?: Record<string, unknown>;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AddLineItemInput {
+    type?: LineItem['type'];
+    referenceId?: string;
+    name: string;
+    description?: string;
+    unitPrice: number;
+    quantity?: number;
+    taxAmount?: number;
+    discountAmount?: number;
+    recurring?: {
+        interval: string;
+        count: number | null;
+    } | null;
+    imageUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateLineItemInput {
+    quantity?: number;
+    unitPrice?: number;
+    taxAmount?: number;
+    discountAmount?: number;
+    metadata?: Record<string, unknown>;
+}
+interface SelectShippingInput {
+    methodId: string;
+    displayName: string;
+    rateAmount: number;
+    currency?: string;
+    carrier?: string;
+    serviceCode?: string;
+    estimatedDeliveryDays?: number;
+}
+interface TaxLineInput {
+    lineItemId: string;
+    jurisdictionCode: string;
+    jurisdictionName?: string;
+    taxType: TaxLine['taxType'];
+    rate: number;
+    amount: number;
+    currency?: string;
+}
+interface CheckoutInput {
+    paymentMethod?: string;
+    netDays?: number;
+    termsAccepted?: boolean;
+    termsSnapshot?: string;
+    invoiceNumber?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Order {
+    id: string;
+    status: string;
+    total: number;
+    currency: string;
+}
+
+interface CartClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+declare class CartClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: CartClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    get carts(): {
+        create: (input: CreateCartInput) => Promise<Cart>;
+        get: (id: string) => Promise<Cart>;
+        update: (id: string, input: UpdateCartInput) => Promise<Cart>;
+        checkout: (id: string, input?: CheckoutInput) => Promise<Order>;
+        merge: (id: string, customerId: string) => Promise<Cart>;
+    };
+    get items(): {
+        add: (cartId: string, input: AddLineItemInput) => Promise<LineItem>;
+        update: (cartId: string, itemId: string, input: UpdateLineItemInput) => Promise<LineItem>;
+        remove: (cartId: string, itemId: string) => Promise<void>;
+    };
+    get shipping(): {
+        select: (cartId: string, input: SelectShippingInput) => Promise<Cart>;
+        clear: (cartId: string) => Promise<Cart>;
+    };
+    get discounts(): {
+        apply: (cartId: string, code: string) => Promise<Cart>;
+        remove: (cartId: string) => Promise<Cart>;
+    };
+    get taxLines(): {
+        set: (cartId: string, lines: TaxLineInput[]) => Promise<Cart>;
+        clear: (cartId: string) => Promise<Cart>;
+    };
+    get events(): {
+        list: (cartId: string, opts?: {
+            sinceSequence?: number;
+            limit?: number;
+        }) => Promise<CartEvent[]>;
+    };
+}
+
+declare class ThrottleApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: Record<string, unknown>;
+    constructor(args: {
+        code: string;
+        message: string;
+        statusCode: number;
+        details?: Record<string, unknown>;
+    });
+}
+
+export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, type CheckoutInput, type CreateCartInput, type LineItem, type Order, type SelectShippingInput, type SelectedShipping, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateLineItemInput };

package/dist/index.js

@@ -0,0 +1,102 @@
+// src/errors.ts
+var ThrottleApiError = class extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(args) {
+    super(args.message);
+    this.name = "ThrottleApiError";
+    this.code = args.code;
+    this.statusCode = args.statusCode;
+    this.details = args.details;
+  }
+};
+
+// src/client.ts
+var CartClient = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("CartClient: apiKey is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://throttle-api-gff1.onrender.com").replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(method, path, body) {
+    const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: { "x-api-key": this.apiKey, "content-type": "application/json" },
+        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);
+    }
+  }
+  get carts() {
+    return {
+      create: (input) => this.request("POST", "/api/v1/carts", input),
+      get: (id) => this.request("GET", `/api/v1/carts/${id}`),
+      update: (id, input) => this.request("PATCH", `/api/v1/carts/${id}`, input),
+      checkout: (id, input) => this.request("POST", `/api/v1/carts/${id}/checkout`, input ?? {}),
+      merge: (id, customerId) => this.request("POST", `/api/v1/carts/${id}/merge`, { customerId })
+    };
+  }
+  get items() {
+    return {
+      add: (cartId, input) => this.request("POST", `/api/v1/carts/${cartId}/items`, input),
+      update: (cartId, itemId, input) => this.request("PATCH", `/api/v1/carts/${cartId}/items/${itemId}`, input),
+      remove: (cartId, itemId) => this.request("DELETE", `/api/v1/carts/${cartId}/items/${itemId}`)
+    };
+  }
+  get shipping() {
+    return {
+      select: (cartId, input) => this.request("POST", `/api/v1/carts/${cartId}/shipping`, input),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/shipping`)
+    };
+  }
+  get discounts() {
+    return {
+      apply: (cartId, code) => this.request("POST", `/api/v1/carts/${cartId}/apply-discount`, { code }),
+      remove: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/discount`)
+    };
+  }
+  get taxLines() {
+    return {
+      set: (cartId, lines) => this.request("PUT", `/api/v1/carts/${cartId}/tax-lines`, { lines }),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/tax-lines`)
+    };
+  }
+  get events() {
+    return {
+      list: (cartId, opts) => {
+        const params = new URLSearchParams();
+        if (opts?.sinceSequence !== void 0) params.set("sinceSequence", String(opts.sinceSequence));
+        if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+        const qs = params.toString();
+        return this.request("GET", `/api/v1/carts/${cartId}/events${qs ? "?" + qs : ""}`);
+      }
+    };
+  }
+};
+export {
+  CartClient,
+  ThrottleApiError
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@usethrottle/cart",
+  "version": "0.1.0",
+  "description": "Typed REST client for the Throttle Cart API.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "vitest": "^2.1.9",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}