@usethrottle/cart 3.11.1 → 3.13.0

package/README.md

@@ -144,6 +144,127 @@ button — checkout still works. Omitting `returnUrl` or `cancelUrl` falls back
 to Throttle's own `/complete` page and this same hosted cart page,
 respectively.
 
+### Resolved carts
+
+A resolved cart's lines are priced by an installed app (a line resolver, such
+as Product Catalog), never by the browser. Create the session with
+`lineResolver` and the environment's `currency`, then add lines by
+`referenceId`. Throttle asks the app for the price, stock and limits on every
+add, quantity change, sign-in merge and checkout.
+
+```ts
+import {
+  QuantityUnavailableError,
+  LineNotPurchasableError,
+  LineResolverUnavailableError,
+  CartPricesChangedError,
+} from '@usethrottle/cart';
+
+await cart.create({
+  currency: 'USD', // required with lineResolver; must be the environment's currency
+  lineResolver: { extensionId: '0b6a3c1e-8d2f-4a5b-9c7d-1e2f3a4b5c6d' },
+  locale: 'en-US', // optional, passed to the app
+});
+
+try {
+  await cart.addResolvedItem({ referenceId: 'TSHIRT-BLUE-M', quantity: 2 });
+} catch (e) {
+  if (e instanceof QuantityUnavailableError) showMessage(`Only ${e.maxQuantity ?? 0} available`);
+  else if (e instanceof LineNotPurchasableError) showMessage('No longer available');
+  else if (e instanceof LineResolverUnavailableError) showMessage('Try again in a moment');
+  else throw e;
+}
+
+// Re-check every owned line (for example when the buyer comes back to the cart).
+const { changed, ...current } = await cart.refresh();
+
+try {
+  const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
+  location.href = checkoutUrl;
+} catch (e) {
+  if (e instanceof CartPricesChangedError) {
+    // The new prices are already applied; show them, then check out again.
+    if (e.cart) render(e.cart);
+  } else throw e;
+}
+```
+
+`addResolvedItem()` sends only `referenceId`, `quantity` (default 1) and
+`metadata`. The app sets the name, price and image: sending `unitPrice`,
+`name`, `imageUrl`, `taxAmount`, `discountAmount`, a reserved metadata key
+(`lineResolver`, `requiresShipping`) or a metadata key that changes a shipping
+or tax quote answers `400 price_locked` (`PriceLockedError.fields` names them).
+`updateItem()` keeps working for quantity and other metadata; a quantity change
+is re-checked by the app.
+
+A resolved cart carries `lineResolver: { extensionId }` (`extensionId` is
+`null` if the app's installation is gone), and each line carries `resolution`:
+`null` on a line the app does not own, otherwise `{ status, code, maxQuantity,
+minQuantity }`. `status` is `resolved`, `refused` (the app refused the line;
+`code` says why, for example `OUT_OF_STOCK`) or `stale` (the last re-check
+failed; checkout re-checks it). Carts created without `lineResolver` have
+neither key.
+
+Shipping on a resolved cart is priced by Throttle, not the browser: pick a
+method Throttle quotes for the cart with
+`cart.selectShippingMethod({ methodId })`, which sends only the method id (the
+cart needs a shipping address first). A method Throttle does not quote answers
+`422 shipping_method_unavailable`. If you use `selectShipping()` instead, a
+`rateAmount` or `currency` different from the quote answers `400
+price_locked`. There is no flat-rate fallback (no selection means shipping
+is not calculated yet). The checkout hand-off re-checks every line and
+re-quotes shipping; any change answers `409 cart_prices_changed` with the
+updated `cart` and, when shipping moved, `shipping: { methodId,
+previousAmount, amount, reason? }` (`amount` is `null` with `reason`
+`method_unavailable` or `quote_unavailable`).
+
+#### From your server (`CartClient`)
+
+Other apps can integrate the same way with a secret key. Create the cart with
+`lineResolver` (and the environment's `currency`), optionally pricing up to 50
+lines in one call with `lineItems` (all or nothing), then add lines by
+`referenceId`:
+
+```ts
+const cart = await client.carts.create({
+  applicationId,
+  currency: 'USD',
+  lineResolver: { extensionId: '0b6a3c1e-8d2f-4a5b-9c7d-1e2f3a4b5c6d' },
+  locale: 'en-GB',
+  lineItems: [{ referenceId: 'TSHIRT-BLUE-M', quantity: 2 }],
+});
+const line = await client.items.addResolvedItem(cart.id, { referenceId: 'MUG-WHITE', quantity: 1 });
+```
+
+A server cart has no refresh: `refresh()` exists only on a browser cart
+session (`CartSessionClient`). From the server, a line is re-checked with the
+app when you change its quantity with `items.update(cartId, itemId,
+{ quantity })`. To re-check the whole cart, mint a hosted-cart session for it
+(`POST /api/v1/carts/{id}/sessions`, which answers `{ sessionId, cartUrl,
+expiresAt }`) and call `CartSessionClient.forSession(sessionId).refresh()`. An
+owned line's `unitPrice`, `taxAmount`, `discountAmount` and reserved metadata
+keys answer `400 price_locked` for every caller. Both clients throw the same
+typed errors:
+
+| Error class | Status / code | Typed fields (`details`) |
+| --- | --- | --- |
+| `PriceLockedError` | `400 price_locked` | `fields` |
+| `QuantityUnavailableError` | `409 quantity_unavailable` | `reason`, `maxQuantity` (or `null`) |
+| `LineNotPurchasableError` | `422 line_not_purchasable` | `reason` on an add; `lines` at checkout |
+| `LineResolverUnavailableError` | `503 line_resolver_unavailable` | `reason` (or `null`); nothing changed, retry |
+| `LineResolverNotAvailableError` | `422 line_resolver_not_available` | `reason`; the app is not installed |
+| `CurrencyNotEnabledError` | `422 currency_not_enabled` | `details.currency`, `details.enabledCurrencies` |
+| `ResolvedLinesRequiredError` | `422 resolved_lines_required` | the store only accepts resolved lines |
+| `LineLimitReachedError` | `422 line_limit_reached` | `details.maxLines` (50 per app) |
+| `CartPricesChangedError` | `409 cart_prices_changed` | `cart`, `shipping` (or `null`) |
+| `ShippingMethodUnavailableError` | `422 shipping_method_unavailable` | |
+| `ShippingQuoteUnavailableError` | `503 shipping_quote_unavailable` | nothing changed, retry |
+| `AmountTooLargeError` | `422 amount_too_large` | lower the quantity |
+| `CartChangedError` | `409 cart_changed` | the cart changed during the add; retry |
+
+Every class extends `ThrottleApiError` (and so `ThrottleError`), so existing
+`instanceof ThrottleApiError` and `e.code` checks keep working.
+
 ## Net-N invoice terms
 
 Cart-level invoice terms are optional. Pass `netN` on cart create or update to

package/dist/index.cjs

@@ -20,11 +20,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AmountTooLargeError: () => AmountTooLargeError,
+  CartChangedError: () => CartChangedError,
   CartClient: () => CartClient,
   CartNotFoundError: () => CartNotFoundError,
   CartNotOpenError: () => CartNotOpenError,
+  CartPricesChangedError: () => CartPricesChangedError,
   CartSessionClient: () => CartSessionClient,
   CartTimeoutError: () => CartTimeoutError,
+  CurrencyNotEnabledError: () => CurrencyNotEnabledError,
+  LineLimitReachedError: () => LineLimitReachedError,
+  LineNotPurchasableError: () => LineNotPurchasableError,
+  LineResolverNotAvailableError: () => LineResolverNotAvailableError,
+  LineResolverUnavailableError: () => LineResolverUnavailableError,
+  PriceLockedError: () => PriceLockedError,
+  QuantityUnavailableError: () => QuantityUnavailableError,
+  ResolvedLinesRequiredError: () => ResolvedLinesRequiredError,
+  ShippingMethodUnavailableError: () => ShippingMethodUnavailableError,
+  ShippingQuoteUnavailableError: () => ShippingQuoteUnavailableError,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
   ThrottleApiError: () => ThrottleApiError,
   ThrottleError: () => import_errors2.ThrottleError,
@@ -77,6 +90,130 @@ var CartTimeoutError = class extends import_errors.ThrottleError {
     this.name = "CartTimeoutError";
   }
 };
+function coded(code, statusCode, args) {
+  return {
+    code,
+    statusCode: args.statusCode ?? statusCode,
+    message: args.message,
+    details: args.details,
+    responseHeaders: args.responseHeaders
+  };
+}
+var str = (v) => typeof v === "string" ? v : null;
+var num = (v) => typeof v === "number" ? v : null;
+var PriceLockedError = class extends ThrottleApiError {
+  /** The refused fields, e.g. `['unitPrice', 'metadata.lineResolver']`. */
+  fields;
+  constructor(args) {
+    super(coded("price_locked", 400, args));
+    this.name = "PriceLockedError";
+    this.fields = Array.isArray(args.details?.fields) ? args.details.fields : [];
+  }
+};
+var QuantityUnavailableError = class extends ThrottleApiError {
+  reason;
+  maxQuantity;
+  constructor(args) {
+    super(coded("quantity_unavailable", 409, args));
+    this.name = "QuantityUnavailableError";
+    this.reason = str(args.details?.reason);
+    this.maxQuantity = num(args.details?.maxQuantity);
+  }
+};
+var LineNotPurchasableError = class extends ThrottleApiError {
+  reason;
+  lines;
+  constructor(args) {
+    super(coded("line_not_purchasable", 422, args));
+    this.name = "LineNotPurchasableError";
+    this.reason = str(args.details?.reason);
+    this.lines = Array.isArray(args.details?.lines) ? args.details.lines : null;
+  }
+};
+var LineResolverUnavailableError = class extends ThrottleApiError {
+  reason;
+  constructor(args) {
+    super(coded("line_resolver_unavailable", 503, args));
+    this.name = "LineResolverUnavailableError";
+    this.reason = str(args.details?.reason);
+  }
+};
+var LineResolverNotAvailableError = class extends ThrottleApiError {
+  reason;
+  constructor(args) {
+    super(coded("line_resolver_not_available", 422, args));
+    this.name = "LineResolverNotAvailableError";
+    this.reason = str(args.details?.reason);
+  }
+};
+var CurrencyNotEnabledError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("currency_not_enabled", 422, args));
+    this.name = "CurrencyNotEnabledError";
+  }
+};
+var ResolvedLinesRequiredError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("resolved_lines_required", 422, args));
+    this.name = "ResolvedLinesRequiredError";
+  }
+};
+var LineLimitReachedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("line_limit_reached", 422, args));
+    this.name = "LineLimitReachedError";
+  }
+};
+var CartPricesChangedError = class extends ThrottleApiError {
+  cart;
+  shipping;
+  constructor(args) {
+    super(coded("cart_prices_changed", 409, args));
+    this.name = "CartPricesChangedError";
+    const d = args.details;
+    this.cart = d?.cart && typeof d.cart === "object" ? d.cart : null;
+    this.shipping = d?.shipping && typeof d.shipping === "object" ? d.shipping : null;
+  }
+};
+var ShippingMethodUnavailableError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("shipping_method_unavailable", 422, args));
+    this.name = "ShippingMethodUnavailableError";
+  }
+};
+var ShippingQuoteUnavailableError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("shipping_quote_unavailable", 503, args));
+    this.name = "ShippingQuoteUnavailableError";
+  }
+};
+var AmountTooLargeError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("amount_too_large", 422, args));
+    this.name = "AmountTooLargeError";
+  }
+};
+var CartChangedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("cart_changed", 409, args));
+    this.name = "CartChangedError";
+  }
+};
+var RESOLVED_CART_ERRORS = {
+  price_locked: PriceLockedError,
+  quantity_unavailable: QuantityUnavailableError,
+  line_not_purchasable: LineNotPurchasableError,
+  line_resolver_unavailable: LineResolverUnavailableError,
+  line_resolver_not_available: LineResolverNotAvailableError,
+  currency_not_enabled: CurrencyNotEnabledError,
+  resolved_lines_required: ResolvedLinesRequiredError,
+  line_limit_reached: LineLimitReachedError,
+  cart_prices_changed: CartPricesChangedError,
+  shipping_method_unavailable: ShippingMethodUnavailableError,
+  shipping_quote_unavailable: ShippingQuoteUnavailableError,
+  amount_too_large: AmountTooLargeError,
+  cart_changed: CartChangedError
+};
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
     return new CartNotOpenError({
@@ -94,6 +231,15 @@ function cartErrorFromResponse(args) {
       responseHeaders: args.responseHeaders
     });
   }
+  const ResolvedCartError = Object.prototype.hasOwnProperty.call(RESOLVED_CART_ERRORS, args.code) ? RESOLVED_CART_ERRORS[args.code] : void 0;
+  if (ResolvedCartError) {
+    return new ResolvedCartError({
+      message: args.message,
+      statusCode: args.statusCode,
+      details: args.details,
+      responseHeaders: args.responseHeaders
+    });
+  }
   return new ThrottleApiError(args);
 }
 
@@ -151,6 +297,17 @@ var CartClient = class {
   get items() {
     return {
       add: (cartId, input) => this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, input),
+      /**
+       * Add a line to a resolved cart (one created with `lineResolver`). Only
+       * the item, quantity and metadata are sent; the app sets the name, price
+       * and image. Refusals throw the typed resolver errors.
+       */
+      addResolvedItem: (cartId, input) => {
+        const body = { referenceId: input.referenceId };
+        if (input.quantity !== void 0) body.quantity = input.quantity;
+        if (input.metadata !== void 0) body.metadata = input.metadata;
+        return this.request("POST", `/api/v1/carts/${segment(cartId)}/items`, body);
+      },
       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)}`)
     };
@@ -323,6 +480,32 @@ var CartSessionClient = class _CartSessionClient {
   async addItem(input) {
     return (await this.request("POST", `${this.basePath()}/items`, input)).cart;
   }
+  /**
+   * Add a line to a resolved cart (one created with `lineResolver`). Only the
+   * item, quantity and metadata are sent; the app sets the name, price and
+   * image. A refusal throws `QuantityUnavailableError`,
+   * `LineNotPurchasableError` or `LineResolverUnavailableError`.
+   */
+  async addResolvedItem(input) {
+    const body = { referenceId: input.referenceId };
+    if (input.quantity !== void 0) body.quantity = input.quantity;
+    if (input.metadata !== void 0) body.metadata = input.metadata;
+    return (await this.request("POST", `${this.basePath()}/items`, body)).cart;
+  }
+  /**
+   * Ask the app that prices a resolved cart to re-check every line it owns.
+   * `changed` is true when a price, name or refusal changed. An unresolved
+   * cart comes back unchanged. Throws `LineResolverUnavailableError` (nothing
+   * changed) when the app does not answer.
+   */
+  async refresh() {
+    const data = await this.request(
+      "POST",
+      `${this.basePath()}/refresh`,
+      {}
+    );
+    return { ...data.cart, changed: data.changed };
+  }
   async updateItem(itemId, input) {
     return (await this.request(
       "PATCH",
@@ -336,6 +519,17 @@ var CartSessionClient = class _CartSessionClient {
   async selectShipping(input) {
     return (await this.request("POST", `${this.basePath()}/shipping`, input)).cart;
   }
+  /**
+   * Pick a shipping method on a resolved cart. Throttle quotes the amount, so
+   * only `methodId` is sent. A method Throttle does not quote for the cart
+   * (it needs a shipping address first) throws `ShippingMethodUnavailableError`;
+   * a failed quote throws `ShippingQuoteUnavailableError`.
+   */
+  async selectShippingMethod(input) {
+    return (await this.request("POST", `${this.basePath()}/shipping`, {
+      methodId: input.methodId
+    })).cart;
+  }
   async clearShipping() {
     return (await this.request("DELETE", `${this.basePath()}/shipping`)).cart;
   }
@@ -424,11 +618,24 @@ var CartSessionClient = class _CartSessionClient {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AmountTooLargeError,
+  CartChangedError,
   CartClient,
   CartNotFoundError,
   CartNotOpenError,
+  CartPricesChangedError,
   CartSessionClient,
   CartTimeoutError,
+  CurrencyNotEnabledError,
+  LineLimitReachedError,
+  LineNotPurchasableError,
+  LineResolverNotAvailableError,
+  LineResolverUnavailableError,
+  PriceLockedError,
+  QuantityUnavailableError,
+  ResolvedLinesRequiredError,
+  ShippingMethodUnavailableError,
+  ShippingQuoteUnavailableError,
   StorefrontQuoteClient,
   ThrottleApiError,
   ThrottleError,