@usethrottle/cart 3.1.0 → 3.3.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.
@@ -19,7 +24,7 @@ const client = new CartClient({ apiKey: process.env.THROTTLE_API_KEY! });
 
 // 1. Create a cart
 const cart = await client.carts.create({
-  storeId: 'store_abc',
+  applicationId: '7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40',
   currency: 'USD',
   netN: 45,
 });
@@ -52,8 +57,8 @@ 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.
+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).
 
@@ -95,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',
 });
 
@@ -123,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: {
@@ -189,6 +194,33 @@ try {
 }
 ```
 
+`ThrottleApiError` extends the shared **`ThrottleError`** from
+[`@usethrottle/errors`](https://www.npmjs.com/package/@usethrottle/errors),
+re-exported here. If you use more than one Throttle SDK you can catch all of
+their errors with a single check — `instanceof ThrottleApiError` keeps working:
+
+```ts
+import { ThrottleError } from '@usethrottle/cart'; // same class across every SDK
+
+try {
+  await cart.items.add(cartId, item);
+  await checkout.completeSession(sessionId, payment);
+} catch (e) {
+  if (e instanceof ThrottleError) {
+    console.error(e.statusCode, e.code, e.message);
+  }
+}
+```
+
+### Line item `imageUrl`
+
+`imageUrl` accepts an absolute `http(s)` URL **or** a relative path like
+`/images/x.png`. Relative paths are resolved to an absolute URL against your
+application's storefront base URL so the image renders on the hosted checkout —
+set it with `PUT /v1/embed-config { "storefrontBaseUrl": "https://yourstore.com" }`
+(the first `allowedOrigin` is used as a fallback). A relative path with no
+resolvable base returns `400 image_url_unresolvable`.
+
 ## Client options
 
 | Option      | Default                       | Description                                                 |

package/dist/index.cjs

@@ -22,25 +22,26 @@ var index_exports = {};
 __export(index_exports, {
   CartClient: () => CartClient,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
-  ThrottleApiError: () => ThrottleApiError
+  ThrottleApiError: () => ThrottleApiError,
+  ThrottleError: () => import_errors2.ThrottleError,
+  isThrottleError: () => import_errors2.isThrottleError
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var ThrottleApiError = class extends Error {
-  code;
-  statusCode;
-  details;
+var import_errors = require("@usethrottle/errors");
+var import_errors2 = require("@usethrottle/errors");
+var ThrottleApiError = class extends import_errors.ThrottleError {
   constructor(args) {
-    super(args.message);
+    super(args);
     this.name = "ThrottleApiError";
-    this.code = args.code;
-    this.statusCode = args.statusCode;
-    this.details = args.details;
   }
 };
 
 // src/client.ts
+function segment(value) {
+  return encodeURIComponent(value);
+}
 var CartClient = class {
   apiKey;
   baseUrl;
@@ -81,40 +82,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 +130,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 +145,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 +166,9 @@ var StorefrontQuoteClient = class {
         method: "POST",
         headers,
         body: JSON.stringify({
+          ...input,
           applicationId: this.applicationId,
-          quoteToken: this.quoteToken,
-          ...input
+          quoteToken: this.quoteToken
         }),
         signal: ctrl.signal
       });
@@ -187,5 +191,7 @@ var StorefrontQuoteClient = class {
 0 && (module.exports = {
   CartClient,
   StorefrontQuoteClient,
-  ThrottleApiError
+  ThrottleApiError,
+  ThrottleError,
+  isThrottleError
 });

package/dist/index.d.cts

@@ -1,8 +1,10 @@
+import { ThrottleError } from '@usethrottle/errors';
+export { ThrottleError, isThrottleError } from '@usethrottle/errors';
+
 interface Cart {
     id: string;
-    merchantId: string;
+    workspaceId: string;
     applicationId: string;
-    storeId: string | null;
     customerId: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
     currency: string;
@@ -88,19 +90,13 @@ interface CartEvent {
     actorId: string | null;
     createdAt: string;
 }
-type CartApplicationRef = {
-    storeId: string;
-    applicationId?: string;
-} | {
+interface CreateCartInput {
     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>;
@@ -224,8 +220,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;
@@ -287,7 +283,7 @@ interface ShippingTaxCalculationResponse {
     }>;
 }
 interface ExternalShippingTaxSnapshotInput {
-    storeId: string;
+    applicationId: string;
     cartId?: string | null;
     checkoutSessionId?: string | null;
     orderId?: string | null;
@@ -348,10 +344,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;
@@ -369,9 +362,14 @@ declare class StorefrontQuoteClient {
     quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
 }
 
-declare class ThrottleApiError extends Error {
-    readonly code: string;
-    readonly statusCode: number;
+/**
+ * Thrown on a non-2xx response from the Throttle Cart API.
+ *
+ * Extends the shared {@link ThrottleError} so a single
+ * `catch (e) { if (e instanceof ThrottleError) … }` covers errors from every
+ * Throttle SDK. `instanceof ThrottleApiError` keeps working for existing code.
+ */
+declare class ThrottleApiError extends ThrottleError {
     readonly details?: Record<string, unknown>;
     constructor(args: {
         code: string;

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+import { ThrottleError } from '@usethrottle/errors';
+export { ThrottleError, isThrottleError } from '@usethrottle/errors';
+
 interface Cart {
     id: string;
-    merchantId: string;
+    workspaceId: string;
     applicationId: string;
-    storeId: string | null;
     customerId: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
     currency: string;
@@ -88,19 +90,13 @@ interface CartEvent {
     actorId: string | null;
     createdAt: string;
 }
-type CartApplicationRef = {
-    storeId: string;
-    applicationId?: string;
-} | {
+interface CreateCartInput {
     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>;
@@ -224,8 +220,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;
@@ -287,7 +283,7 @@ interface ShippingTaxCalculationResponse {
     }>;
 }
 interface ExternalShippingTaxSnapshotInput {
-    storeId: string;
+    applicationId: string;
     cartId?: string | null;
     checkoutSessionId?: string | null;
     orderId?: string | null;
@@ -348,10 +344,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;
@@ -369,9 +362,14 @@ declare class StorefrontQuoteClient {
     quote(input: ShippingTaxQuoteInput): Promise<ShippingTaxCalculationResponse>;
 }
 
-declare class ThrottleApiError extends Error {
-    readonly code: string;
-    readonly statusCode: number;
+/**
+ * Thrown on a non-2xx response from the Throttle Cart API.
+ *
+ * Extends the shared {@link ThrottleError} so a single
+ * `catch (e) { if (e instanceof ThrottleError) … }` covers errors from every
+ * Throttle SDK. `instanceof ThrottleApiError` keeps working for existing code.
+ */
+declare class ThrottleApiError extends ThrottleError {
     readonly details?: Record<string, unknown>;
     constructor(args: {
         code: string;

package/dist/index.js

@@ -1,18 +1,17 @@
 // src/errors.ts
-var ThrottleApiError = class extends Error {
-  code;
-  statusCode;
-  details;
+import { ThrottleError } from "@usethrottle/errors";
+import { ThrottleError as ThrottleError2, isThrottleError } from "@usethrottle/errors";
+var ThrottleApiError = class extends ThrottleError {
   constructor(args) {
-    super(args.message);
+    super(args);
     this.name = "ThrottleApiError";
-    this.code = args.code;
-    this.statusCode = args.statusCode;
-    this.details = args.details;
   }
 };
 
 // src/client.ts
+function segment(value) {
+  return encodeURIComponent(value);
+}
 var CartClient = class {
   apiKey;
   baseUrl;
@@ -53,40 +52,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 +100,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 +115,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 +136,9 @@ var StorefrontQuoteClient = class {
         method: "POST",
         headers,
         body: JSON.stringify({
+          ...input,
           applicationId: this.applicationId,
-          quoteToken: this.quoteToken,
-          ...input
+          quoteToken: this.quoteToken
         }),
         signal: ctrl.signal
       });
@@ -158,5 +160,7 @@ var StorefrontQuoteClient = class {
 export {
   CartClient,
   StorefrontQuoteClient,
-  ThrottleApiError
+  ThrottleApiError,
+  ThrottleError2 as ThrottleError,
+  isThrottleError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/cart",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,6 +17,9 @@
     "dist",
     "README.md"
   ],
+  "dependencies": {
+    "@usethrottle/errors": "^1.0.0"
+  },
   "devDependencies": {
     "tsup": "^8.0.0",
     "vitest": "^2.1.9",