@usethrottle/cart 3.10.1 → 3.11.1

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({
@@ -222,23 +225,45 @@ await client.shippingTax.pushExternalSnapshot({
 
 ## Subscriptions
 
-Mark a line item with `type: 'subscription'`:
+Put `recurring` on a line to make it a subscription. A cart can hold any
+number of one-time lines and up to 10 subscription lines, with the same plan
+or different ones. The whole cart is paid in one capture, with one shipping
+fee, and completes as one order linked to every subscription it created.
 
 ```ts
+await client.items.add(cart.id, { name: 'Coffee kit', unitPrice: 4500, quantity: 1 });
 await client.items.add(cart.id, {
-  type: 'subscription',
-  name: 'Pro Plan',
-  unitPrice: 1900,
-  quantity: 1,
+  name: 'Barista Club',
+  unitPrice: 2000,          // per period, per seat
+  quantity: 2,              // seats
+  recurring: { plan: 'club_monthly', interval: 'monthly', trialDays: 14 },
 });
 ```
 
-Then call `client.carts.checkout` as normal.
-
-The billing schedule is **not** settable through this endpoint. The add-item
-body is strict and has no `recurring` field, so sending one is rejected with
-`Unsupported field(s): recurring` — the recurring plan is attached by the
-subscription engine, not by the cart API.
+- `interval` (`weekly`, `biweekly`, `monthly`, `quarterly`, `yearly`), or
+  `intervalUnit` (`hour`, `day`, `week`, `month`) + `intervalCount`: 1 hour
+  to 1 year.
+- `totalPayments` (2–60) makes an installment plan; `trialDays` (0–365) a free
+  trial. They cannot be combined (`400 invalid_combination`).
+- `type` is forced to `subscription`, and the line never ships:
+  `requiresShipping: true` is rejected with `400 validation_error`.
+- A free-trial line is stored with `unitPrice: 0` and your price on
+  `recurring.amount`, and its name gets a "— 14-day free trial" suffix.
+- `PATCH` may change `quantity` (seats) and `metadata` only. Changing
+  `unitPrice`, `taxAmount` or `discountAmount` is `422 recurring_line_immutable`.
+  Remove the line and add it again to change its terms.
+- Each line's `subscriptionId` is set when the checkout completes.
+
+| Status | Code | When |
+|---|---|---|
+| 422 | `too_many_subscriptions` | An 11th subscription line |
+| 422 | `recurring_not_supported_for_cart` | The cart is managed by an external cart provider |
+| 422 | `recurring_line_immutable` | A PATCH changes a subscription line's price, tax or discount |
+| 400 | `invalid_line_item` | A free-trial line carries `taxAmount` or `discountAmount` |
+| 400 | `invalid_interval` / `interval_conflict` / `invalid_total_payments` / `invalid_combination` / `invalid_plan` / `invalid_trial_days` | Terms out of range |
+
+Do not also send a session `recurring` intent for the same cart. The two are
+exclusive, and session creation answers `422 recurring_source_conflict`.
 
 ## Events
 

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

@@ -79,6 +79,47 @@ interface CartSessionCart extends Omit<Cart, 'workspaceId'> {
      */
     unitCount: number;
 }
+type SubscriptionInterval = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom';
+type SubscriptionIntervalUnit = 'hour' | 'day' | 'week' | 'month';
+/**
+ * Terms that make a cart line a subscription. One subscription is created per
+ * line when the checkout completes, with `quantity` as seats; at most 10 per
+ * cart. Send `interval`, or `intervalUnit` + `intervalCount` (1 hour to 1
+ * year). `totalPayments` (2-60) makes an installment plan; `trialDays`
+ * (0-365) a free trial, not combinable with `totalPayments`. The line's
+ * `unitPrice` is the per-period price per seat.
+ */
+interface LineRecurringInput {
+    plan: string;
+    planName?: string;
+    interval?: SubscriptionInterval;
+    intervalUnit?: SubscriptionIntervalUnit;
+    intervalCount?: number;
+    totalPayments?: number;
+    trialDays?: number;
+}
+/** A merchant-declared subscription line's stored terms (it carries `plan`). */
+interface StoredLineRecurring {
+    plan: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string;
+    intervalCount: number;
+    totalPayments: number | null;
+    trialDays: number;
+    /** Renewal price per seat. Set only on a free-trial line, whose `unitPrice` is 0. */
+    amount: number | null;
+    /** Display mirror of `totalPayments`. */
+    count: number | null;
+}
+/** The plan line Throttle adds for a checkout session `recurring` intent. */
+interface LegacyLineRecurring {
+    interval: string;
+    intervalUnit?: string | null;
+    intervalCount?: number | null;
+    /** Display metadata: the number of payments to show. Not enforced. */
+    count: number | null;
+}
 interface LineItem {
     id: string;
     cartId: string;
@@ -93,16 +134,13 @@ interface LineItem {
     discountAmount: number;
     total: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Subscription terms. `'plan' in recurring` tells a merchant-declared
+     * subscription line (`StoredLineRecurring`) from the plan line a checkout
+     * session adds (`LegacyLineRecurring`). Null on a one-time line.
      */
-    recurring: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring: StoredLineRecurring | LegacyLineRecurring | null;
+    /** The subscription this line created. Null until the checkout completes. */
+    subscriptionId: string | null;
     imageUrl: string | null;
     position: number;
     metadata: Record<string, unknown>;
@@ -181,16 +219,12 @@ interface AddLineItemInput {
     taxAmount?: number;
     discountAmount?: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Makes this line a subscription: `type` is forced to `subscription`, and it
+     * never ships (`requiresShipping: true` is rejected with it). A free-trial
+     * line is stored with `unitPrice` 0 and your price on `recurring.amount`.
+     * Terms cannot change later: remove the line and add it again.
      */
-    recurring?: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring?: LineRecurringInput;
     imageUrl?: string;
     /**
      * Whether this item is physically shippable. For external/ad-hoc catalogs
@@ -201,6 +235,11 @@ interface AddLineItemInput {
     requiresShipping?: boolean;
     metadata?: Record<string, unknown>;
 }
+/**
+ * On a subscription line only `quantity` (seats) and `metadata` may change;
+ * a different `unitPrice`, `taxAmount` or `discountAmount` is
+ * 422 `recurring_line_immutable`.
+ */
 interface UpdateLineItemInput {
     quantity?: number;
     unitPrice?: number;
@@ -467,8 +506,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.
  *
@@ -483,9 +523,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;
@@ -605,7 +650,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.
@@ -705,4 +750,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, 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 UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineRecurringInput, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.d.ts

@@ -79,6 +79,47 @@ interface CartSessionCart extends Omit<Cart, 'workspaceId'> {
      */
     unitCount: number;
 }
+type SubscriptionInterval = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom';
+type SubscriptionIntervalUnit = 'hour' | 'day' | 'week' | 'month';
+/**
+ * Terms that make a cart line a subscription. One subscription is created per
+ * line when the checkout completes, with `quantity` as seats; at most 10 per
+ * cart. Send `interval`, or `intervalUnit` + `intervalCount` (1 hour to 1
+ * year). `totalPayments` (2-60) makes an installment plan; `trialDays`
+ * (0-365) a free trial, not combinable with `totalPayments`. The line's
+ * `unitPrice` is the per-period price per seat.
+ */
+interface LineRecurringInput {
+    plan: string;
+    planName?: string;
+    interval?: SubscriptionInterval;
+    intervalUnit?: SubscriptionIntervalUnit;
+    intervalCount?: number;
+    totalPayments?: number;
+    trialDays?: number;
+}
+/** A merchant-declared subscription line's stored terms (it carries `plan`). */
+interface StoredLineRecurring {
+    plan: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string;
+    intervalCount: number;
+    totalPayments: number | null;
+    trialDays: number;
+    /** Renewal price per seat. Set only on a free-trial line, whose `unitPrice` is 0. */
+    amount: number | null;
+    /** Display mirror of `totalPayments`. */
+    count: number | null;
+}
+/** The plan line Throttle adds for a checkout session `recurring` intent. */
+interface LegacyLineRecurring {
+    interval: string;
+    intervalUnit?: string | null;
+    intervalCount?: number | null;
+    /** Display metadata: the number of payments to show. Not enforced. */
+    count: number | null;
+}
 interface LineItem {
     id: string;
     cartId: string;
@@ -93,16 +134,13 @@ interface LineItem {
     discountAmount: number;
     total: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Subscription terms. `'plan' in recurring` tells a merchant-declared
+     * subscription line (`StoredLineRecurring`) from the plan line a checkout
+     * session adds (`LegacyLineRecurring`). Null on a one-time line.
      */
-    recurring: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring: StoredLineRecurring | LegacyLineRecurring | null;
+    /** The subscription this line created. Null until the checkout completes. */
+    subscriptionId: string | null;
     imageUrl: string | null;
     position: number;
     metadata: Record<string, unknown>;
@@ -181,16 +219,12 @@ interface AddLineItemInput {
     taxAmount?: number;
     discountAmount?: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Makes this line a subscription: `type` is forced to `subscription`, and it
+     * never ships (`requiresShipping: true` is rejected with it). A free-trial
+     * line is stored with `unitPrice` 0 and your price on `recurring.amount`.
+     * Terms cannot change later: remove the line and add it again.
      */
-    recurring?: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring?: LineRecurringInput;
     imageUrl?: string;
     /**
      * Whether this item is physically shippable. For external/ad-hoc catalogs
@@ -201,6 +235,11 @@ interface AddLineItemInput {
     requiresShipping?: boolean;
     metadata?: Record<string, unknown>;
 }
+/**
+ * On a subscription line only `quantity` (seats) and `metadata` may change;
+ * a different `unitPrice`, `taxAmount` or `discountAmount` is
+ * 422 `recurring_line_immutable`.
+ */
 interface UpdateLineItemInput {
     quantity?: number;
     unitPrice?: number;
@@ -467,8 +506,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.
  *
@@ -483,9 +523,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;
@@ -605,7 +650,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.
@@ -705,4 +750,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, 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 UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineRecurringInput, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

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.10.1",
+  "version": "3.11.1",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run",
+    "test": "tsc --noEmit --strict --skipLibCheck --target es2022 --lib es2022,dom --module esnext --moduleResolution bundler __tests__/recurring-types.check.ts && vitest run",
     "typecheck": "tsc --noEmit"
   }
 }