@moonbase.sh/storefront-api 2.4.0 → 3.0.0

package/dist/index.js

@@ -18,10 +18,14 @@ import { z as z4 } from "zod";
 var schemas_exports2 = {};
 __export(schemas_exports2, {
   offerConditionSchema: () => offerConditionSchema,
+  offerScopeSchema: () => offerScopeSchema,
   storefrontBundleSchema: () => storefrontBundleSchema,
   storefrontOfferSchema: () => storefrontOfferSchema,
   storefrontOfferTargetSchema: () => storefrontOfferTargetSchema,
   storefrontProductSchema: () => storefrontProductSchema,
+  storefrontPromotionCtaSchema: () => storefrontPromotionCtaSchema,
+  storefrontPromotionSchema: () => storefrontPromotionSchema,
+  storefrontPromotionTargetSchema: () => storefrontPromotionTargetSchema,
   storefrontSchema: () => storefrontSchema,
   taxEstimateSchema: () => taxEstimateSchema
 });
@@ -61,6 +65,11 @@ function utmToObject(utm) {
 
 // src/globalSchemas.ts
 var priceCollectionSchema = z.record(z.number());
+var discountPromotionFields = {
+  promotionId: z.string().optional(),
+  validFrom: z.string().optional(),
+  validUntil: z.string().optional()
+};
 var percentageOffDiscountSchema = z.object({
   type: z.literal("PercentageOffDiscount"),
   name: z.string(),
@@ -68,7 +77,8 @@ var percentageOffDiscountSchema = z.object({
   percentage: z.number(),
   total: priceCollectionSchema.optional(),
   isExclusive: z.boolean(),
-  recurringPaymentUseCount: z.number().optional()
+  recurringPaymentUseCount: z.number().optional(),
+  ...discountPromotionFields
 });
 var flatAmountOffDiscountSchema = z.object({
   type: z.literal("FlatAmountOffDiscount"),
@@ -76,7 +86,8 @@ var flatAmountOffDiscountSchema = z.object({
   description: z.string().optional(),
   total: priceCollectionSchema.optional(),
   isExclusive: z.boolean(),
-  recurringPaymentUseCount: z.number().optional()
+  recurringPaymentUseCount: z.number().optional(),
+  ...discountPromotionFields
 });
 var moneySchema = z.object({
   currency: z.string(),
@@ -110,6 +121,7 @@ var rawPropertyValueSchema = z.lazy(
     z.string(),
     z.number(),
     z.boolean(),
+    z.null(),
     z.record(rawPropertyValueSchema),
     z.array(rawPropertyValueSchema)
   ])
@@ -180,7 +192,7 @@ var downloadSchema = z2.object({
 var productSummarySchema = z2.object({
   id: z2.string(),
   name: z2.string(),
-  tagline: z2.string(),
+  tagline: z2.string().nullish(),
   description: z2.string().nullish(),
   website: z2.string().optional(),
   iconUrl: z2.string().optional(),
@@ -203,8 +215,8 @@ var productSummarySchema = z2.object({
 var storefrontProductSchema = z3.object({
   id: z3.string(),
   name: z3.string(),
-  tagline: z3.string(),
-  description: z3.string(),
+  tagline: z3.string().nullish(),
+  description: z3.string().nullish(),
   iconUrl: z3.string().nullable(),
   website: z3.string().nullish(),
   owned: z3.boolean(),
@@ -218,8 +230,8 @@ var storefrontProductSchema = z3.object({
 var storefrontBundleSchema = z3.object({
   id: z3.string(),
   name: z3.string(),
-  tagline: z3.string(),
-  description: z3.string(),
+  tagline: z3.string().nullish(),
+  description: z3.string().nullish(),
   iconUrl: z3.string().nullable(),
   owned: z3.boolean(),
   partial: z3.boolean(),
@@ -236,7 +248,22 @@ var cartContainsItemsConditionSchema = z3.object({
   minimumItems: z3.number(),
   relevantItemVariations: z3.record(z3.string(), z3.string().array())
 });
-var offerConditionSchema = z3.discriminatedUnion("type", [cartContainsItemsConditionSchema]);
+var cartTotalConditionSchema = z3.object({
+  type: z3.literal("CartTotal"),
+  // Both bounds are optional, but never both absent. They serialize as an explicit `null` when
+  // unset, hence `.nullish()` rather than `.optional()`. The API converts them into every enabled
+  // currency up front, precisely so we can tell the buyer how much further they have to go without
+  // doing any currency conversion ourselves.
+  minimumTotal: priceCollectionSchema.nullish(),
+  maximumTotal: priceCollectionSchema.nullish()
+});
+var knownOfferConditionSchema = z3.discriminatedUnion("type", [
+  cartContainsItemsConditionSchema,
+  cartTotalConditionSchema
+]);
+var unsupportedOfferConditionSchema = z3.object({ type: z3.string() }).passthrough().transform(({ type }) => ({ type: "Unsupported", unsupportedType: type }));
+var offerConditionSchema = z3.union([knownOfferConditionSchema, unsupportedOfferConditionSchema]);
+var offerScopeSchema = z3.enum(["Item", "Cart"]).catch("Item").optional().default("Item");
 var offerTargetItemSchema = z3.union([storefrontProductSchema, storefrontBundleSchema]);
 var storefrontOfferTargetSchema = z3.object({
   // The product or bundle the offer applies to.
@@ -252,8 +279,10 @@ function legacyOfferTargets(target, targetVariations) {
 }
 var storefrontOfferSchema = z3.object({
   id: z3.string(),
+  scope: offerScopeSchema,
   // Each target pairs a product/bundle with the pricing variations the offer applies to (an empty
-  // list means all variations). This is the model to consume.
+  // list means all variations). This is the model to consume. A cart offer may have no targets at
+  // all, which means it discounts every line item.
   targets: z3.array(storefrontOfferTargetSchema).optional(),
   // Legacy fields, kept optional only so old cached storefront responses still parse. The API now
   // exposes the unified `targets` model; we derive `targets` from these when a response predates it.
@@ -267,6 +296,57 @@ var storefrontOfferSchema = z3.object({
   ...rest,
   targets: targets != null ? targets : legacyOfferTargets(target, targetVariations)
 }));
+var storefrontPromotionTargetSchema = z3.object({
+  // A prefixed reference to the item the sale covers, `Product/<id>` or `Bundle/<id>`. The item
+  // itself is already serialized in `products`/`bundles`; embedding it again would duplicate the
+  // bulk of the payload for a sale spanning dozens of products.
+  referenceId: z3.string(),
+  // The pricing variation IDs the sale is restricted to; an empty list means all variations.
+  variations: z3.string().array()
+});
+var storefrontPromotionCtaSchema = z3.object({
+  url: z3.string(),
+  label: z3.string()
+});
+var storefrontPromotionSchema = z3.object({
+  id: z3.string(),
+  name: z3.string(),
+  description: z3.string().nullish(),
+  imageUrl: z3.string().nullish(),
+  // Absent when the merchant has not set one, in which case the storefront decides whether the
+  // sale leads anywhere.
+  cta: storefrontPromotionCtaSchema.nullish(),
+  // How the merchant wants the sale surfaced, e.g. `['Banner', 'Popup']`; an empty list means no
+  // preference. Kept as free-form strings and narrowed with `isPromotionDisplay`, so a display
+  // mode added server-side later is ignored rather than failing the whole storefront.
+  display: z3.string().array(),
+  // The promotion's *intended* scope, not what is actually showing the sale price: each variation
+  // displays only its single best discount, so a targeted item may be showing a better one. The
+  // authoritative signal is `promotionId` on a variation's own discount.
+  targets: storefrontPromotionTargetSchema.array(),
+  // The promotion's own discount, for banner copy ("20% off"). Per-item prices are already
+  // discounted on each variation.
+  discount: discountSchema,
+  validFrom: z3.string().nullish(),
+  validUntil: z3.string().nullish(),
+  properties: z3.record(rawPropertyValueSchema).nullish()
+});
+var storefrontOffersSchema = z3.array(z3.unknown()).transform((offers) => offers.flatMap((offer) => {
+  const parsed = storefrontOfferSchema.safeParse(offer);
+  if (!parsed.success) {
+    console.warn("Ignoring storefront offer that could not be parsed:", parsed.error.issues);
+    return [];
+  }
+  return [parsed.data];
+}));
+var storefrontPromotionsSchema = z3.array(z3.unknown()).transform((promotions) => promotions.flatMap((promotion) => {
+  const parsed = storefrontPromotionSchema.safeParse(promotion);
+  if (!parsed.success) {
+    console.warn("Ignoring storefront promotion that could not be parsed:", parsed.error.issues);
+    return [];
+  }
+  return [parsed.data];
+}));
 var taxEstimateSchema = z3.object({
   rate: z3.number(),
   mode: z3.enum(["Exclusive", "Inclusive"]),
@@ -280,7 +360,9 @@ var storefrontSchema = z3.object({
   products: storefrontProductSchema.array(),
   bundles: storefrontBundleSchema.array(),
   // Offers need to be optional since we may still have old, cached representations in browsers
-  offers: storefrontOfferSchema.array().optional(),
+  offers: storefrontOffersSchema.optional(),
+  // Promotions need to be optional since we may still have old, cached representations in browsers
+  promotions: storefrontPromotionsSchema.optional(),
   // Depending on circumstances, we may have a tax estimate available
   estimatedTax: taxEstimateSchema.optional()
 });
@@ -1026,6 +1108,7 @@ import { z as z13 } from "zod";
 var schemas_exports7 = {};
 __export(schemas_exports7, {
   completedOrderSchema: () => completedOrderSchema,
+  lineItemTotalSchema: () => lineItemTotalSchema,
   openBundleLineItem: () => openBundleLineItem,
   openOrderLineItem: () => openOrderLineItem,
   openOrderSchema: () => openOrderSchema,
@@ -1054,14 +1137,17 @@ var couponSchema = z12.object({
 var lineItemProductSchema = z12.object({
   id: z12.string(),
   name: z12.string(),
-  tagline: z12.string(),
+  tagline: z12.string().nullish(),
   iconUrl: z12.string().nullable()
 });
 var lineItemTotalSchema = z12.object({
   original: moneySchema,
   discount: moneySchema,
   subtotal: moneySchema,
-  due: moneySchema
+  due: moneySchema,
+  // This line's per-unit share of the order's cart offer, kept apart from the offer the buyer picked
+  // for this item. Both are part of `discount`. Absent on orders priced before cart offers existed.
+  cartOfferDiscount: moneySchema.optional()
 });
 var openProductLineItem = z12.object({
   id: z12.string(),
@@ -1081,7 +1167,7 @@ var openProductLineItem = z12.object({
 var lineItemBundleSchema = z12.object({
   id: z12.string(),
   name: z12.string(),
-  tagline: z12.string(),
+  tagline: z12.string().nullish(),
   iconUrl: z12.string().nullable(),
   products: lineItemProductSchema.and(z12.object({
     included: z12.boolean().optional()
@@ -1113,7 +1199,10 @@ var orderTotalSchema = z12.object({
   discount: moneySchema,
   subtotal: moneySchema,
   taxes: moneySchema,
-  due: moneySchema
+  due: moneySchema,
+  // How much of `discount` came from the cart offer, so it can be shown as one order-wide saving
+  // rather than a share on every line. Absent when no cart offer applied.
+  cartOfferDiscount: moneySchema.optional()
 });
 var openOrderSchema = z12.object({
   id: z12.string(),
@@ -1121,6 +1210,12 @@ var openOrderSchema = z12.object({
   total: orderTotalSchema.nullish(),
   items: openOrderLineItem.array(),
   couponsApplied: couponSchema.array(),
+  // The cart offer on the order as a whole: the buyer's intent. It is part of the cart payload, so
+  // a content push that leaves it out clears it. The API echoes it back even while the cart sits
+  // below the offer's threshold.
+  offerId: z12.string().optional(),
+  // The cart offer as actually applied: the result. Absent while the offer's condition doesn't hold.
+  appliedOffer: discountSchema.optional(),
   checkoutUrl: z12.string().optional(),
   hostedCheckoutUrl: z12.string().optional(),
   embeddedCheckoutUrl: z12.string().optional()
@@ -1140,7 +1235,8 @@ var completedOrderSchema = z12.object({
   customer: customerSnapshotSchema,
   total: orderTotalSchema,
   items: openOrderLineItem.array(),
-  couponsApplied: couponSchema.array()
+  couponsApplied: couponSchema.array(),
+  appliedOffer: discountSchema.optional()
 });
 var orderSchema = z12.discriminatedUnion("status", [
   openOrderSchema.extend({
@@ -1298,6 +1394,7 @@ var OrderEndpoints = class {
         method: "PATCH",
         body: {
           currency: order.currency || void 0,
+          offerId: order.offerId,
           items: order.items
         }
       }
@@ -1312,6 +1409,12 @@ var OrderEndpoints = class {
     const response = await this.api.fetch(`/api/customer/orders/${orderId}/billing-details`, openOrderSchema, { method: "DELETE" });
     return response.data;
   }
+  // Takes the cart offer off the order without re-sending the cart. Offers picked for a single item
+  // come off by pushing that item without its `offerId` instead.
+  async removeOffer(orderId) {
+    const response = await this.api.fetch(`/api/customer/orders/${orderId}/offer`, openOrderSchema, { method: "DELETE" });
+    return response.data;
+  }
   async addCouponCode(orderId, code) {
     const response = await this.api.fetch(`/api/customer/orders/${orderId}/coupon?code=${encodeURIComponent(code)}`, openOrderSchema, { method: "PATCH" });
     return response.data;
@@ -1616,6 +1719,12 @@ __export(schemas_exports11, {
   subscriptions: () => schemas_exports8
 });
 
+// src/storefront/models.ts
+var promotionDisplays = ["Banner", "Popup"];
+function isPromotionDisplay(value) {
+  return promotionDisplays.includes(value);
+}
+
 // src/utils/discount.ts
 var DiscountUtils = class {
   static apply(discount, price) {
@@ -1642,25 +1751,68 @@ var MoneyCollectionUtils = class {
 };
 
 // src/utils/offer.ts
+function evaluated(unit, currency, current, target, eligible) {
+  return {
+    eligible,
+    progress: {
+      unit,
+      currency,
+      current,
+      target,
+      remaining: Math.max(0, target - current),
+      fraction: target <= 0 ? 1 : Math.min(1, Math.max(0, current / target)),
+      eligible
+    }
+  };
+}
 var OfferUtils = class _OfferUtils {
-  static eligible(offer, order) {
-    switch (offer.condition.type) {
+  // Callers that only have an order keep working and simply have no cart total, so a monetary
+  // condition fails closed for them. Pass the full context to have `CartTotal` actually evaluate.
+  static eligible(offer, context) {
+    return _OfferUtils.evaluate(offer, context).eligible;
+  }
+  // How close the cart is to satisfying the offer, or `null` when there is nothing to show progress
+  // toward: an unsupported condition, an unknown cart total, or a condition with only an upper
+  // bound (which the buyer starts out satisfying rather than working toward).
+  static progress(offer, context) {
+    return _OfferUtils.evaluate(offer, context).progress;
+  }
+  // The single evaluator behind both faces, so the "spend €12 more" nudge and the gate that unlocks
+  // the discount can never disagree about the same cart.
+  static evaluate(offer, context) {
+    var _a, _b;
+    const { order, cartTotal } = "items" in context ? { order: context, cartTotal: void 0 } : context;
+    const condition = offer.condition;
+    switch (condition.type) {
       case "CartContainsItems": {
         const relevantItems = order.items.filter(
-          (i) => i.type === "Product" && offer.condition.relevantItemVariations[`Product/${i.productId}`] && offer.condition.relevantItemVariations[`Product/${i.productId}`].includes(i.variationId) || i.type === "Bundle" && offer.condition.relevantItemVariations[`Bundle/${i.bundleId}`] && offer.condition.relevantItemVariations[`Bundle/${i.bundleId}`].includes(i.variationId)
+          (i) => i.type === "Product" && condition.relevantItemVariations[`Product/${i.productId}`] && condition.relevantItemVariations[`Product/${i.productId}`].includes(i.variationId) || i.type === "Bundle" && condition.relevantItemVariations[`Bundle/${i.bundleId}`] && condition.relevantItemVariations[`Bundle/${i.bundleId}`].includes(i.variationId)
         );
         const relevantReplacedItems = order.items.flatMap((i) => {
-          var _a;
-          return offer.id === i.offerId && i.type === "Bundle" && _OfferUtils.targetContainsBundle(offer, i.id) ? (_a = i.replaced) != null ? _a : [] : [];
+          var _a2;
+          return offer.id === i.offerId && i.type === "Bundle" && _OfferUtils.targetContainsBundle(offer, i.id) ? (_a2 = i.replaced) != null ? _a2 : [] : [];
         }).filter((ref) => {
           const [productId, variationId] = ref.split("/");
-          return offer.condition.relevantItemVariations[`Product/${productId}`] && offer.condition.relevantItemVariations[`Product/${productId}`].includes(variationId);
+          return condition.relevantItemVariations[`Product/${productId}`] && condition.relevantItemVariations[`Product/${productId}`].includes(variationId);
         });
-        return relevantItems.length + relevantReplacedItems.length >= offer.condition.minimumItems;
+        const current = relevantItems.length + relevantReplacedItems.length;
+        return evaluated("Items", void 0, current, condition.minimumItems, current >= condition.minimumItems);
+      }
+      case "CartTotal": {
+        if (!cartTotal)
+          return { eligible: false, progress: null };
+        const minimum = (_a = condition.minimumTotal) == null ? void 0 : _a[cartTotal.currency];
+        const maximum = (_b = condition.maximumTotal) == null ? void 0 : _b[cartTotal.currency];
+        if (minimum === void 0 && maximum === void 0)
+          return { eligible: false, progress: null };
+        const eligible = (minimum === void 0 || cartTotal.amount >= minimum) && (maximum === void 0 || cartTotal.amount <= maximum);
+        if (minimum === void 0)
+          return { eligible, progress: null };
+        return evaluated("Money", cartTotal.currency, cartTotal.amount, minimum, eligible);
       }
     }
-    console.warn("Unsupported offer condition found:", offer.condition);
-    return false;
+    console.warn("Unsupported offer condition found:", condition);
+    return { eligible: false, progress: null };
   }
   // The relevant targets of an offer with more than a single target needs to:
   // a. Not be owned, or all targets need to be owned
@@ -1701,6 +1853,276 @@ var OfferUtils = class _OfferUtils {
   }
 };
 
+// src/utils/cart.ts
+var CartUtils = class _CartUtils {
+  // The pricing variation a line item points at, falling back to the item's default variation when
+  // the variation id doesn't resolve, which is what the cart has always displayed.
+  static resolveVariation(catalog, item) {
+    var _a, _b;
+    const source = item.type === "Product" ? catalog.products.find((p) => p.id === item.productId) : catalog.bundles.find((b) => b.id === item.bundleId);
+    return (_b = (_a = source == null ? void 0 : source.variations) == null ? void 0 : _a.find((v) => v.id === item.variationId)) != null ? _b : source == null ? void 0 : source.defaultVariation;
+  }
+  // A line's unit price after its product discount and any pricing tier, and *before* any offer.
+  // This is the basis the API measures cart total conditions on, which is why it reads the catalog
+  // rather than the line item's own `price`: `enrichLineItems` rewrites that to the offer-discounted
+  // price, and reading it here would take the offer off twice.
+  static unitPrice(catalog, item, currency) {
+    var _a;
+    return (_a = _CartUtils.unitPricing(catalog, item, currency)) == null ? void 0 : _a.price;
+  }
+  // A line's list and post-product-discount unit prices, from whichever pricing tier applies. Both
+  // come from the same tier so they can be subtracted from one another: taking the list price off one
+  // tier and the paid price off another would invent a discount neither of them offers.
+  static unitPricing(catalog, item, currency) {
+    var _a, _b, _c, _d, _e, _f;
+    const variation = _CartUtils.resolveVariation(catalog, item);
+    const price = variation == null ? void 0 : variation.price[currency];
+    if (price === void 0 || variation === void 0)
+      return void 0;
+    const eligiblePricingTiers = (_b = (_a = variation.pricingTiers) == null ? void 0 : _a.filter((tier) => item.quantity >= tier.minQuantity)) != null ? _b : [];
+    const matchingPricingTier = eligiblePricingTiers.length > 0 ? eligiblePricingTiers[eligiblePricingTiers.length - 1] : null;
+    const tierPrice = matchingPricingTier == null ? void 0 : matchingPricingTier.price[currency];
+    if (tierPrice !== void 0 && tierPrice < price) {
+      return {
+        price: tierPrice,
+        originalPrice: (_d = (_c = matchingPricingTier == null ? void 0 : matchingPricingTier.originalPrice) == null ? void 0 : _c[currency]) != null ? _d : tierPrice
+      };
+    }
+    return { price, originalPrice: (_f = (_e = variation.originalPrice) == null ? void 0 : _e[currency]) != null ? _f : price };
+  }
+  // The number the API measures cart conditions against: each line's price after its product
+  // discount, times quantity, before offers and coupons. `undefined` when any line's price can't be
+  // resolved in `currency`. One unreadable line makes the whole measurement a guess, and a guess
+  // must not unlock an offer.
+  static measure(catalog, items, currency) {
+    if (!currency)
+      return void 0;
+    let amount = 0;
+    for (const item of items) {
+      const unitPrice = _CartUtils.unitPrice(catalog, item, currency);
+      if (unitPrice === void 0)
+        return void 0;
+      amount += unitPrice * item.quantity;
+    }
+    return { currency, amount };
+  }
+  static conditionContext(catalog, order, currency) {
+    return { order, cartTotal: _CartUtils.measure(catalog, order.items, currency) };
+  }
+  // Which lines a cart offer discounts. No targets means the whole cart, a reading that only holds
+  // for cart-scope offers, where an empty target list is the API's way of saying "every line".
+  static cartOfferAppliesToLine(offer, item) {
+    if (offer.targets.length === 0)
+      return true;
+    return offer.targets.some(({ item: target, variations }) => target.type === item.type && target.id === (item.type === "Product" ? item.productId : item.bundleId) && (variations.length === 0 || variations.includes(item.variationId)));
+  }
+  // The cart offer actually discounting this cart, as opposed to the one attached to the order. An
+  // offer whose targets name nothing in the cart discounts nothing however healthy the total looks,
+  // so it has not really applied.
+  static appliedCartOffer(catalog, order, context) {
+    var _a;
+    if (!order.offerId)
+      return void 0;
+    const offer = (_a = catalog.offers) == null ? void 0 : _a.find((o) => o.id === order.offerId);
+    if (!offer || offer.scope !== "Cart" || !OfferUtils.eligible(offer, context))
+      return void 0;
+    return order.items.some((item) => _CartUtils.cartOfferAppliesToLine(offer, item)) ? offer : void 0;
+  }
+  // What the cart is worth to the buyer, broken down so the cart can show the saving on its own row.
+  // Unlike `measure`, an unresolvable price counts as zero here: this number fills a label, so a
+  // half-loaded catalog should still render a total rather than nothing.
+  static total(catalog, order, currency) {
+    var _a, _b;
+    const context = _CartUtils.conditionContext(catalog, order, currency);
+    const cartOffer = _CartUtils.appliedCartOffer(catalog, order, context);
+    let original = 0;
+    let subtotal = 0;
+    let cartOfferDiscount = 0;
+    for (const item of order.items) {
+      const unitPrice = _CartUtils.unitPriceAfterItemOffer(catalog, item, currency, context);
+      original += ((_b = (_a = _CartUtils.unitPricing(catalog, item, currency)) == null ? void 0 : _a.originalPrice) != null ? _b : unitPrice) * item.quantity;
+      subtotal += unitPrice * item.quantity;
+      if (cartOffer && _CartUtils.cartOfferAppliesToLine(cartOffer, item))
+        cartOfferDiscount += DiscountUtils.apply(cartOffer.discount, { [currency]: unitPrice })[currency] * item.quantity;
+    }
+    const amount = subtotal - cartOfferDiscount;
+    return {
+      currency,
+      original,
+      subtotal,
+      cartOffer: cartOffer ? { offer: cartOffer, discount: cartOfferDiscount } : null,
+      discount: original - amount,
+      amount
+    };
+  }
+  // The cart offer worth attaching to the order. Cart offers are always percentages, but 10% off
+  // everything can still beat 50% off one cheap line, so they are ranked by what they would actually
+  // take off this cart rather than by percentage.
+  static bestCartOffer(catalog, order, currency) {
+    var _a;
+    const context = _CartUtils.conditionContext(catalog, order, currency);
+    let best;
+    for (const offer of (_a = catalog.offers) != null ? _a : []) {
+      if (offer.scope !== "Cart" || !OfferUtils.eligible(offer, context))
+        continue;
+      const value = _CartUtils.cartOfferValue(catalog, order, offer, currency, context);
+      if (value <= 0)
+        continue;
+      if (!best || value > best.value || value === best.value && offer.id === order.offerId)
+        best = { offer, value };
+    }
+    return best == null ? void 0 : best.offer;
+  }
+  /**
+   * What a cart offer would take off this cart, whether or not its condition is met yet.
+   *
+   * Computed on the same post-line-offer price `total` discounts, so "which offer do we attach" and
+   * "what does the cart actually save" can never disagree. Ranking on the list price instead would
+   * over-value an offer aimed at a line that already carries a steep offer of its own: 50% of a
+   * line discounted to a tenth of its price is worth less than 10% of a full-price one.
+   */
+  static cartOfferValue(catalog, order, offer, currency, context) {
+    const conditionContext = context != null ? context : _CartUtils.conditionContext(catalog, order, currency);
+    return order.items.reduce((aggregate, item) => {
+      if (!_CartUtils.cartOfferAppliesToLine(offer, item))
+        return aggregate;
+      const unitPrice = _CartUtils.unitPriceAfterItemOffer(catalog, item, currency, conditionContext);
+      return aggregate + DiscountUtils.apply(offer.discount, { [currency]: unitPrice })[currency] * item.quantity;
+    }, 0);
+  }
+  // A line's unit price once its own offer has come off, which is what a cart offer is applied to:
+  // the API discounts in the order product discount -> line offer -> cart offer -> coupons. An
+  // unresolvable price counts as zero, matching `total`'s "still render something" stance rather
+  // than `measure`'s "refuse to guess".
+  static unitPriceAfterItemOffer(catalog, item, currency, context) {
+    var _a, _b;
+    const unitPrice = (_a = _CartUtils.unitPrice(catalog, item, currency)) != null ? _a : 0;
+    const itemOffer = item.offerId ? (_b = catalog.offers) == null ? void 0 : _b.find((o) => o.id === item.offerId) : void 0;
+    if (!itemOffer || !OfferUtils.eligible(itemOffer, context))
+      return unitPrice;
+    return unitPrice - DiscountUtils.apply(itemOffer.discount, { [currency]: unitPrice })[currency];
+  }
+};
+
+// src/utils/image.ts
+var imageWidths = [16, 32, 48, 64, 96, 128, 192, 256, 384, 512, 768, 1024, 1536, 2048];
+var maxImageDimension = imageWidths[imageWidths.length - 1];
+var transformPathSegment = "_i";
+var maxCoverAspectRatio = 4;
+function isAssetUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (e) {
+    return false;
+  }
+  return parsed.hostname === "assets.moonbase.sh" || parsed.hostname.startsWith("assets.") && parsed.hostname.endsWith(".moonbase.sh");
+}
+function isRendition(url) {
+  try {
+    return new URL(url).pathname.startsWith(`/${transformPathSegment}/`);
+  } catch (e) {
+    return false;
+  }
+}
+function isTransformableImageUrl(url) {
+  return isAssetUrl(url) && !isRendition(url);
+}
+var warned = /* @__PURE__ */ new Set();
+function warnOnce(reason, url, message) {
+  const key = `${reason}:${url}`;
+  if (warned.has(key))
+    return;
+  warned.add(key);
+  console.warn(message, url);
+}
+function snap(value) {
+  var _a;
+  if (value === void 0 || !Number.isFinite(value) || value <= 0)
+    return void 0;
+  return (_a = imageWidths.find((width) => value <= width)) != null ? _a : maxImageDimension;
+}
+var ImageUtils = class _ImageUtils {
+  /**
+   * Rewrites an asset URL to ask the CDN for a rendition at the given size.
+   *
+   * Returns the URL untouched — never a broken one — when there is nothing to do: a URL that
+   * isn't a Moonbase asset, one that is already a rendition, an empty transform, or a `cover`
+   * crop too extreme for the CDN to serve. Callers can apply it unconditionally.
+   */
+  static transform(url, transform) {
+    if (!url)
+      return void 0;
+    if (!isAssetUrl(url)) {
+      warnOnce(
+        "host",
+        url,
+        "Only images hosted by Moonbase can be resized on the fly. Serving this one at its original size; host it in Moonbase, or size it yourself before uploading:"
+      );
+      return url;
+    }
+    if (isRendition(url))
+      return url;
+    const query = _ImageUtils.toQuery(transform);
+    if (query === null) {
+      warnOnce(
+        "aspect-ratio",
+        url,
+        `A 'cover' crop more lopsided than ${maxCoverAspectRatio}:1 is not served. Serving this image at its original size instead:`
+      );
+      return url;
+    }
+    if (query.length === 0)
+      return url;
+    const parsed = new URL(url);
+    const separator = parsed.search ? "&" : "?";
+    return `${parsed.origin}/${transformPathSegment}${parsed.pathname}${parsed.search}${separator}${query.map(([key, value]) => `${key}=${value}`).join("&")}`;
+  }
+  /**
+   * A `srcset` covering the given pixel densities, so a retina screen gets the sharper rendition
+   * without every screen paying for it. Pair it with a `src` built from the same transform.
+   */
+  static srcSet(url, transform, ...scales) {
+    if (!url || scales.length === 0)
+      return void 0;
+    return scales.map((scale) => `${_ImageUtils.transform(url, _ImageUtils.atScale(transform, scale))} ${scale}x`).join(", ");
+  }
+  /** The same transform at a different pixel density. */
+  static atScale(transform, scale) {
+    return {
+      ...transform,
+      width: transform.width === void 0 ? void 0 : transform.width * scale,
+      height: transform.height === void 0 ? void 0 : transform.height * scale
+    };
+  }
+  /**
+   * The query parameters for a transform, in the CDN's own order, with defaults left out so two
+   * equivalent transforms always produce the same URL — and therefore the same cache entry.
+   * `null` when the CDN would refuse the transform outright.
+   */
+  static toQuery(transform) {
+    var _a, _b;
+    const fit = (_a = transform.fit) != null ? _a : "contain";
+    const width = snap(transform.width);
+    const height = fit === "cover" ? (_b = snap(transform.height)) != null ? _b : width : snap(transform.height);
+    if (fit === "cover" && width && height) {
+      const ratio = width > height ? width / height : height / width;
+      if (ratio > maxCoverAspectRatio)
+        return null;
+    }
+    const query = [];
+    if (width)
+      query.push(["w", String(width)]);
+    if (height && (fit === "cover" || transform.height !== void 0))
+      query.push(["h", String(height)]);
+    if (fit !== "contain")
+      query.push(["fit", fit]);
+    if (transform.format)
+      query.push(["f", transform.format]);
+    return query;
+  }
+};
+
 // src/utils/utm.ts
 function parseOffSiteReferrer(rawReferrer, currentOrigin) {
   if (!rawReferrer)
@@ -1747,10 +2169,12 @@ export {
   ActivationRequestStatus,
   ActivationStatus,
   Architecture,
+  CartUtils,
   ConnectableAccountProvider,
   ConsoleLogger,
   CycleLength,
   DiscountUtils,
+  ImageUtils,
   InMemoryStore,
   LicenseStatus,
   LocalStorageStore,
@@ -1768,9 +2192,14 @@ export {
   Platform,
   SubscriptionStatus,
   TokenStore,
+  imageWidths,
+  isPromotionDisplay,
+  isTransformableImageUrl,
+  maxImageDimension,
   objectToQuery,
   parseOffSiteReferrer,
   problemDetailsSchema,
+  promotionDisplays,
   resolveUtm,
   schemas_exports12 as schemas,
   utmToObject

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonbase.sh/storefront-api",
   "type": "module",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Package to let you build storefronts with Moonbase.sh as payment and delivery provider",
   "author": "Tobias Lønnerød Madsen <m@dsen.tv>",
   "license": "MIT",