@usethrottle/cart 3.0.0 → 3.1.0

package/README.md

@@ -18,7 +18,11 @@ 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' });
+const cart = await client.carts.create({
+  storeId: 'store_abc',
+  currency: 'USD',
+  netN: 45,
+});
 
 // 2. Add a line item
 await client.items.add(cart.id, {
@@ -48,8 +52,25 @@ const order = await client.carts.checkout(cart.id, { paymentMethod: 'card' });
 console.log(order.id, order.status);
 ```
 
+`applicationId` is accepted as an alias for `storeId` when your integration
+already uses the newer application naming.
+
 All monetary values are integers in the smallest currency unit (cents for USD).
 
+## Net-N invoice terms
+
+Cart-level invoice terms are optional. Pass `netN` on cart create or update to
+set the cart override, or `null` to clear it. The final invoice term is resolved
+when the buyer completes checkout with Invoice Terms:
+
+```text
+customer.netN ?? cart.netN ?? DEFAULT_NET_N
+```
+
+`allowedMethods` only controls which payment methods can appear in checkout; it
+does not change the Net-N day count. For hosted/embed checkout, create a cart
+with `netN` and then create a checkout session for that cart.
+
 ## Shipping and tax
 
 Use the secret-key client on your backend to calculate and persist cart totals
@@ -74,7 +95,7 @@ External stores can also request read-only storefront quotes with a publishable
 import { StorefrontQuoteClient } from '@usethrottle/cart';
 
 const quotes = new StorefrontQuoteClient({
-  storeId: 'store_uuid',
+  applicationId: 'application_uuid',
   quoteToken: 'pk_publishable_quote_token',
 });
 
@@ -170,14 +191,14 @@ try {
 
 ## 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`). |
+| 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`).            |
 
 ## See also
 
-- [API client (auto-generated): `@usethrottle/api-client`](https://www.npmjs.com/package/@usethrottle/api-client)
+- [Checkout SDK: `@usethrottle/checkout-sdk`](https://www.npmjs.com/package/@usethrottle/checkout-sdk)
 - [React embed components: `@usethrottle/checkout-react`](https://www.npmjs.com/package/@usethrottle/checkout-react)

package/dist/index.cjs

@@ -133,18 +133,19 @@ var CartClient = class {
 
 // src/storefront.ts
 var StorefrontQuoteClient = class {
-  storeId;
+  applicationId;
   quoteToken;
   baseUrl;
   fetchImpl;
   timeoutMs;
   origin;
   constructor(opts) {
-    if (!opts.storeId) throw new Error("StorefrontQuoteClient: storeId is required");
+    const applicationId = opts.applicationId ?? opts.storeId;
+    if (!applicationId) throw new Error("StorefrontQuoteClient: applicationId is required");
     if (!opts.quoteToken?.startsWith("pk_")) {
       throw new Error("StorefrontQuoteClient: quoteToken must be a publishable pk_ token");
     }
-    this.storeId = opts.storeId;
+    this.applicationId = applicationId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
@@ -161,7 +162,7 @@ var StorefrontQuoteClient = class {
         method: "POST",
         headers,
         body: JSON.stringify({
-          storeId: this.storeId,
+          applicationId: this.applicationId,
           quoteToken: this.quoteToken,
           ...input
         }),

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 interface Cart {
     id: string;
     merchantId: string;
+    applicationId: string;
     storeId: string | null;
     customerId: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
@@ -10,6 +11,7 @@ interface Cart {
     discountTotal: number;
     shippingTotal: number;
     total: number;
+    netN: number | null;
     billingAddress: Record<string, unknown> | null;
     shippingAddress: Record<string, unknown> | null;
     notes: string | null;
@@ -86,17 +88,25 @@ interface CartEvent {
     actorId: string | null;
     createdAt: string;
 }
-interface CreateCartInput {
+type CartApplicationRef = {
     storeId: string;
+    applicationId?: string;
+} | {
+    applicationId: string;
+    storeId?: string;
+};
+type CreateCartInput = CartApplicationRef & {
     customerId?: string;
     currency?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
-}
+};
 interface UpdateCartInput {
     customerId?: string;
     billingAddress?: Record<string, unknown>;
     shippingAddress?: Record<string, unknown>;
     notes?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface AddLineItemInput {
@@ -338,7 +348,10 @@ declare class CartClient {
 }
 
 interface StorefrontQuoteClientOptions {
-    storeId: string;
+    /** Current API contract: the application/store UUID that owns the quote config. */
+    applicationId?: string;
+    /** @deprecated Use applicationId. Kept as an alias for older storefronts. */
+    storeId?: string;
     quoteToken: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
@@ -346,7 +359,7 @@ interface StorefrontQuoteClientOptions {
     origin?: string;
 }
 declare class StorefrontQuoteClient {
-    private readonly storeId;
+    private readonly applicationId;
     private readonly quoteToken;
     private readonly baseUrl;
     private readonly fetchImpl;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 interface Cart {
     id: string;
     merchantId: string;
+    applicationId: string;
     storeId: string | null;
     customerId: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
@@ -10,6 +11,7 @@ interface Cart {
     discountTotal: number;
     shippingTotal: number;
     total: number;
+    netN: number | null;
     billingAddress: Record<string, unknown> | null;
     shippingAddress: Record<string, unknown> | null;
     notes: string | null;
@@ -86,17 +88,25 @@ interface CartEvent {
     actorId: string | null;
     createdAt: string;
 }
-interface CreateCartInput {
+type CartApplicationRef = {
     storeId: string;
+    applicationId?: string;
+} | {
+    applicationId: string;
+    storeId?: string;
+};
+type CreateCartInput = CartApplicationRef & {
     customerId?: string;
     currency?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
-}
+};
 interface UpdateCartInput {
     customerId?: string;
     billingAddress?: Record<string, unknown>;
     shippingAddress?: Record<string, unknown>;
     notes?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface AddLineItemInput {
@@ -338,7 +348,10 @@ declare class CartClient {
 }
 
 interface StorefrontQuoteClientOptions {
-    storeId: string;
+    /** Current API contract: the application/store UUID that owns the quote config. */
+    applicationId?: string;
+    /** @deprecated Use applicationId. Kept as an alias for older storefronts. */
+    storeId?: string;
     quoteToken: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
@@ -346,7 +359,7 @@ interface StorefrontQuoteClientOptions {
     origin?: string;
 }
 declare class StorefrontQuoteClient {
-    private readonly storeId;
+    private readonly applicationId;
     private readonly quoteToken;
     private readonly baseUrl;
     private readonly fetchImpl;

package/dist/index.js

@@ -105,18 +105,19 @@ var CartClient = class {
 
 // src/storefront.ts
 var StorefrontQuoteClient = class {
-  storeId;
+  applicationId;
   quoteToken;
   baseUrl;
   fetchImpl;
   timeoutMs;
   origin;
   constructor(opts) {
-    if (!opts.storeId) throw new Error("StorefrontQuoteClient: storeId is required");
+    const applicationId = opts.applicationId ?? opts.storeId;
+    if (!applicationId) throw new Error("StorefrontQuoteClient: applicationId is required");
     if (!opts.quoteToken?.startsWith("pk_")) {
       throw new Error("StorefrontQuoteClient: quoteToken must be a publishable pk_ token");
     }
-    this.storeId = opts.storeId;
+    this.applicationId = applicationId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
@@ -133,7 +134,7 @@ var StorefrontQuoteClient = class {
         method: "POST",
         headers,
         body: JSON.stringify({
-          storeId: this.storeId,
+          applicationId: this.applicationId,
           quoteToken: this.quoteToken,
           ...input
         }),

package/package.json

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