@usethrottle/cart 3.0.1 → 3.2.0

package/README.md

@@ -1,3 +1,8 @@
+<p align="left">
+  <img src="https://raw.githubusercontent.com/Epic-Design-Labs/app-throttle/main/packages/brand/assets/throttle-logo.png" alt="Throttle" height="56" />
+</p>
+
+
 # @usethrottle/cart
 
 Typed Node.js REST client for the Throttle Cart API.
@@ -18,7 +23,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({
+  applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
+  currency: 'USD',
+  netN: 45,
+});
 
 // 2. Add a line item
 await client.items.add(cart.id, {
@@ -48,8 +57,25 @@ const order = await client.carts.checkout(cart.id, { paymentMethod: 'card' });
 console.log(order.id, order.status);
 ```
 
+Use applicationId for every public request body. Deprecated store identifiers
+are rejected by the API.
+
 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 +100,7 @@ External stores can also request read-only storefront quotes with a publishable
 import { StorefrontQuoteClient } from '@usethrottle/cart';
 
 const quotes = new StorefrontQuoteClient({
-  applicationId: 'application_uuid',
+  applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
   quoteToken: 'pk_publishable_quote_token',
 });
 
@@ -102,7 +128,7 @@ when at least one axis is in `byo` mode:
 
 ```ts
 await client.shippingTax.pushExternalSnapshot({
-  storeId: 'store_uuid',
+  applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
   cartId: cart.id,
   currency: 'USD',
   totals: {

package/dist/index.cjs

@@ -41,6 +41,9 @@ var ThrottleApiError = class extends Error {
 };
 
 // src/client.ts
+function segment(value) {
+  return encodeURIComponent(value);
+}
 var CartClient = class {
   apiKey;
   baseUrl;
@@ -81,40 +84,44 @@ var CartClient = class {
   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: (id) => this.request("GET", `/api/v1/carts/${segment(id)}`),
+      update: (id, input) => this.request("PATCH", `/api/v1/carts/${segment(id)}`, input),
+      checkout: (id, input) => this.request("POST", `/api/v1/carts/${segment(id)}/checkout`, input ?? {}),
+      merge: (id, customerId) => this.request("POST", `/api/v1/carts/${segment(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}`)
+      add: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, input),
+      update: (cartId, itemId, input) => this.request("PATCH", `/api/v1/carts/${segment(cartId)}/items/${segment(itemId)}`, input),
+      remove: (cartId, itemId) => this.request("DELETE", `/api/v1/carts/${segment(cartId)}/items/${segment(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`)
+      select: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/shipping`, input),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${segment(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`)
+      apply: (cartId, code) => this.request("POST", `/api/v1/carts/${segment(cartId)}/apply-discount`, { code }),
+      remove: (cartId) => this.request("DELETE", `/api/v1/carts/${segment(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`)
+      set: (cartId, lines) => this.request("PUT", `/api/v1/carts/${segment(cartId)}/tax-lines`, { lines }),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${segment(cartId)}/tax-lines`)
     };
   }
   get shippingTax() {
     return {
-      calculateCart: (cartId, input = {}) => this.request("POST", `/api/v1/shipping-tax/carts/${cartId}/calculate`, input),
+      calculateCart: (cartId, input = {}) => this.request(
+        "POST",
+        `/api/v1/shipping-tax/carts/${segment(cartId)}/calculate`,
+        input
+      ),
       pushExternalSnapshot: (input) => this.request("POST", "/api/v1/shipping-tax/external-snapshots", input)
     };
   }
@@ -125,7 +132,7 @@ var CartClient = class {
         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 : ""}`);
+        return this.request("GET", `/api/v1/carts/${segment(cartId)}/events${qs ? "?" + qs : ""}`);
       }
     };
   }
@@ -140,12 +147,11 @@ var StorefrontQuoteClient = class {
   timeoutMs;
   origin;
   constructor(opts) {
-    const applicationId = opts.applicationId ?? opts.storeId;
-    if (!applicationId) throw new Error("StorefrontQuoteClient: applicationId is required");
+    if (!opts.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.applicationId = applicationId;
+    this.applicationId = opts.applicationId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
@@ -162,9 +168,9 @@ var StorefrontQuoteClient = class {
         method: "POST",
         headers,
         body: JSON.stringify({
+          ...input,
           applicationId: this.applicationId,
-          quoteToken: this.quoteToken,
-          ...input
+          quoteToken: this.quoteToken
         }),
         signal: ctrl.signal
       });

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 interface Cart {
     id: string;
-    merchantId: string;
-    storeId: string | null;
+    workspaceId: string;
+    applicationId: string;
     customerId: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
     currency: string;
@@ -10,6 +10,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;
@@ -87,9 +88,10 @@ interface CartEvent {
     createdAt: string;
 }
 interface CreateCartInput {
-    storeId: string;
+    applicationId: string;
     customerId?: string;
     currency?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface UpdateCartInput {
@@ -97,6 +99,7 @@ interface UpdateCartInput {
     billingAddress?: Record<string, unknown>;
     shippingAddress?: Record<string, unknown>;
     notes?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface AddLineItemInput {
@@ -214,8 +217,8 @@ interface ShippingTaxCalculationResponse {
     kind: 'quote' | 'cart_estimate' | 'checkout_final' | 'external_snapshot';
     status: 'estimated' | 'final' | 'failed';
     source: 'off' | 'byo' | 'calculated' | 'app_based' | 'external_push';
-    storeId: string;
-    merchantId?: string;
+    applicationId: string;
+    workspaceId?: string;
     currency: string;
     configId?: string;
     configVersion?: number;
@@ -277,7 +280,7 @@ interface ShippingTaxCalculationResponse {
     }>;
 }
 interface ExternalShippingTaxSnapshotInput {
-    storeId: string;
+    applicationId: string;
     cartId?: string | null;
     checkoutSessionId?: string | null;
     orderId?: string | null;
@@ -338,10 +341,7 @@ declare class CartClient {
 }
 
 interface StorefrontQuoteClientOptions {
-    /** 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;
+    applicationId: string;
     quoteToken: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 interface Cart {
     id: string;
-    merchantId: string;
-    storeId: string | null;
+    workspaceId: string;
+    applicationId: string;
     customerId: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
     currency: string;
@@ -10,6 +10,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;
@@ -87,9 +88,10 @@ interface CartEvent {
     createdAt: string;
 }
 interface CreateCartInput {
-    storeId: string;
+    applicationId: string;
     customerId?: string;
     currency?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface UpdateCartInput {
@@ -97,6 +99,7 @@ interface UpdateCartInput {
     billingAddress?: Record<string, unknown>;
     shippingAddress?: Record<string, unknown>;
     notes?: string;
+    netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface AddLineItemInput {
@@ -214,8 +217,8 @@ interface ShippingTaxCalculationResponse {
     kind: 'quote' | 'cart_estimate' | 'checkout_final' | 'external_snapshot';
     status: 'estimated' | 'final' | 'failed';
     source: 'off' | 'byo' | 'calculated' | 'app_based' | 'external_push';
-    storeId: string;
-    merchantId?: string;
+    applicationId: string;
+    workspaceId?: string;
     currency: string;
     configId?: string;
     configVersion?: number;
@@ -277,7 +280,7 @@ interface ShippingTaxCalculationResponse {
     }>;
 }
 interface ExternalShippingTaxSnapshotInput {
-    storeId: string;
+    applicationId: string;
     cartId?: string | null;
     checkoutSessionId?: string | null;
     orderId?: string | null;
@@ -338,10 +341,7 @@ declare class CartClient {
 }
 
 interface StorefrontQuoteClientOptions {
-    /** 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;
+    applicationId: string;
     quoteToken: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;

package/dist/index.js

@@ -13,6 +13,9 @@ var ThrottleApiError = class extends Error {
 };
 
 // src/client.ts
+function segment(value) {
+  return encodeURIComponent(value);
+}
 var CartClient = class {
   apiKey;
   baseUrl;
@@ -53,40 +56,44 @@ var CartClient = class {
   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: (id) => this.request("GET", `/api/v1/carts/${segment(id)}`),
+      update: (id, input) => this.request("PATCH", `/api/v1/carts/${segment(id)}`, input),
+      checkout: (id, input) => this.request("POST", `/api/v1/carts/${segment(id)}/checkout`, input ?? {}),
+      merge: (id, customerId) => this.request("POST", `/api/v1/carts/${segment(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}`)
+      add: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, input),
+      update: (cartId, itemId, input) => this.request("PATCH", `/api/v1/carts/${segment(cartId)}/items/${segment(itemId)}`, input),
+      remove: (cartId, itemId) => this.request("DELETE", `/api/v1/carts/${segment(cartId)}/items/${segment(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`)
+      select: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/shipping`, input),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${segment(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`)
+      apply: (cartId, code) => this.request("POST", `/api/v1/carts/${segment(cartId)}/apply-discount`, { code }),
+      remove: (cartId) => this.request("DELETE", `/api/v1/carts/${segment(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`)
+      set: (cartId, lines) => this.request("PUT", `/api/v1/carts/${segment(cartId)}/tax-lines`, { lines }),
+      clear: (cartId) => this.request("DELETE", `/api/v1/carts/${segment(cartId)}/tax-lines`)
     };
   }
   get shippingTax() {
     return {
-      calculateCart: (cartId, input = {}) => this.request("POST", `/api/v1/shipping-tax/carts/${cartId}/calculate`, input),
+      calculateCart: (cartId, input = {}) => this.request(
+        "POST",
+        `/api/v1/shipping-tax/carts/${segment(cartId)}/calculate`,
+        input
+      ),
       pushExternalSnapshot: (input) => this.request("POST", "/api/v1/shipping-tax/external-snapshots", input)
     };
   }
@@ -97,7 +104,7 @@ var CartClient = class {
         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 : ""}`);
+        return this.request("GET", `/api/v1/carts/${segment(cartId)}/events${qs ? "?" + qs : ""}`);
       }
     };
   }
@@ -112,12 +119,11 @@ var StorefrontQuoteClient = class {
   timeoutMs;
   origin;
   constructor(opts) {
-    const applicationId = opts.applicationId ?? opts.storeId;
-    if (!applicationId) throw new Error("StorefrontQuoteClient: applicationId is required");
+    if (!opts.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.applicationId = applicationId;
+    this.applicationId = opts.applicationId;
     this.quoteToken = opts.quoteToken;
     this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
@@ -134,9 +140,9 @@ var StorefrontQuoteClient = class {
         method: "POST",
         headers,
         body: JSON.stringify({
+          ...input,
           applicationId: this.applicationId,
-          quoteToken: this.quoteToken,
-          ...input
+          quoteToken: this.quoteToken
         }),
         signal: ctrl.signal
       });

package/package.json

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