@usethrottle/cart 3.13.0 → 3.15.0

package/README.md

@@ -366,8 +366,10 @@ await client.items.add(cart.id, {
   to 1 year.
 - `totalPayments` (2–60) makes an installment plan; `trialDays` (0–365) a free
   trial. They cannot be combined (`400 invalid_combination`).
-- `type` is forced to `subscription`, and the line never ships:
-  `requiresShipping: true` is rejected with `400 validation_error`.
+- `type` is forced to `subscription`, and the line is never charged shipping.
+  It ships only with `deliveryMethod: 'shipment'`, which makes a physical
+  subscription: every renewal order owes a box. `requiresShipping: true` is
+  rejected with `400 validation_error`.
 - A free-trial line is stored with `unitPrice: 0` and your price on
   `recurring.amount`, and its name gets a "— 14-day free trial" suffix.
 - `PATCH` may change `quantity` (seats) and `metadata` only. Changing

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   CartSessionClient: () => CartSessionClient,
   CartTimeoutError: () => CartTimeoutError,
   CurrencyNotEnabledError: () => CurrencyNotEnabledError,
+  DiscountCurrencyUnsupportedError: () => DiscountCurrencyUnsupportedError,
   LineLimitReachedError: () => LineLimitReachedError,
   LineNotPurchasableError: () => LineNotPurchasableError,
   LineResolverNotAvailableError: () => LineResolverNotAvailableError,
@@ -36,6 +37,7 @@ __export(index_exports, {
   PriceLockedError: () => PriceLockedError,
   QuantityUnavailableError: () => QuantityUnavailableError,
   ResolvedLinesRequiredError: () => ResolvedLinesRequiredError,
+  ShippingCurrencyUnsupportedError: () => ShippingCurrencyUnsupportedError,
   ShippingMethodUnavailableError: () => ShippingMethodUnavailableError,
   ShippingQuoteUnavailableError: () => ShippingQuoteUnavailableError,
   StorefrontQuoteClient: () => StorefrontQuoteClient,
@@ -199,6 +201,21 @@ var CartChangedError = class extends ThrottleApiError {
     this.name = "CartChangedError";
   }
 };
+var DiscountCurrencyUnsupportedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("discount_currency_unsupported", 422, args));
+    this.name = "DiscountCurrencyUnsupportedError";
+  }
+};
+var ShippingCurrencyUnsupportedError = class extends ThrottleApiError {
+  shipping;
+  constructor(args) {
+    super(coded("shipping_currency_unsupported", 422, args));
+    this.name = "ShippingCurrencyUnsupportedError";
+    const d = args.details;
+    this.shipping = d?.shipping && typeof d.shipping === "object" ? d.shipping : null;
+  }
+};
 var RESOLVED_CART_ERRORS = {
   price_locked: PriceLockedError,
   quantity_unavailable: QuantityUnavailableError,
@@ -212,7 +229,9 @@ var RESOLVED_CART_ERRORS = {
   shipping_method_unavailable: ShippingMethodUnavailableError,
   shipping_quote_unavailable: ShippingQuoteUnavailableError,
   amount_too_large: AmountTooLargeError,
-  cart_changed: CartChangedError
+  cart_changed: CartChangedError,
+  discount_currency_unsupported: DiscountCurrencyUnsupportedError,
+  shipping_currency_unsupported: ShippingCurrencyUnsupportedError
 };
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
@@ -627,6 +646,7 @@ var CartSessionClient = class _CartSessionClient {
   CartSessionClient,
   CartTimeoutError,
   CurrencyNotEnabledError,
+  DiscountCurrencyUnsupportedError,
   LineLimitReachedError,
   LineNotPurchasableError,
   LineResolverNotAvailableError,
@@ -634,6 +654,7 @@ var CartSessionClient = class _CartSessionClient {
   PriceLockedError,
   QuantityUnavailableError,
   ResolvedLinesRequiredError,
+  ShippingCurrencyUnsupportedError,
   ShippingMethodUnavailableError,
   ShippingQuoteUnavailableError,
   StorefrontQuoteClient,

package/dist/index.d.cts

@@ -279,7 +279,8 @@ interface CreateCartInput {
     /**
      * Make this a resolved cart: the installed app with this extension id
      * prices its lines (add them with `items.addResolvedItem()`). Requires
-     * `currency`, which must be the environment's currency.
+     * `currency`: the environment's currency or one of its extra cart
+     * currencies (`cartCurrencies`).
      */
     lineResolver?: {
         extensionId: string;
@@ -315,12 +316,20 @@ interface AddLineItemInput {
     taxAmount?: number;
     discountAmount?: number;
     /**
-     * Makes this line a subscription: `type` is forced to `subscription`, and it
-     * never ships (`requiresShipping: true` is rejected with it). A free-trial
-     * line is stored with `unitPrice` 0 and your price on `recurring.amount`.
-     * Terms cannot change later: remove the line and add it again.
+     * Makes this line a subscription: `type` is forced to `subscription`. It
+     * ships only with `deliveryMethod: 'shipment'` (a physical subscription: a
+     * box every cycle, no shipping charge); `requiresShipping: true` is
+     * rejected with it. A free-trial line is stored with `unitPrice` 0 and your
+     * price on `recurring.amount`. Terms cannot change later: remove the line
+     * and add it again.
      */
     recurring?: LineRecurringInput;
+    /**
+     * What the item needs before it counts as delivered. Omit to infer it from
+     * `type` and `metadata`. `digital` and `access_grant` deliver themselves on
+     * payment; `none` means nothing to deliver.
+     */
+    deliveryMethod?: 'shipment' | 'digital' | 'access_grant' | 'service' | 'in_person' | 'custom' | 'none';
     imageUrl?: string;
     /**
      * Whether this item is physically shippable. For external/ad-hoc catalogs
@@ -651,7 +660,8 @@ interface CreateCartSessionInput {
     /**
      * Make this a resolved cart: the installed app with this extension id
      * prices its lines (add them with `addResolvedItem()`). Requires
-     * `currency`, which must be the environment's currency.
+     * `currency`: the environment's currency or one of its extra cart
+     * currencies (`cartCurrencies`).
      */
     lineResolver?: {
         extensionId: string;
@@ -973,7 +983,10 @@ type CurrencyNotEnabledDetails = {
     currency: string;
     enabledCurrencies: string[];
 };
-/** `422 currency_not_enabled`: a resolved cart must use the environment's currency. */
+/**
+ * `422 currency_not_enabled`: a resolved cart must use the environment's
+ * currency or one of its extra cart currencies (`enabledCurrencies` lists them).
+ */
 declare class CurrencyNotEnabledError extends ThrottleApiError {
     readonly details?: CurrencyNotEnabledDetails;
     constructor(args: CartErrorArgs);
@@ -997,14 +1010,16 @@ declare class LineLimitReachedError extends ThrottleApiError {
 /**
  * The stored shipping selection after the checkout hand-off re-quoted it.
  * `amount` is the new quote, or null with a `reason`: `method_unavailable`
- * (no longer offered, so cleared) or `quote_unavailable` (could not be
- * quoted now; kept for the next hand-off).
+ * (no longer offered, so cleared), `quote_unavailable` (could not be
+ * quoted now; kept for the next hand-off) or `shipping_currency_unsupported`
+ * (on a cart in an extra currency, its rate is a non-zero amount in another
+ * currency; kept, and the buyer must choose another method).
  */
 type CartShippingChange = {
     methodId: string;
     previousAmount: number;
     amount: number | null;
-    reason?: 'method_unavailable' | 'quote_unavailable';
+    reason?: 'method_unavailable' | 'quote_unavailable' | 'shipping_currency_unsupported';
 };
 /** `details` of `409 cart_prices_changed`. */
 type CartPricesChangedDetails = {
@@ -1041,6 +1056,27 @@ declare class AmountTooLargeError extends ThrottleApiError {
 declare class CartChangedError extends ThrottleApiError {
     constructor(args: CartErrorArgs);
 }
+/**
+ * `422 discount_currency_unsupported`: a fixed-amount discount can't be used
+ * on a resolved cart in an extra currency. Nothing is applied; a percentage
+ * discount works.
+ */
+declare class DiscountCurrencyUnsupportedError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/**
+ * `422 shipping_currency_unsupported`: on a resolved cart in an extra
+ * currency, a non-zero shipping rate in another currency. Nothing new is
+ * selected; choose a zero-rate method. At the checkout hand-off, `shipping`
+ * is the kept selection.
+ */
+declare class ShippingCurrencyUnsupportedError extends ThrottleApiError {
+    readonly details?: {
+        shipping?: CartShippingChange;
+    };
+    readonly shipping: CartShippingChange | null;
+    constructor(args: CartErrorArgs);
+}
 /**
  * Map a raw API error envelope to the most specific Cart SDK error class.
  * Falls back to {@link ThrottleApiError} for everything unrecognised.
@@ -1053,4 +1089,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AddResolvedLineItemInput, AmountTooLargeError, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartChangedError, CartClient, type CartErrorArgs, type CartEvent, CartNotFoundError, CartNotOpenError, type CartPricesChangedDetails, CartPricesChangedError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, type CartShippingChange, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type CurrencyNotEnabledDetails, CurrencyNotEnabledError, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineLimitReachedDetails, LineLimitReachedError, type LineNotPurchasableDetails, LineNotPurchasableError, type LineRecurringInput, type LineResolution, type LineResolverNotAvailableDetails, LineResolverNotAvailableError, type LineResolverUnavailableDetails, LineResolverUnavailableError, type Order, type PriceLockedDetails, PriceLockedError, type QuantityUnavailableDetails, QuantityUnavailableError, type RefusedCartLine, ResolvedLinesRequiredError, type SelectShippingInput, type SelectShippingMethodInput, type SelectedShipping, ShippingMethodUnavailableError, ShippingQuoteUnavailableError, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AddResolvedLineItemInput, AmountTooLargeError, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartChangedError, CartClient, type CartErrorArgs, type CartEvent, CartNotFoundError, CartNotOpenError, type CartPricesChangedDetails, CartPricesChangedError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, type CartShippingChange, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type CurrencyNotEnabledDetails, CurrencyNotEnabledError, DiscountCurrencyUnsupportedError, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineLimitReachedDetails, LineLimitReachedError, type LineNotPurchasableDetails, LineNotPurchasableError, type LineRecurringInput, type LineResolution, type LineResolverNotAvailableDetails, LineResolverNotAvailableError, type LineResolverUnavailableDetails, LineResolverUnavailableError, type Order, type PriceLockedDetails, PriceLockedError, type QuantityUnavailableDetails, QuantityUnavailableError, type RefusedCartLine, ResolvedLinesRequiredError, type SelectShippingInput, type SelectShippingMethodInput, type SelectedShipping, ShippingCurrencyUnsupportedError, ShippingMethodUnavailableError, ShippingQuoteUnavailableError, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.d.ts

@@ -279,7 +279,8 @@ interface CreateCartInput {
     /**
      * Make this a resolved cart: the installed app with this extension id
      * prices its lines (add them with `items.addResolvedItem()`). Requires
-     * `currency`, which must be the environment's currency.
+     * `currency`: the environment's currency or one of its extra cart
+     * currencies (`cartCurrencies`).
      */
     lineResolver?: {
         extensionId: string;
@@ -315,12 +316,20 @@ interface AddLineItemInput {
     taxAmount?: number;
     discountAmount?: number;
     /**
-     * Makes this line a subscription: `type` is forced to `subscription`, and it
-     * never ships (`requiresShipping: true` is rejected with it). A free-trial
-     * line is stored with `unitPrice` 0 and your price on `recurring.amount`.
-     * Terms cannot change later: remove the line and add it again.
+     * Makes this line a subscription: `type` is forced to `subscription`. It
+     * ships only with `deliveryMethod: 'shipment'` (a physical subscription: a
+     * box every cycle, no shipping charge); `requiresShipping: true` is
+     * rejected with it. A free-trial line is stored with `unitPrice` 0 and your
+     * price on `recurring.amount`. Terms cannot change later: remove the line
+     * and add it again.
      */
     recurring?: LineRecurringInput;
+    /**
+     * What the item needs before it counts as delivered. Omit to infer it from
+     * `type` and `metadata`. `digital` and `access_grant` deliver themselves on
+     * payment; `none` means nothing to deliver.
+     */
+    deliveryMethod?: 'shipment' | 'digital' | 'access_grant' | 'service' | 'in_person' | 'custom' | 'none';
     imageUrl?: string;
     /**
      * Whether this item is physically shippable. For external/ad-hoc catalogs
@@ -651,7 +660,8 @@ interface CreateCartSessionInput {
     /**
      * Make this a resolved cart: the installed app with this extension id
      * prices its lines (add them with `addResolvedItem()`). Requires
-     * `currency`, which must be the environment's currency.
+     * `currency`: the environment's currency or one of its extra cart
+     * currencies (`cartCurrencies`).
      */
     lineResolver?: {
         extensionId: string;
@@ -973,7 +983,10 @@ type CurrencyNotEnabledDetails = {
     currency: string;
     enabledCurrencies: string[];
 };
-/** `422 currency_not_enabled`: a resolved cart must use the environment's currency. */
+/**
+ * `422 currency_not_enabled`: a resolved cart must use the environment's
+ * currency or one of its extra cart currencies (`enabledCurrencies` lists them).
+ */
 declare class CurrencyNotEnabledError extends ThrottleApiError {
     readonly details?: CurrencyNotEnabledDetails;
     constructor(args: CartErrorArgs);
@@ -997,14 +1010,16 @@ declare class LineLimitReachedError extends ThrottleApiError {
 /**
  * The stored shipping selection after the checkout hand-off re-quoted it.
  * `amount` is the new quote, or null with a `reason`: `method_unavailable`
- * (no longer offered, so cleared) or `quote_unavailable` (could not be
- * quoted now; kept for the next hand-off).
+ * (no longer offered, so cleared), `quote_unavailable` (could not be
+ * quoted now; kept for the next hand-off) or `shipping_currency_unsupported`
+ * (on a cart in an extra currency, its rate is a non-zero amount in another
+ * currency; kept, and the buyer must choose another method).
  */
 type CartShippingChange = {
     methodId: string;
     previousAmount: number;
     amount: number | null;
-    reason?: 'method_unavailable' | 'quote_unavailable';
+    reason?: 'method_unavailable' | 'quote_unavailable' | 'shipping_currency_unsupported';
 };
 /** `details` of `409 cart_prices_changed`. */
 type CartPricesChangedDetails = {
@@ -1041,6 +1056,27 @@ declare class AmountTooLargeError extends ThrottleApiError {
 declare class CartChangedError extends ThrottleApiError {
     constructor(args: CartErrorArgs);
 }
+/**
+ * `422 discount_currency_unsupported`: a fixed-amount discount can't be used
+ * on a resolved cart in an extra currency. Nothing is applied; a percentage
+ * discount works.
+ */
+declare class DiscountCurrencyUnsupportedError extends ThrottleApiError {
+    constructor(args: CartErrorArgs);
+}
+/**
+ * `422 shipping_currency_unsupported`: on a resolved cart in an extra
+ * currency, a non-zero shipping rate in another currency. Nothing new is
+ * selected; choose a zero-rate method. At the checkout hand-off, `shipping`
+ * is the kept selection.
+ */
+declare class ShippingCurrencyUnsupportedError extends ThrottleApiError {
+    readonly details?: {
+        shipping?: CartShippingChange;
+    };
+    readonly shipping: CartShippingChange | null;
+    constructor(args: CartErrorArgs);
+}
 /**
  * Map a raw API error envelope to the most specific Cart SDK error class.
  * Falls back to {@link ThrottleApiError} for everything unrecognised.
@@ -1053,4 +1089,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AddResolvedLineItemInput, AmountTooLargeError, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartChangedError, CartClient, type CartErrorArgs, type CartEvent, CartNotFoundError, CartNotOpenError, type CartPricesChangedDetails, CartPricesChangedError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, type CartShippingChange, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type CurrencyNotEnabledDetails, CurrencyNotEnabledError, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineLimitReachedDetails, LineLimitReachedError, type LineNotPurchasableDetails, LineNotPurchasableError, type LineRecurringInput, type LineResolution, type LineResolverNotAvailableDetails, LineResolverNotAvailableError, type LineResolverUnavailableDetails, LineResolverUnavailableError, type Order, type PriceLockedDetails, PriceLockedError, type QuantityUnavailableDetails, QuantityUnavailableError, type RefusedCartLine, ResolvedLinesRequiredError, type SelectShippingInput, type SelectShippingMethodInput, type SelectedShipping, ShippingMethodUnavailableError, ShippingQuoteUnavailableError, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AddResolvedLineItemInput, AmountTooLargeError, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartChangedError, CartClient, type CartErrorArgs, type CartEvent, CartNotFoundError, CartNotOpenError, type CartPricesChangedDetails, CartPricesChangedError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, type CartShippingChange, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type CurrencyNotEnabledDetails, CurrencyNotEnabledError, DiscountCurrencyUnsupportedError, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineLimitReachedDetails, LineLimitReachedError, type LineNotPurchasableDetails, LineNotPurchasableError, type LineRecurringInput, type LineResolution, type LineResolverNotAvailableDetails, LineResolverNotAvailableError, type LineResolverUnavailableDetails, LineResolverUnavailableError, type Order, type PriceLockedDetails, PriceLockedError, type QuantityUnavailableDetails, QuantityUnavailableError, type RefusedCartLine, ResolvedLinesRequiredError, type SelectShippingInput, type SelectShippingMethodInput, type SelectedShipping, ShippingCurrencyUnsupportedError, ShippingMethodUnavailableError, ShippingQuoteUnavailableError, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.js

@@ -151,6 +151,21 @@ var CartChangedError = class extends ThrottleApiError {
     this.name = "CartChangedError";
   }
 };
+var DiscountCurrencyUnsupportedError = class extends ThrottleApiError {
+  constructor(args) {
+    super(coded("discount_currency_unsupported", 422, args));
+    this.name = "DiscountCurrencyUnsupportedError";
+  }
+};
+var ShippingCurrencyUnsupportedError = class extends ThrottleApiError {
+  shipping;
+  constructor(args) {
+    super(coded("shipping_currency_unsupported", 422, args));
+    this.name = "ShippingCurrencyUnsupportedError";
+    const d = args.details;
+    this.shipping = d?.shipping && typeof d.shipping === "object" ? d.shipping : null;
+  }
+};
 var RESOLVED_CART_ERRORS = {
   price_locked: PriceLockedError,
   quantity_unavailable: QuantityUnavailableError,
@@ -164,7 +179,9 @@ var RESOLVED_CART_ERRORS = {
   shipping_method_unavailable: ShippingMethodUnavailableError,
   shipping_quote_unavailable: ShippingQuoteUnavailableError,
   amount_too_large: AmountTooLargeError,
-  cart_changed: CartChangedError
+  cart_changed: CartChangedError,
+  discount_currency_unsupported: DiscountCurrencyUnsupportedError,
+  shipping_currency_unsupported: ShippingCurrencyUnsupportedError
 };
 function cartErrorFromResponse(args) {
   if (args.statusCode === 409 && args.code === "cart_not_open") {
@@ -578,6 +595,7 @@ export {
   CartSessionClient,
   CartTimeoutError,
   CurrencyNotEnabledError,
+  DiscountCurrencyUnsupportedError,
   LineLimitReachedError,
   LineNotPurchasableError,
   LineResolverNotAvailableError,
@@ -585,6 +603,7 @@ export {
   PriceLockedError,
   QuantityUnavailableError,
   ResolvedLinesRequiredError,
+  ShippingCurrencyUnsupportedError,
   ShippingMethodUnavailableError,
   ShippingQuoteUnavailableError,
   StorefrontQuoteClient,

package/package.json

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