@usethrottle/cart 0.1.0 → 1.0.0

package/README.md

@@ -50,6 +50,69 @@ console.log(order.id, order.status);
 
 All monetary values are integers in the smallest currency unit (cents for USD).
 
+## Shipping and tax
+
+Use the secret-key client on your backend to calculate and persist cart totals
+with Throttle's native engine:
+
+```ts
+const estimate = await client.shippingTax.calculateCart(cart.id, {
+  kind: 'cart_estimate',
+});
+
+const locked = await client.shippingTax.calculateCart(cart.id, {
+  kind: 'checkout_final',
+  selectedShippingMethodId: estimate.shipping.selectedMethod?.id,
+});
+```
+
+External stores can also request read-only storefront quotes with a publishable
+`pk_` quote token. Create one from the dashboard Shipping & Tax page or with
+`POST /api/v1/shipping-tax/quote-tokens`.
+
+```ts
+import { StorefrontQuoteClient } from '@usethrottle/cart';
+
+const quotes = new StorefrontQuoteClient({
+  storeId: 'store_uuid',
+  quoteToken: 'pk_publishable_quote_token',
+});
+
+const estimate = await quotes.quote({
+  currency: 'USD',
+  items: [
+    {
+      id: 'sku_123',
+      quantity: 1,
+      subtotalAmount: 12900,
+      requiresShipping: true,
+      taxCategory: 'standard',
+    },
+  ],
+  addresses: {
+    shipping: { countryCode: 'US', stateProvince: 'CA', postalCode: '90001' },
+  },
+});
+```
+
+For provider-owned totals, set the store to `provider_totals` mode and push the
+final snapshot from your backend:
+
+```ts
+await client.shippingTax.pushExternalSnapshot({
+  storeId: 'store_uuid',
+  cartId: cart.id,
+  currency: 'USD',
+  totals: {
+    subtotal: 12900,
+    discountTotal: 0,
+    shippingTotal: 600,
+    taxTotal: 1215,
+    total: 14715,
+  },
+});
+```
+
 ## Subscriptions
 
 Pass `type: 'subscription'` and a `recurring` block on the line item:

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CartClient: () => CartClient,
+  StorefrontQuoteClient: () => StorefrontQuoteClient,
   ThrottleApiError: () => ThrottleApiError
 });
 module.exports = __toCommonJS(index_exports);
@@ -48,7 +49,7 @@ var CartClient = class {
   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.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
     this.timeoutMs = opts.timeoutMs ?? 3e4;
   }
@@ -111,6 +112,12 @@ var CartClient = class {
       clear: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/tax-lines`)
     };
   }
+  get shippingTax() {
+    return {
+      calculateCart: (cartId, input = {}) => this.request("POST", `/api/v1/shipping-tax/carts/${cartId}/calculate`, input),
+      pushExternalSnapshot: (input) => this.request("POST", "/api/v1/shipping-tax/external-snapshots", input)
+    };
+  }
   get events() {
     return {
       list: (cartId, opts) => {
@@ -123,8 +130,61 @@ var CartClient = class {
     };
   }
 };
+
+// src/storefront.ts
+var StorefrontQuoteClient = class {
+  storeId;
+  quoteToken;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  origin;
+  constructor(opts) {
+    if (!opts.storeId) throw new Error("StorefrontQuoteClient: storeId is required");
+    if (!opts.quoteToken?.startsWith("pk_")) {
+      throw new Error("StorefrontQuoteClient: quoteToken must be a publishable pk_ token");
+    }
+    this.storeId = opts.storeId;
+    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;
+  }
+  async quote(input) {
+    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}/api/v1/shipping-tax/quotes`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          storeId: this.storeId,
+          quoteToken: this.quoteToken,
+          ...input
+        }),
+        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,
+  StorefrontQuoteClient,
   ThrottleApiError
 });

package/dist/index.d.cts

@@ -58,7 +58,7 @@ interface SelectedShipping {
 }
 interface AppliedDiscount {
     code: string;
-    type: 'percentage' | 'fixed_amount' | 'free_shipping';
+    type: 'percentage' | 'fixed_amount' | 'free_shipping' | 'buy_x_get_y';
     amount: number;
     currency: string;
     freeShipping: boolean;
@@ -153,6 +153,139 @@ interface Order {
     total: number;
     currency: string;
 }
+interface ShippingTaxAddress {
+    countryCode?: string;
+    stateProvince?: string;
+    postalCode?: string;
+    city?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    [key: string]: unknown;
+}
+interface ShippingTaxQuoteItem {
+    id: string;
+    quantity?: number;
+    unitPrice?: number;
+    subtotalAmount: number;
+    discountAmount?: number;
+    productType?: string;
+    requiresShipping?: boolean;
+    shippingProfileIds?: string[];
+    taxCategory?: string;
+    weight?: number;
+    weightUnit?: 'lb' | 'kg';
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ShippingTaxQuoteInput {
+    currency?: string;
+    items: ShippingTaxQuoteItem[];
+    discountsTotal?: number;
+    selectedShippingMethodId?: string | null;
+    addresses?: {
+        shipping?: ShippingTaxAddress | null;
+        billing?: ShippingTaxAddress | null;
+        customer?: ShippingTaxAddress | null;
+    };
+}
+interface ShippingTaxCartCalculateInput {
+    kind?: 'cart_estimate' | 'checkout_final';
+    selectedShippingMethodId?: string | null;
+    persist?: boolean;
+}
+interface ShippingTaxMethod {
+    id: string;
+    type?: 'ship' | 'pickup';
+    label: string;
+    amount: number;
+    currency: string;
+    deliveryWindowLabel?: string | null;
+    deliveryMinDays?: number | null;
+    deliveryMaxDays?: number | null;
+    warnings?: Array<{
+        code: string;
+        message: string;
+        field?: string;
+    }>;
+}
+interface ShippingTaxCalculationResponse {
+    snapshotId?: string;
+    kind: 'quote' | 'cart_estimate' | 'checkout_final' | 'external_snapshot';
+    status: 'estimated' | 'final' | 'failed';
+    source: 'throttle_engine' | 'provider_totals' | 'external_push';
+    storeId: string;
+    merchantId?: string;
+    currency: string;
+    configId?: string;
+    configVersion?: number;
+    shippingRequired: boolean;
+    shipping: {
+        shippingRequired: boolean;
+        methods: ShippingTaxMethod[];
+        selectedMethod: ShippingTaxMethod | null;
+        warnings: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        errors: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        matchedZoneIds: string[];
+    };
+    tax: {
+        taxTotal: number;
+        lines: TaxLine[];
+        warnings: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        errors: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        matchedRegionIds: string[];
+    };
+    selectedShippingMethodId?: string | null;
+    taxLines: TaxLine[];
+    totals: {
+        subtotal: number;
+        discountTotal: number;
+        shippingTotal: number;
+        taxTotal: number;
+        total: number;
+    };
+    prompts: Array<{
+        code: 'missing_info';
+        field: string;
+        message: string;
+    }>;
+    warnings: Array<{
+        code: string;
+        message: string;
+        field?: string;
+    }>;
+    errors: Array<{
+        code: string;
+        message: string;
+        field?: string;
+    }>;
+}
+interface ExternalShippingTaxSnapshotInput {
+    storeId: string;
+    cartId?: string | null;
+    checkoutSessionId?: string | null;
+    orderId?: string | null;
+    currency?: string;
+    totals: ShippingTaxCalculationResponse['totals'];
+    selectedShipping?: Record<string, unknown> | null;
+    taxLines?: TaxLine[];
+    source?: string;
+}
 
 interface CartClientOptions {
     apiKey: string;
@@ -191,6 +324,10 @@ declare class CartClient {
         set: (cartId: string, lines: TaxLineInput[]) => Promise<Cart>;
         clear: (cartId: string) => Promise<Cart>;
     };
+    get shippingTax(): {
+        calculateCart: (cartId: string, input?: ShippingTaxCartCalculateInput) => Promise<ShippingTaxCalculationResponse>;
+        pushExternalSnapshot: (input: ExternalShippingTaxSnapshotInput) => Promise<ShippingTaxCalculationResponse>;
+    };
     get events(): {
         list: (cartId: string, opts?: {
             sinceSequence?: number;
@@ -199,6 +336,25 @@ declare class CartClient {
     };
 }
 
+interface StorefrontQuoteClientOptions {
+    storeId: string;
+    quoteToken: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    origin?: string;
+}
+declare class StorefrontQuoteClient {
+    private readonly storeId;
+    private readonly quoteToken;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly origin?;
+    constructor(opts: StorefrontQuoteClientOptions);
+    quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
+}
+
 declare class ThrottleApiError extends Error {
     readonly code: string;
     readonly statusCode: number;
@@ -211,4 +367,4 @@ declare class ThrottleApiError extends Error {
     });
 }
 
-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 };
+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 };

package/dist/index.d.ts

@@ -58,7 +58,7 @@ interface SelectedShipping {
 }
 interface AppliedDiscount {
     code: string;
-    type: 'percentage' | 'fixed_amount' | 'free_shipping';
+    type: 'percentage' | 'fixed_amount' | 'free_shipping' | 'buy_x_get_y';
     amount: number;
     currency: string;
     freeShipping: boolean;
@@ -153,6 +153,139 @@ interface Order {
     total: number;
     currency: string;
 }
+interface ShippingTaxAddress {
+    countryCode?: string;
+    stateProvince?: string;
+    postalCode?: string;
+    city?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    [key: string]: unknown;
+}
+interface ShippingTaxQuoteItem {
+    id: string;
+    quantity?: number;
+    unitPrice?: number;
+    subtotalAmount: number;
+    discountAmount?: number;
+    productType?: string;
+    requiresShipping?: boolean;
+    shippingProfileIds?: string[];
+    taxCategory?: string;
+    weight?: number;
+    weightUnit?: 'lb' | 'kg';
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ShippingTaxQuoteInput {
+    currency?: string;
+    items: ShippingTaxQuoteItem[];
+    discountsTotal?: number;
+    selectedShippingMethodId?: string | null;
+    addresses?: {
+        shipping?: ShippingTaxAddress | null;
+        billing?: ShippingTaxAddress | null;
+        customer?: ShippingTaxAddress | null;
+    };
+}
+interface ShippingTaxCartCalculateInput {
+    kind?: 'cart_estimate' | 'checkout_final';
+    selectedShippingMethodId?: string | null;
+    persist?: boolean;
+}
+interface ShippingTaxMethod {
+    id: string;
+    type?: 'ship' | 'pickup';
+    label: string;
+    amount: number;
+    currency: string;
+    deliveryWindowLabel?: string | null;
+    deliveryMinDays?: number | null;
+    deliveryMaxDays?: number | null;
+    warnings?: Array<{
+        code: string;
+        message: string;
+        field?: string;
+    }>;
+}
+interface ShippingTaxCalculationResponse {
+    snapshotId?: string;
+    kind: 'quote' | 'cart_estimate' | 'checkout_final' | 'external_snapshot';
+    status: 'estimated' | 'final' | 'failed';
+    source: 'throttle_engine' | 'provider_totals' | 'external_push';
+    storeId: string;
+    merchantId?: string;
+    currency: string;
+    configId?: string;
+    configVersion?: number;
+    shippingRequired: boolean;
+    shipping: {
+        shippingRequired: boolean;
+        methods: ShippingTaxMethod[];
+        selectedMethod: ShippingTaxMethod | null;
+        warnings: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        errors: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        matchedZoneIds: string[];
+    };
+    tax: {
+        taxTotal: number;
+        lines: TaxLine[];
+        warnings: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        errors: Array<{
+            code: string;
+            message: string;
+            field?: string;
+        }>;
+        matchedRegionIds: string[];
+    };
+    selectedShippingMethodId?: string | null;
+    taxLines: TaxLine[];
+    totals: {
+        subtotal: number;
+        discountTotal: number;
+        shippingTotal: number;
+        taxTotal: number;
+        total: number;
+    };
+    prompts: Array<{
+        code: 'missing_info';
+        field: string;
+        message: string;
+    }>;
+    warnings: Array<{
+        code: string;
+        message: string;
+        field?: string;
+    }>;
+    errors: Array<{
+        code: string;
+        message: string;
+        field?: string;
+    }>;
+}
+interface ExternalShippingTaxSnapshotInput {
+    storeId: string;
+    cartId?: string | null;
+    checkoutSessionId?: string | null;
+    orderId?: string | null;
+    currency?: string;
+    totals: ShippingTaxCalculationResponse['totals'];
+    selectedShipping?: Record<string, unknown> | null;
+    taxLines?: TaxLine[];
+    source?: string;
+}
 
 interface CartClientOptions {
     apiKey: string;
@@ -191,6 +324,10 @@ declare class CartClient {
         set: (cartId: string, lines: TaxLineInput[]) => Promise<Cart>;
         clear: (cartId: string) => Promise<Cart>;
     };
+    get shippingTax(): {
+        calculateCart: (cartId: string, input?: ShippingTaxCartCalculateInput) => Promise<ShippingTaxCalculationResponse>;
+        pushExternalSnapshot: (input: ExternalShippingTaxSnapshotInput) => Promise<ShippingTaxCalculationResponse>;
+    };
     get events(): {
         list: (cartId: string, opts?: {
             sinceSequence?: number;
@@ -199,6 +336,25 @@ declare class CartClient {
     };
 }
 
+interface StorefrontQuoteClientOptions {
+    storeId: string;
+    quoteToken: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    origin?: string;
+}
+declare class StorefrontQuoteClient {
+    private readonly storeId;
+    private readonly quoteToken;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly origin?;
+    constructor(opts: StorefrontQuoteClientOptions);
+    quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
+}
+
 declare class ThrottleApiError extends Error {
     readonly code: string;
     readonly statusCode: number;
@@ -211,4 +367,4 @@ declare class ThrottleApiError extends Error {
     });
 }
 
-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 };
+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 };

package/dist/index.js

@@ -21,7 +21,7 @@ var CartClient = class {
   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.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
     this.timeoutMs = opts.timeoutMs ?? 3e4;
   }
@@ -84,6 +84,12 @@ var CartClient = class {
       clear: (cartId) => this.request("DELETE", `/api/v1/carts/${cartId}/tax-lines`)
     };
   }
+  get shippingTax() {
+    return {
+      calculateCart: (cartId, input = {}) => this.request("POST", `/api/v1/shipping-tax/carts/${cartId}/calculate`, input),
+      pushExternalSnapshot: (input) => this.request("POST", "/api/v1/shipping-tax/external-snapshots", input)
+    };
+  }
   get events() {
     return {
       list: (cartId, opts) => {
@@ -96,7 +102,60 @@ var CartClient = class {
     };
   }
 };
+
+// src/storefront.ts
+var StorefrontQuoteClient = class {
+  storeId;
+  quoteToken;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  origin;
+  constructor(opts) {
+    if (!opts.storeId) throw new Error("StorefrontQuoteClient: storeId is required");
+    if (!opts.quoteToken?.startsWith("pk_")) {
+      throw new Error("StorefrontQuoteClient: quoteToken must be a publishable pk_ token");
+    }
+    this.storeId = opts.storeId;
+    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;
+  }
+  async quote(input) {
+    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}/api/v1/shipping-tax/quotes`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          storeId: this.storeId,
+          quoteToken: this.quoteToken,
+          ...input
+        }),
+        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,
+  StorefrontQuoteClient,
   ThrottleApiError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/cart",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,12 +13,10 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "README.md"],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "devDependencies": {
     "tsup": "^8.0.0",
     "vitest": "^2.1.9",
@@ -26,5 +24,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}