@usethrottle/cart 3.11.0 → 3.12.0

package/README.md

@@ -66,8 +66,11 @@ All monetary values are integers in the smallest currency unit (cents for USD).
 `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.
+the browser, authorized by a storefront quote token (`qt_…`, the same token used
+by `StorefrontQuoteClient`) plus your application's origin allowlist. Quote
+tokens minted before `qt_` start with `pk_` and keep working. A `pk_`
+publishable API key is a different credential and is refused with
+`401 invalid_quote_token`.
 
 Set your allowed origins first (`PUT /api/v1/embed-config`), then:
 
@@ -77,7 +80,7 @@ import { CartSessionClient } from '@usethrottle/cart';
 const cart = new CartSessionClient({
   applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
   environmentId: 'a1b2c3d4-...',
-  quoteToken: 'pk_live_...',
+  quoteToken: 'qt_...',
 });
 
 // Create a new session (store cart.cartSessionId in localStorage),
@@ -171,8 +174,8 @@ const locked = await client.shippingTax.calculateCart(cart.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
+External stores can also request read-only storefront quotes with a storefront
+quote token (`qt_…`, or a legacy `pk_…` quote token). Create one from the dashboard Shipping & Tax page or with
 `POST /api/v1/shipping-tax/quote-tokens`.
 
 ```ts
@@ -180,7 +183,7 @@ import { StorefrontQuoteClient } from '@usethrottle/cart';
 
 const quotes = new StorefrontQuoteClient({
   applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
-  quoteToken: 'pk_publishable_quote_token',
+  quoteToken: 'qt_storefront_quote_token',
 });
 
 const estimate = await quotes.quote({

package/dist/index.cjs

@@ -287,7 +287,7 @@ var CartSessionClient = class _CartSessionClient {
   async create(input = {}) {
     if (this.isForSessionClient) {
       throw new Error(
-        "CartSessionClient: this client was created with forSession() and cannot call create(). Construct a CartSessionClient with a real pk_ publishable token instead."
+        "CartSessionClient: this client was created with forSession() and cannot call create(). Construct a CartSessionClient with a real qt_ quote token instead."
       );
     }
     const data = await this.request("POST", "/api/v1/cart-sessions", {
@@ -352,7 +352,7 @@ var CartSessionClient = class _CartSessionClient {
   /**
    * Bind to an existing session without a publishable token.
    *
-   * `create()` needs a `pk_` token; every other route is authorized by the
+   * `create()` needs a quote token; every other route is authorized by the
    * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
    * hosted cart page, or a storefront restoring from localStorage — would
    * otherwise have to invent a token to satisfy the constructor.

package/dist/index.d.cts

@@ -97,6 +97,19 @@ interface LineRecurringInput {
     intervalCount?: number;
     totalPayments?: number;
     trialDays?: number;
+    /**
+     * Custom installment schedule: 2-60 payments that differ in amount (per unit,
+     * minor units) and in the gap before each one. Row 0 has no gap. Replaces
+     * `interval`/`intervalUnit`/`intervalCount`/`totalPayments`/`trialDays`, which
+     * must be omitted or agree with it. The line's `unitPrice` must equal row 0.
+     */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit?: SubscriptionIntervalUnit;
+        intervalCount?: number;
+    }>;
+    /** Read-only echo on responses: the sum of every row's per-unit amount. Ignored on input. */
+    scheduleUnitTotal?: number;
 }
 /** A merchant-declared subscription line's stored terms (it carries `plan`). */
 interface StoredLineRecurring {
@@ -111,6 +124,14 @@ interface StoredLineRecurring {
     amount: number | null;
     /** Display mirror of `totalPayments`. */
     count: number | null;
+    /** Present only on a custom installment schedule line. */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit: string | null;
+        intervalCount: number | null;
+    }>;
+    /** Present only on a schedule line: the sum of every row's per-unit amount. */
+    scheduleUnitTotal?: number;
 }
 /** The plan line Throttle adds for a checkout session `recurring` intent. */
 interface LegacyLineRecurring {
@@ -506,8 +527,9 @@ declare class StorefrontQuoteClient {
 /**
  * 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
+ * it creates and mutates a Throttle cart authorized by a storefront quote token
+ * (`qt_…`, or a legacy `pk_…` quote token; the same token used by
+ * {@link StorefrontQuoteClient}, not a `pk_` publishable API key) plus the
  * application origin allowlist, and an opaque `cart_…` session id scoped to that
  * one cart.
  *
@@ -522,9 +544,14 @@ declare class StorefrontQuoteClient {
 interface CartSessionClientOptions {
     /** Application UUID. */
     applicationId: string;
-    /** Workspace environment UUID the publishable token was minted for. */
+    /** Workspace environment UUID the quote token was minted for. */
     environmentId: string;
-    /** Publishable storefront quote token (`pk_…`). */
+    /**
+     * Storefront quote token (`qt_…`), from the dashboard Shipping & Tax page or
+     * `POST /api/v1/shipping-tax/quote-tokens`. Tokens minted before `qt_` start
+     * with `pk_` and keep working. A `pk_` publishable API key is a different
+     * credential and is refused (`401 invalid_quote_token`).
+     */
     quoteToken: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
@@ -644,7 +671,7 @@ declare class CartSessionClient {
     /**
      * Bind to an existing session without a publishable token.
      *
-     * `create()` needs a `pk_` token; every other route is authorized by the
+     * `create()` needs a quote token; every other route is authorized by the
      * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
      * hosted cart page, or a storefront restoring from localStorage — would
      * otherwise have to invent a token to satisfy the constructor.

package/dist/index.d.ts

@@ -97,6 +97,19 @@ interface LineRecurringInput {
     intervalCount?: number;
     totalPayments?: number;
     trialDays?: number;
+    /**
+     * Custom installment schedule: 2-60 payments that differ in amount (per unit,
+     * minor units) and in the gap before each one. Row 0 has no gap. Replaces
+     * `interval`/`intervalUnit`/`intervalCount`/`totalPayments`/`trialDays`, which
+     * must be omitted or agree with it. The line's `unitPrice` must equal row 0.
+     */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit?: SubscriptionIntervalUnit;
+        intervalCount?: number;
+    }>;
+    /** Read-only echo on responses: the sum of every row's per-unit amount. Ignored on input. */
+    scheduleUnitTotal?: number;
 }
 /** A merchant-declared subscription line's stored terms (it carries `plan`). */
 interface StoredLineRecurring {
@@ -111,6 +124,14 @@ interface StoredLineRecurring {
     amount: number | null;
     /** Display mirror of `totalPayments`. */
     count: number | null;
+    /** Present only on a custom installment schedule line. */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit: string | null;
+        intervalCount: number | null;
+    }>;
+    /** Present only on a schedule line: the sum of every row's per-unit amount. */
+    scheduleUnitTotal?: number;
 }
 /** The plan line Throttle adds for a checkout session `recurring` intent. */
 interface LegacyLineRecurring {
@@ -506,8 +527,9 @@ declare class StorefrontQuoteClient {
 /**
  * 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
+ * it creates and mutates a Throttle cart authorized by a storefront quote token
+ * (`qt_…`, or a legacy `pk_…` quote token; the same token used by
+ * {@link StorefrontQuoteClient}, not a `pk_` publishable API key) plus the
  * application origin allowlist, and an opaque `cart_…` session id scoped to that
  * one cart.
  *
@@ -522,9 +544,14 @@ declare class StorefrontQuoteClient {
 interface CartSessionClientOptions {
     /** Application UUID. */
     applicationId: string;
-    /** Workspace environment UUID the publishable token was minted for. */
+    /** Workspace environment UUID the quote token was minted for. */
     environmentId: string;
-    /** Publishable storefront quote token (`pk_…`). */
+    /**
+     * Storefront quote token (`qt_…`), from the dashboard Shipping & Tax page or
+     * `POST /api/v1/shipping-tax/quote-tokens`. Tokens minted before `qt_` start
+     * with `pk_` and keep working. A `pk_` publishable API key is a different
+     * credential and is refused (`401 invalid_quote_token`).
+     */
     quoteToken: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
@@ -644,7 +671,7 @@ declare class CartSessionClient {
     /**
      * Bind to an existing session without a publishable token.
      *
-     * `create()` needs a `pk_` token; every other route is authorized by the
+     * `create()` needs a quote token; every other route is authorized by the
      * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
      * hosted cart page, or a storefront restoring from localStorage — would
      * otherwise have to invent a token to satisfy the constructor.

package/dist/index.js

@@ -252,7 +252,7 @@ var CartSessionClient = class _CartSessionClient {
   async create(input = {}) {
     if (this.isForSessionClient) {
       throw new Error(
-        "CartSessionClient: this client was created with forSession() and cannot call create(). Construct a CartSessionClient with a real pk_ publishable token instead."
+        "CartSessionClient: this client was created with forSession() and cannot call create(). Construct a CartSessionClient with a real qt_ quote token instead."
       );
     }
     const data = await this.request("POST", "/api/v1/cart-sessions", {
@@ -317,7 +317,7 @@ var CartSessionClient = class _CartSessionClient {
   /**
    * Bind to an existing session without a publishable token.
    *
-   * `create()` needs a `pk_` token; every other route is authorized by the
+   * `create()` needs a quote token; every other route is authorized by the
    * opaque `cart_…` id alone. A caller that only ever resumes — Throttle's own
    * hosted cart page, or a storefront restoring from localStorage — would
    * otherwise have to invent a token to satisfy the constructor.

package/package.json

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