@usethrottle/cart 3.5.0 → 3.7.0

package/dist/index.cjs

@@ -21,10 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CartClient: () => CartClient,
+  CartNotFoundError: () => CartNotFoundError,
+  CartNotOpenError: () => CartNotOpenError,
   CartSessionClient: () => CartSessionClient,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
   ThrottleApiError: () => ThrottleApiError,
   ThrottleError: () => import_errors2.ThrottleError,
+  cartErrorFromResponse: () => cartErrorFromResponse,
   isThrottleError: () => import_errors2.isThrottleError
 });
 module.exports = __toCommonJS(index_exports);
@@ -38,6 +41,27 @@ var ThrottleApiError = class extends import_errors.ThrottleError {
     this.name = "ThrottleApiError";
   }
 };
+var CartNotOpenError = class extends ThrottleApiError {
+  constructor(args) {
+    super({ code: "cart_not_open", statusCode: args.statusCode ?? 409, message: args.message, details: args.details });
+    this.name = "CartNotOpenError";
+  }
+};
+var CartNotFoundError = class extends ThrottleApiError {
+  constructor(args) {
+    super({ code: "cart_not_found", statusCode: args.statusCode ?? 404, message: args.message, details: args.details });
+    this.name = "CartNotFoundError";
+  }
+};
+function cartErrorFromResponse(args) {
+  if (args.statusCode === 409 && args.code === "cart_not_open") {
+    return new CartNotOpenError({ message: args.message, statusCode: args.statusCode, details: args.details });
+  }
+  if (args.statusCode === 404 && (args.code === "cart_not_found" || args.code === "not_found")) {
+    return new CartNotFoundError({ message: args.message, statusCode: args.statusCode, details: args.details });
+  }
+  return new ThrottleApiError(args);
+}
 
 // src/client.ts
 function segment(value) {
@@ -68,7 +92,7 @@ var CartClient = class {
       });
       const json = await res.json().catch(() => ({}));
       if (!res.ok) {
-        throw new ThrottleApiError({
+        throw cartErrorFromResponse({
           code: json?.error?.code ?? "unknown_error",
           message: json?.error?.message ?? `HTTP ${res.status}`,
           statusCode: res.status,
@@ -282,7 +306,7 @@ var CartSessionClient = class {
       });
       const json = await res.json().catch(() => ({}));
       if (!res.ok) {
-        throw new ThrottleApiError({
+        throw cartErrorFromResponse({
           code: json?.error?.code ?? "unknown_error",
           message: json?.error?.message ?? `HTTP ${res.status}`,
           statusCode: res.status,
@@ -298,9 +322,12 @@ var CartSessionClient = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CartClient,
+  CartNotFoundError,
+  CartNotOpenError,
   CartSessionClient,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError,
+  cartErrorFromResponse,
   isThrottleError
 });

package/dist/index.d.cts

@@ -1,11 +1,33 @@
 import { ThrottleError } from '@usethrottle/errors';
 export { ThrottleError, isThrottleError } from '@usethrottle/errors';
 
+/**
+ * Canonical address shape used everywhere the Cart API accepts or returns an
+ * address. Required fields (`addressLine1`, `city`, `countryCode`) are validated
+ * at write time — sending non-canonical keys (`line1`, `state`, `country`, …) is
+ * rejected with a did-you-mean hint instead of silently stored and failing later
+ * at checkout. Field names match {@link ShippingTaxAddress}.
+ */
+interface CartAddress {
+    firstName?: string;
+    lastName?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    stateProvince?: string;
+    postalCode?: string;
+    /** ISO-3166-1 alpha-2 country code, e.g. "US". */
+    countryCode: string;
+    phone?: string;
+    email?: string;
+}
 interface Cart {
     id: string;
     workspaceId: string;
     applicationId: string;
     customerId: string | null;
+    /** Lightweight captured email (no full customer record), or null. */
+    customerEmail: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
     currency: string;
     subtotal: number;
@@ -14,8 +36,8 @@ interface Cart {
     shippingTotal: number;
     total: number;
     netN: number | null;
-    billingAddress: Record<string, unknown> | null;
-    shippingAddress: Record<string, unknown> | null;
+    billingAddress: CartAddress | null;
+    shippingAddress: CartAddress | null;
     notes: string | null;
     expiresAt: string | null;
     externalRef?: {
@@ -93,14 +115,18 @@ interface CartEvent {
 interface CreateCartInput {
     applicationId: string;
     customerId?: string;
+    /** Optional lightweight email capture (no full customer record required). */
+    customerEmail?: string;
     currency?: string;
     netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface UpdateCartInput {
     customerId?: string;
-    billingAddress?: Record<string, unknown>;
-    shippingAddress?: Record<string, unknown>;
+    /** Lightweight email capture; `null` clears a previously-set value. */
+    customerEmail?: string | null;
+    billingAddress?: CartAddress;
+    shippingAddress?: CartAddress;
     notes?: string;
     netN?: number | null;
     metadata?: Record<string, unknown>;
@@ -480,5 +506,43 @@ declare class ThrottleApiError extends ThrottleError {
         details?: Record<string, unknown>;
     });
 }
+/**
+ * Thrown when an operation targets a cart that is no longer `open` (HTTP 409,
+ * `cart_not_open`). A cart leaves `open` when it is converted by a completed
+ * order (terminal — start a new cart) or abandoned. Catch this to branch on a
+ * stale cart and rebuild from the last-known line items instead of sniffing
+ * `error.code`.
+ *
+ * Subclass of {@link ThrottleApiError} (and therefore {@link ThrottleError}), so
+ * existing `instanceof ThrottleApiError` / `.code` checks keep working.
+ */
+declare class CartNotOpenError extends ThrottleApiError {
+    constructor(args: {
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Thrown when a cart cannot be found for the request's environment (HTTP 404).
+ * Subclass of {@link ThrottleApiError}.
+ */
+declare class CartNotFoundError extends ThrottleApiError {
+    constructor(args: {
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Map a raw API error envelope to the most specific Cart SDK error class.
+ * Falls back to {@link ThrottleApiError} for everything unrecognised.
+ */
+declare function cartErrorFromResponse(args: {
+    code: string;
+    message: string;
+    statusCode: number;
+    details?: Record<string, unknown>;
+}): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, type CartSession, CartSessionClient, type CartSessionClientOptions, 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 UpdateLineItemInput };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, CartSessionClient, type CartSessionClientOptions, 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 UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.d.ts

@@ -1,11 +1,33 @@
 import { ThrottleError } from '@usethrottle/errors';
 export { ThrottleError, isThrottleError } from '@usethrottle/errors';
 
+/**
+ * Canonical address shape used everywhere the Cart API accepts or returns an
+ * address. Required fields (`addressLine1`, `city`, `countryCode`) are validated
+ * at write time — sending non-canonical keys (`line1`, `state`, `country`, …) is
+ * rejected with a did-you-mean hint instead of silently stored and failing later
+ * at checkout. Field names match {@link ShippingTaxAddress}.
+ */
+interface CartAddress {
+    firstName?: string;
+    lastName?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    stateProvince?: string;
+    postalCode?: string;
+    /** ISO-3166-1 alpha-2 country code, e.g. "US". */
+    countryCode: string;
+    phone?: string;
+    email?: string;
+}
 interface Cart {
     id: string;
     workspaceId: string;
     applicationId: string;
     customerId: string | null;
+    /** Lightweight captured email (no full customer record), or null. */
+    customerEmail: string | null;
     status: 'open' | 'checkout' | 'converted' | 'abandoned';
     currency: string;
     subtotal: number;
@@ -14,8 +36,8 @@ interface Cart {
     shippingTotal: number;
     total: number;
     netN: number | null;
-    billingAddress: Record<string, unknown> | null;
-    shippingAddress: Record<string, unknown> | null;
+    billingAddress: CartAddress | null;
+    shippingAddress: CartAddress | null;
     notes: string | null;
     expiresAt: string | null;
     externalRef?: {
@@ -93,14 +115,18 @@ interface CartEvent {
 interface CreateCartInput {
     applicationId: string;
     customerId?: string;
+    /** Optional lightweight email capture (no full customer record required). */
+    customerEmail?: string;
     currency?: string;
     netN?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface UpdateCartInput {
     customerId?: string;
-    billingAddress?: Record<string, unknown>;
-    shippingAddress?: Record<string, unknown>;
+    /** Lightweight email capture; `null` clears a previously-set value. */
+    customerEmail?: string | null;
+    billingAddress?: CartAddress;
+    shippingAddress?: CartAddress;
     notes?: string;
     netN?: number | null;
     metadata?: Record<string, unknown>;
@@ -480,5 +506,43 @@ declare class ThrottleApiError extends ThrottleError {
         details?: Record<string, unknown>;
     });
 }
+/**
+ * Thrown when an operation targets a cart that is no longer `open` (HTTP 409,
+ * `cart_not_open`). A cart leaves `open` when it is converted by a completed
+ * order (terminal — start a new cart) or abandoned. Catch this to branch on a
+ * stale cart and rebuild from the last-known line items instead of sniffing
+ * `error.code`.
+ *
+ * Subclass of {@link ThrottleApiError} (and therefore {@link ThrottleError}), so
+ * existing `instanceof ThrottleApiError` / `.code` checks keep working.
+ */
+declare class CartNotOpenError extends ThrottleApiError {
+    constructor(args: {
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Thrown when a cart cannot be found for the request's environment (HTTP 404).
+ * Subclass of {@link ThrottleApiError}.
+ */
+declare class CartNotFoundError extends ThrottleApiError {
+    constructor(args: {
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Map a raw API error envelope to the most specific Cart SDK error class.
+ * Falls back to {@link ThrottleApiError} for everything unrecognised.
+ */
+declare function cartErrorFromResponse(args: {
+    code: string;
+    message: string;
+    statusCode: number;
+    details?: Record<string, unknown>;
+}): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, CartClient, type CartEvent, type CartSession, CartSessionClient, type CartSessionClientOptions, 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 UpdateLineItemInput };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, CartSessionClient, type CartSessionClientOptions, 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 UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.js

@@ -7,6 +7,27 @@ var ThrottleApiError = class extends ThrottleError {
     this.name = "ThrottleApiError";
   }
 };
+var CartNotOpenError = class extends ThrottleApiError {
+  constructor(args) {
+    super({ code: "cart_not_open", statusCode: args.statusCode ?? 409, message: args.message, details: args.details });
+    this.name = "CartNotOpenError";
+  }
+};
+var CartNotFoundError = class extends ThrottleApiError {
+  constructor(args) {
+    super({ code: "cart_not_found", statusCode: args.statusCode ?? 404, message: args.message, details: args.details });
+    this.name = "CartNotFoundError";
+  }
+};
+function cartErrorFromResponse(args) {
+  if (args.statusCode === 409 && args.code === "cart_not_open") {
+    return new CartNotOpenError({ message: args.message, statusCode: args.statusCode, details: args.details });
+  }
+  if (args.statusCode === 404 && (args.code === "cart_not_found" || args.code === "not_found")) {
+    return new CartNotFoundError({ message: args.message, statusCode: args.statusCode, details: args.details });
+  }
+  return new ThrottleApiError(args);
+}
 
 // src/client.ts
 function segment(value) {
@@ -37,7 +58,7 @@ var CartClient = class {
       });
       const json = await res.json().catch(() => ({}));
       if (!res.ok) {
-        throw new ThrottleApiError({
+        throw cartErrorFromResponse({
           code: json?.error?.code ?? "unknown_error",
           message: json?.error?.message ?? `HTTP ${res.status}`,
           statusCode: res.status,
@@ -251,7 +272,7 @@ var CartSessionClient = class {
       });
       const json = await res.json().catch(() => ({}));
       if (!res.ok) {
-        throw new ThrottleApiError({
+        throw cartErrorFromResponse({
           code: json?.error?.code ?? "unknown_error",
           message: json?.error?.message ?? `HTTP ${res.status}`,
           statusCode: res.status,
@@ -266,9 +287,12 @@ var CartSessionClient = class {
 };
 export {
   CartClient,
+  CartNotFoundError,
+  CartNotOpenError,
   CartSessionClient,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError2 as ThrottleError,
+  cartErrorFromResponse,
   isThrottleError
 };

package/package.json

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