@moonbase.sh/storefront-api 3.0.0 → 3.1.0

package/dist/index.cjs

@@ -266,6 +266,10 @@ var productSummarySchema = import_zod2.z.object({
   releaseDescription: import_zod2.z.string().optional(),
   downloadsNeedsUser: import_zod2.z.boolean(),
   downloadsNeedsOwnership: import_zod2.z.boolean(),
+  downloadsNeedsGroupMembership: import_zod2.z.boolean(),
+  // Whether this caller clears every requirement above, including the group membership the client
+  // can't see for itself.
+  downloadsAllowed: import_zod2.z.boolean(),
   downloads: import_zod2.z.array(downloadSchema).optional()
 });
 
@@ -1430,6 +1434,9 @@ var OrderEndpoints = class {
       if (options.checkout.returnUrl) {
         query.append("returnUrl", options.checkout.returnUrl);
       }
+      if (options.checkout.embedded !== void 0) {
+        query.append("embedded", options.checkout.embedded ? "true" : "false");
+      }
     }
     const response = await this.api.fetch(`/api/customer/orders/${orderId}?${query.toString()}`, orderSchema, {
       abort: options == null ? void 0 : options.abort
@@ -1444,6 +1451,8 @@ var OrderEndpoints = class {
       query.checkout = "true";
       if (checkout.returnUrl)
         query.returnUrl = checkout.returnUrl;
+      if (checkout.embedded !== void 0)
+        query.embedded = checkout.embedded ? "true" : "false";
     }
     const response = await this.api.fetch(
       `/api/customer/orders/${order.id}?${new URLSearchParams(query).toString()}`,
@@ -1878,10 +1887,29 @@ var OfferUtils = class _OfferUtils {
   static relevantTargets(offer, cartItems) {
     if (offer.targets.length > 1) {
       const allOwned = offer.targets.every((t) => t.item.owned);
-      return offer.targets.filter((t) => (allOwned || !t.item.owned) && !cartItems.some((l) => l.type === t.item.type && t.item.id === (l.type === "Product" ? l.productId : l.bundleId)));
+      return offer.targets.filter((t) => (allOwned || !t.item.owned) && !_OfferUtils.targetInCart(t, cartItems));
     }
     return offer.targets;
   }
+  /**
+   * Whether every item an offer targets is already in the cart, so the offer has no upsell left to
+   * show.
+   *
+   * This is the set of offers the cart hides: a card inviting the buyer to add what they have already
+   * added says nothing, so it is dropped. Which makes it exactly the set whose discount nothing can
+   * currently claim: an offer is only good for one line, and there is no card left to spend it from.
+   *
+   * An offer with no targets names nothing and so is never in this set.
+   */
+  static allTargetsInCart(offer, cartItems) {
+    return offer.targets.length > 0 && offer.targets.every((target) => _OfferUtils.targetInCart(target, cartItems));
+  }
+  // Matched on the item alone, not the variation: a target narrowed to one variation still counts as
+  // in the cart when another variation of it is. That is the reading the cart's own upsell has always
+  // taken, and the two have to agree or an offer could be hidden and auto-applied at once.
+  static targetInCart(target, cartItems) {
+    return cartItems.some((l) => l.type === target.item.type && target.item.id === (l.type === "Product" ? l.productId : l.bundleId));
+  }
   // The pricing variations a target restricts the offer to. An empty (or missing) variation list
   // means the offer is not narrowed to specific variations, in which case we keep the established
   // single default-variation upsell.
@@ -1912,7 +1940,7 @@ var OfferUtils = class _OfferUtils {
 };
 
 // src/utils/cart.ts
-var CartUtils = class _CartUtils {
+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) {
@@ -1970,8 +1998,13 @@ var CartUtils = class _CartUtils {
   // 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.length === 0 || _CartUtils.offerTargetsLine(offer, item);
+  }
+  // Whether an offer names this line among its targets. An empty variation list on a target leaves
+  // the offer open to every variation of that item. An offer with no targets at all names nothing
+  // here, which is why the "every line" reading stays in `cartOfferAppliesToLine`: it is only true
+  // of a cart offer.
+  static offerTargetsLine(offer, item) {
     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
@@ -2048,6 +2081,148 @@ var CartUtils = class _CartUtils {
       return aggregate + DiscountUtils.apply(offer.discount, { [currency]: unitPrice })[currency] * item.quantity;
     }, 0);
   }
+  /**
+   * The item-scope offer worth attaching to a single line, or `undefined` when none is.
+   *
+   * Ranked by what it would actually take off this line rather than by percentage, the same way
+   * `bestCartOffer` ranks a cart: a flat amount off can beat a bigger-looking percentage on a cheap
+   * line, and the other way round on an expensive one.
+   *
+   * `unavailableOfferIds` are offers the rest of the cart has already claimed. An offer is only ever
+   * good for one line, since the cart treats an offer held by any line as in use. So a caller walking
+   * the cart must reserve each one as it goes, or two lines would both count on the same offer and
+   * the API would honour it once. `assignItemOffers` does that bookkeeping for a whole cart.
+   */
+  static bestItemOffer(catalog, item, currency, context, unavailableOfferIds) {
+    let best;
+    for (const candidate of _CartUtils.itemOfferCandidates(catalog, [item], currency, context, unavailableOfferIds)) {
+      if (!best || candidate.value > best.value)
+        best = candidate;
+    }
+    return best == null ? void 0 : best.offer;
+  }
+  /**
+   * Which item-scope offer to attach to which line, for the lines not already carrying one.
+   *
+   * Chosen for what the pairings are worth together rather than by cart order. An offer is only good
+   * for one line, so walking the cart and taking the best offer for each line in turn hands a
+   * multi-target offer to whichever line the buyer happened to add first, which is arbitrary and can
+   * be the cheapest one. A buyer claiming these from the upsell cards would have placed them where
+   * they are worth most, so that is what this does.
+   *
+   * Lines already holding an offer are left alone and their offers reserved: an offer on a line is
+   * intent, whether the buyer's from the upsell or the API's from a refreshed order, and this is not
+   * the place to second-guess it.
+   */
+  static assignItemOffers(catalog, order, currency, context) {
+    const conditionContext = context != null ? context : _CartUtils.conditionContext(catalog, order, currency);
+    const claimed = new Set(order.items.map((i) => i.offerId).filter((id) => !!id));
+    return _CartUtils.maximalItemOfferAssignment(
+      _CartUtils.itemOfferCandidates(catalog, order.items.filter((i) => !i.offerId), currency, conditionContext, claimed)
+    );
+  }
+  /**
+   * The pairings worth the most together, given each offer can only be spent once.
+   *
+   * Taking the most valuable pairing first is not enough: with one offer worth 100 on line A and 99 on
+   * line B, and a second offer worth 98 on line A alone, claiming the 100 strands the second offer and
+   * saves 100, where putting the first offer on B and the second on A saves 197. The pairings have to
+   * be chosen as a set.
+   *
+   * Walked line by line, memoised on which offers are still free. The candidates have already been
+   * through targeting and eligibility, so in a real cart there are a handful; past `searchableOffers`
+   * distinct offers it takes the most valuable pairing first instead, which is never worse than
+   * applying nothing.
+   */
+  static maximalItemOfferAssignment(candidates) {
+    var _a;
+    const optionsByItem = /* @__PURE__ */ new Map();
+    const offerBits = /* @__PURE__ */ new Map();
+    for (const { item, offer, value } of candidates) {
+      let bit = offerBits.get(offer.id);
+      if (bit === void 0) {
+        bit = offerBits.size;
+        offerBits.set(offer.id, bit);
+      }
+      const options = (_a = optionsByItem.get(item.id)) != null ? _a : [];
+      options.push({ offerId: offer.id, bit, value });
+      optionsByItem.set(item.id, options);
+    }
+    if (offerBits.size > _CartUtils.searchableOffers)
+      return _CartUtils.mostValuableItemOfferPairings(candidates);
+    const itemIds = [...optionsByItem.keys()];
+    const memo = /* @__PURE__ */ new Map();
+    const from = (index, spent) => {
+      var _a2;
+      if (index >= itemIds.length)
+        return { value: 0, assignments: [] };
+      const key = `${index}:${spent}`;
+      const memoised = memo.get(key);
+      if (memoised)
+        return memoised;
+      let best = from(index + 1, spent);
+      const itemId = itemIds[index];
+      for (const option of (_a2 = optionsByItem.get(itemId)) != null ? _a2 : []) {
+        if (spent & 1 << option.bit)
+          continue;
+        const rest = from(index + 1, spent | 1 << option.bit);
+        const value = option.value + rest.value;
+        if (value > best.value)
+          best = { value, assignments: [{ itemId, offerId: option.offerId }, ...rest.assignments] };
+      }
+      memo.set(key, best);
+      return best;
+    };
+    return from(0, 0).assignments;
+  }
+  // The fallback for a candidate set too large to search: repeatedly take the most valuable pairing
+  // still available. Can strand a better combination, which is the whole reason it is only a fallback.
+  static mostValuableItemOfferPairings(candidates) {
+    const assignments = [];
+    const assignedItemIds = /* @__PURE__ */ new Set();
+    const spentOfferIds = /* @__PURE__ */ new Set();
+    for (const { item, offer } of [...candidates].sort((a, b) => b.value - a.value)) {
+      if (assignedItemIds.has(item.id) || spentOfferIds.has(offer.id))
+        continue;
+      assignedItemIds.add(item.id);
+      spentOfferIds.add(offer.id);
+      assignments.push({ itemId: item.id, offerId: offer.id });
+    }
+    return assignments;
+  }
+  // Every line-and-offer pairing the cart could make, and what each would save. Enumerated in cart
+  // order and then catalog order, which `sort` preserves for equal savings, so an unchanged cart
+  // always resolves the same way.
+  static itemOfferCandidates(catalog, items, currency, context, unavailableOfferIds) {
+    var _a;
+    const candidates = [];
+    for (const item of items) {
+      const unitPrice = _CartUtils.unitPrice(catalog, item, currency);
+      if (unitPrice === void 0)
+        continue;
+      for (const offer of (_a = catalog.offers) != null ? _a : []) {
+        if (offer.scope === "Cart" || (unavailableOfferIds == null ? void 0 : unavailableOfferIds.has(offer.id)))
+          continue;
+        if (!_CartUtils.offerTargetsLine(offer, item))
+          continue;
+        if (!OfferUtils.allTargetsInCart(offer, context.order.items))
+          continue;
+        if (!OfferUtils.eligible(offer, context))
+          continue;
+        const value = _CartUtils.itemOfferUnitDiscount(offer, unitPrice, currency) * item.quantity;
+        if (value <= 0)
+          continue;
+        candidates.push({ item, offer, value });
+      }
+    }
+    return candidates;
+  }
+  // What an item offer takes off one unit of a line. Measured off the post-product-discount price,
+  // which is what an item offer comes off in the API's order: product discount -> line offer -> cart
+  // offer -> coupons.
+  static itemOfferUnitDiscount(offer, unitPrice, currency) {
+    return DiscountUtils.apply(offer.discount, { [currency]: unitPrice })[currency];
+  }
   // 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
@@ -2058,9 +2233,14 @@ var CartUtils = class _CartUtils {
     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];
+    return unitPrice - _CartUtils.itemOfferUnitDiscount(itemOffer, unitPrice, currency);
   }
 };
+// How many distinct offers can compete for the same cart before the exact search is given up on.
+// 12 leaves 4096 states per line, which is nothing, and no real storefront has a dozen item offers
+// eligible against one cart at once.
+_CartUtils.searchableOffers = 12;
+var CartUtils = _CartUtils;
 
 // src/utils/image.ts
 var imageWidths = [16, 32, 48, 64, 96, 128, 192, 256, 384, 512, 768, 1024, 1536, 2048];

package/dist/index.d.cts

@@ -1682,6 +1682,8 @@ declare const licenseSchema: z.ZodObject<{
         releaseDescription: z.ZodOptional<z.ZodString>;
         downloadsNeedsUser: z.ZodBoolean;
         downloadsNeedsOwnership: z.ZodBoolean;
+        downloadsNeedsGroupMembership: z.ZodBoolean;
+        downloadsAllowed: z.ZodBoolean;
         downloads: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             key: z.ZodString;
@@ -1749,6 +1751,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -1783,6 +1787,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -1850,6 +1856,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -1903,6 +1911,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -2450,6 +2460,8 @@ declare const productSummarySchema: z.ZodObject<{
     releaseDescription: z.ZodOptional<z.ZodString>;
     downloadsNeedsUser: z.ZodBoolean;
     downloadsNeedsOwnership: z.ZodBoolean;
+    downloadsNeedsGroupMembership: z.ZodBoolean;
+    downloadsAllowed: z.ZodBoolean;
     downloads: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         key: z.ZodString;
@@ -2517,6 +2529,8 @@ declare const productSummarySchema: z.ZodObject<{
     currentVersion: string | null;
     downloadsNeedsUser: boolean;
     downloadsNeedsOwnership: boolean;
+    downloadsNeedsGroupMembership: boolean;
+    downloadsAllowed: boolean;
     description?: string | null | undefined;
     tagline?: string | null | undefined;
     website?: string | undefined;
@@ -2551,6 +2565,8 @@ declare const productSummarySchema: z.ZodObject<{
     currentVersion: string | null;
     downloadsNeedsUser: boolean;
     downloadsNeedsOwnership: boolean;
+    downloadsNeedsGroupMembership: boolean;
+    downloadsAllowed: boolean;
     description?: string | null | undefined;
     tagline?: string | null | undefined;
     website?: string | undefined;
@@ -22703,15 +22719,25 @@ type LineItem = z.infer<typeof openOrderLineItem>;
 type ProductLineItem = z.infer<typeof openProductLineItem>;
 type BundleLineItem = z.infer<typeof openBundleLineItem>;
 
+interface CheckoutUrlOptions {
+    /** Where to send the buyer once the checkout is done with them. */
+    returnUrl?: string;
+    /**
+     * Whether checkout will be rendered in the overlay iframe rather than as a
+     * full-page redirect. Tells the backend whether a checkout login token is
+     * worth minting: the returned `hostedCheckoutUrl` only carries one when this
+     * is not `false`. Say `false` whenever you intend to redirect, so a day-long
+     * credential is never minted for a URL that will not use it.
+     */
+    embedded?: boolean;
+}
 declare class OrderEndpoints {
     private api;
     constructor(api: MoonbaseApi);
     get(orderId: string, options?: {
         abort?: AbortSignal;
         finalize?: boolean;
-        checkout?: {
-            returnUrl?: string;
-        };
+        checkout?: CheckoutUrlOptions;
     }): Promise<{
         id: string;
         status: OrderStatus.Completed;
@@ -24102,9 +24128,7 @@ declare class OrderEndpoints {
             offerId?: string;
             replaced?: string[];
         })[];
-    }, checkout?: {
-        returnUrl?: string;
-    }, utm?: UrchinTrackingModule): Promise<OpenOrder>;
+    }, checkout?: CheckoutUrlOptions, utm?: UrchinTrackingModule): Promise<OpenOrder>;
     addBillingDetails(orderId: string, details: {
         name: string;
         email: string;
@@ -46733,6 +46757,18 @@ declare class OfferUtils {
     static progress(offer: StorefrontOffer, context: Order | OfferConditionContext): OfferProgress | null;
     private static evaluate;
     static relevantTargets(offer: StorefrontOffer, cartItems: LineItem[]): StorefrontOfferTarget[];
+    /**
+     * Whether every item an offer targets is already in the cart, so the offer has no upsell left to
+     * show.
+     *
+     * This is the set of offers the cart hides: a card inviting the buyer to add what they have already
+     * added says nothing, so it is dropped. Which makes it exactly the set whose discount nothing can
+     * currently claim: an offer is only good for one line, and there is no card left to spend it from.
+     *
+     * An offer with no targets names nothing and so is never in this set.
+     */
+    static allTargetsInCart(offer: StorefrontOffer, cartItems: LineItem[]): boolean;
+    private static targetInCart;
     static targetedVariations(target: StorefrontOfferTarget): PricingVariation[];
     static relevantTargetVariations(offer: StorefrontOffer, cartItems: LineItem[]): {
         target: StorefrontProduct | StorefrontBundle;
@@ -46764,6 +46800,7 @@ declare class CartUtils {
     static measure(catalog: CartCatalog, items: LineItem[], currency: string): Money | undefined;
     static conditionContext(catalog: CartCatalog, order: CartOrder, currency: string): OfferConditionContext;
     static cartOfferAppliesToLine(offer: StorefrontOffer, item: LineItem): boolean;
+    static offerTargetsLine(offer: StorefrontOffer, item: LineItem): boolean;
     static appliedCartOffer(catalog: CartCatalog, order: CartOrder, context: OfferConditionContext): StorefrontOffer | undefined;
     static total(catalog: CartCatalog, order: CartOrder, currency: string): CartTotal;
     static bestCartOffer(catalog: CartCatalog, order: CartOrder, currency: string): StorefrontOffer | undefined;
@@ -46776,6 +46813,54 @@ declare class CartUtils {
      * line discounted to a tenth of its price is worth less than 10% of a full-price one.
      */
     static cartOfferValue(catalog: CartCatalog, order: CartOrder, offer: StorefrontOffer, currency: string, context?: OfferConditionContext): number;
+    /**
+     * The item-scope offer worth attaching to a single line, or `undefined` when none is.
+     *
+     * Ranked by what it would actually take off this line rather than by percentage, the same way
+     * `bestCartOffer` ranks a cart: a flat amount off can beat a bigger-looking percentage on a cheap
+     * line, and the other way round on an expensive one.
+     *
+     * `unavailableOfferIds` are offers the rest of the cart has already claimed. An offer is only ever
+     * good for one line, since the cart treats an offer held by any line as in use. So a caller walking
+     * the cart must reserve each one as it goes, or two lines would both count on the same offer and
+     * the API would honour it once. `assignItemOffers` does that bookkeeping for a whole cart.
+     */
+    static bestItemOffer(catalog: CartCatalog, item: LineItem, currency: string, context: OfferConditionContext, unavailableOfferIds?: ReadonlySet<string>): StorefrontOffer | undefined;
+    /**
+     * Which item-scope offer to attach to which line, for the lines not already carrying one.
+     *
+     * Chosen for what the pairings are worth together rather than by cart order. An offer is only good
+     * for one line, so walking the cart and taking the best offer for each line in turn hands a
+     * multi-target offer to whichever line the buyer happened to add first, which is arbitrary and can
+     * be the cheapest one. A buyer claiming these from the upsell cards would have placed them where
+     * they are worth most, so that is what this does.
+     *
+     * Lines already holding an offer are left alone and their offers reserved: an offer on a line is
+     * intent, whether the buyer's from the upsell or the API's from a refreshed order, and this is not
+     * the place to second-guess it.
+     */
+    static assignItemOffers(catalog: CartCatalog, order: CartOrder, currency: string, context?: OfferConditionContext): {
+        itemId: string;
+        offerId: string;
+    }[];
+    /**
+     * The pairings worth the most together, given each offer can only be spent once.
+     *
+     * Taking the most valuable pairing first is not enough: with one offer worth 100 on line A and 99 on
+     * line B, and a second offer worth 98 on line A alone, claiming the 100 strands the second offer and
+     * saves 100, where putting the first offer on B and the second on A saves 197. The pairings have to
+     * be chosen as a set.
+     *
+     * Walked line by line, memoised on which offers are still free. The candidates have already been
+     * through targeting and eligibility, so in a real cart there are a handful; past `searchableOffers`
+     * distinct offers it takes the most valuable pairing first instead, which is never worse than
+     * applying nothing.
+     */
+    private static maximalItemOfferAssignment;
+    private static mostValuableItemOfferPairings;
+    private static readonly searchableOffers;
+    private static itemOfferCandidates;
+    private static itemOfferUnitDiscount;
     private static unitPriceAfterItemOffer;
 }
 

package/dist/index.d.ts

@@ -1682,6 +1682,8 @@ declare const licenseSchema: z.ZodObject<{
         releaseDescription: z.ZodOptional<z.ZodString>;
         downloadsNeedsUser: z.ZodBoolean;
         downloadsNeedsOwnership: z.ZodBoolean;
+        downloadsNeedsGroupMembership: z.ZodBoolean;
+        downloadsAllowed: z.ZodBoolean;
         downloads: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             key: z.ZodString;
@@ -1749,6 +1751,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -1783,6 +1787,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -1850,6 +1856,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -1903,6 +1911,8 @@ declare const licenseSchema: z.ZodObject<{
         currentVersion: string | null;
         downloadsNeedsUser: boolean;
         downloadsNeedsOwnership: boolean;
+        downloadsNeedsGroupMembership: boolean;
+        downloadsAllowed: boolean;
         description?: string | null | undefined;
         tagline?: string | null | undefined;
         website?: string | undefined;
@@ -2450,6 +2460,8 @@ declare const productSummarySchema: z.ZodObject<{
     releaseDescription: z.ZodOptional<z.ZodString>;
     downloadsNeedsUser: z.ZodBoolean;
     downloadsNeedsOwnership: z.ZodBoolean;
+    downloadsNeedsGroupMembership: z.ZodBoolean;
+    downloadsAllowed: z.ZodBoolean;
     downloads: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         key: z.ZodString;
@@ -2517,6 +2529,8 @@ declare const productSummarySchema: z.ZodObject<{
     currentVersion: string | null;
     downloadsNeedsUser: boolean;
     downloadsNeedsOwnership: boolean;
+    downloadsNeedsGroupMembership: boolean;
+    downloadsAllowed: boolean;
     description?: string | null | undefined;
     tagline?: string | null | undefined;
     website?: string | undefined;
@@ -2551,6 +2565,8 @@ declare const productSummarySchema: z.ZodObject<{
     currentVersion: string | null;
     downloadsNeedsUser: boolean;
     downloadsNeedsOwnership: boolean;
+    downloadsNeedsGroupMembership: boolean;
+    downloadsAllowed: boolean;
     description?: string | null | undefined;
     tagline?: string | null | undefined;
     website?: string | undefined;
@@ -22703,15 +22719,25 @@ type LineItem = z.infer<typeof openOrderLineItem>;
 type ProductLineItem = z.infer<typeof openProductLineItem>;
 type BundleLineItem = z.infer<typeof openBundleLineItem>;
 
+interface CheckoutUrlOptions {
+    /** Where to send the buyer once the checkout is done with them. */
+    returnUrl?: string;
+    /**
+     * Whether checkout will be rendered in the overlay iframe rather than as a
+     * full-page redirect. Tells the backend whether a checkout login token is
+     * worth minting: the returned `hostedCheckoutUrl` only carries one when this
+     * is not `false`. Say `false` whenever you intend to redirect, so a day-long
+     * credential is never minted for a URL that will not use it.
+     */
+    embedded?: boolean;
+}
 declare class OrderEndpoints {
     private api;
     constructor(api: MoonbaseApi);
     get(orderId: string, options?: {
         abort?: AbortSignal;
         finalize?: boolean;
-        checkout?: {
-            returnUrl?: string;
-        };
+        checkout?: CheckoutUrlOptions;
     }): Promise<{
         id: string;
         status: OrderStatus.Completed;
@@ -24102,9 +24128,7 @@ declare class OrderEndpoints {
             offerId?: string;
             replaced?: string[];
         })[];
-    }, checkout?: {
-        returnUrl?: string;
-    }, utm?: UrchinTrackingModule): Promise<OpenOrder>;
+    }, checkout?: CheckoutUrlOptions, utm?: UrchinTrackingModule): Promise<OpenOrder>;
     addBillingDetails(orderId: string, details: {
         name: string;
         email: string;
@@ -46733,6 +46757,18 @@ declare class OfferUtils {
     static progress(offer: StorefrontOffer, context: Order | OfferConditionContext): OfferProgress | null;
     private static evaluate;
     static relevantTargets(offer: StorefrontOffer, cartItems: LineItem[]): StorefrontOfferTarget[];
+    /**
+     * Whether every item an offer targets is already in the cart, so the offer has no upsell left to
+     * show.
+     *
+     * This is the set of offers the cart hides: a card inviting the buyer to add what they have already
+     * added says nothing, so it is dropped. Which makes it exactly the set whose discount nothing can
+     * currently claim: an offer is only good for one line, and there is no card left to spend it from.
+     *
+     * An offer with no targets names nothing and so is never in this set.
+     */
+    static allTargetsInCart(offer: StorefrontOffer, cartItems: LineItem[]): boolean;
+    private static targetInCart;
     static targetedVariations(target: StorefrontOfferTarget): PricingVariation[];
     static relevantTargetVariations(offer: StorefrontOffer, cartItems: LineItem[]): {
         target: StorefrontProduct | StorefrontBundle;
@@ -46764,6 +46800,7 @@ declare class CartUtils {
     static measure(catalog: CartCatalog, items: LineItem[], currency: string): Money | undefined;
     static conditionContext(catalog: CartCatalog, order: CartOrder, currency: string): OfferConditionContext;
     static cartOfferAppliesToLine(offer: StorefrontOffer, item: LineItem): boolean;
+    static offerTargetsLine(offer: StorefrontOffer, item: LineItem): boolean;
     static appliedCartOffer(catalog: CartCatalog, order: CartOrder, context: OfferConditionContext): StorefrontOffer | undefined;
     static total(catalog: CartCatalog, order: CartOrder, currency: string): CartTotal;
     static bestCartOffer(catalog: CartCatalog, order: CartOrder, currency: string): StorefrontOffer | undefined;
@@ -46776,6 +46813,54 @@ declare class CartUtils {
      * line discounted to a tenth of its price is worth less than 10% of a full-price one.
      */
     static cartOfferValue(catalog: CartCatalog, order: CartOrder, offer: StorefrontOffer, currency: string, context?: OfferConditionContext): number;
+    /**
+     * The item-scope offer worth attaching to a single line, or `undefined` when none is.
+     *
+     * Ranked by what it would actually take off this line rather than by percentage, the same way
+     * `bestCartOffer` ranks a cart: a flat amount off can beat a bigger-looking percentage on a cheap
+     * line, and the other way round on an expensive one.
+     *
+     * `unavailableOfferIds` are offers the rest of the cart has already claimed. An offer is only ever
+     * good for one line, since the cart treats an offer held by any line as in use. So a caller walking
+     * the cart must reserve each one as it goes, or two lines would both count on the same offer and
+     * the API would honour it once. `assignItemOffers` does that bookkeeping for a whole cart.
+     */
+    static bestItemOffer(catalog: CartCatalog, item: LineItem, currency: string, context: OfferConditionContext, unavailableOfferIds?: ReadonlySet<string>): StorefrontOffer | undefined;
+    /**
+     * Which item-scope offer to attach to which line, for the lines not already carrying one.
+     *
+     * Chosen for what the pairings are worth together rather than by cart order. An offer is only good
+     * for one line, so walking the cart and taking the best offer for each line in turn hands a
+     * multi-target offer to whichever line the buyer happened to add first, which is arbitrary and can
+     * be the cheapest one. A buyer claiming these from the upsell cards would have placed them where
+     * they are worth most, so that is what this does.
+     *
+     * Lines already holding an offer are left alone and their offers reserved: an offer on a line is
+     * intent, whether the buyer's from the upsell or the API's from a refreshed order, and this is not
+     * the place to second-guess it.
+     */
+    static assignItemOffers(catalog: CartCatalog, order: CartOrder, currency: string, context?: OfferConditionContext): {
+        itemId: string;
+        offerId: string;
+    }[];
+    /**
+     * The pairings worth the most together, given each offer can only be spent once.
+     *
+     * Taking the most valuable pairing first is not enough: with one offer worth 100 on line A and 99 on
+     * line B, and a second offer worth 98 on line A alone, claiming the 100 strands the second offer and
+     * saves 100, where putting the first offer on B and the second on A saves 197. The pairings have to
+     * be chosen as a set.
+     *
+     * Walked line by line, memoised on which offers are still free. The candidates have already been
+     * through targeting and eligibility, so in a real cart there are a handful; past `searchableOffers`
+     * distinct offers it takes the most valuable pairing first instead, which is never worse than
+     * applying nothing.
+     */
+    private static maximalItemOfferAssignment;
+    private static mostValuableItemOfferPairings;
+    private static readonly searchableOffers;
+    private static itemOfferCandidates;
+    private static itemOfferUnitDiscount;
     private static unitPriceAfterItemOffer;
 }
 

package/dist/index.js

@@ -208,6 +208,10 @@ var productSummarySchema = z2.object({
   releaseDescription: z2.string().optional(),
   downloadsNeedsUser: z2.boolean(),
   downloadsNeedsOwnership: z2.boolean(),
+  downloadsNeedsGroupMembership: z2.boolean(),
+  // Whether this caller clears every requirement above, including the group membership the client
+  // can't see for itself.
+  downloadsAllowed: z2.boolean(),
   downloads: z2.array(downloadSchema).optional()
 });
 
@@ -1372,6 +1376,9 @@ var OrderEndpoints = class {
       if (options.checkout.returnUrl) {
         query.append("returnUrl", options.checkout.returnUrl);
       }
+      if (options.checkout.embedded !== void 0) {
+        query.append("embedded", options.checkout.embedded ? "true" : "false");
+      }
     }
     const response = await this.api.fetch(`/api/customer/orders/${orderId}?${query.toString()}`, orderSchema, {
       abort: options == null ? void 0 : options.abort
@@ -1386,6 +1393,8 @@ var OrderEndpoints = class {
       query.checkout = "true";
       if (checkout.returnUrl)
         query.returnUrl = checkout.returnUrl;
+      if (checkout.embedded !== void 0)
+        query.embedded = checkout.embedded ? "true" : "false";
     }
     const response = await this.api.fetch(
       `/api/customer/orders/${order.id}?${new URLSearchParams(query).toString()}`,
@@ -1820,10 +1829,29 @@ var OfferUtils = class _OfferUtils {
   static relevantTargets(offer, cartItems) {
     if (offer.targets.length > 1) {
       const allOwned = offer.targets.every((t) => t.item.owned);
-      return offer.targets.filter((t) => (allOwned || !t.item.owned) && !cartItems.some((l) => l.type === t.item.type && t.item.id === (l.type === "Product" ? l.productId : l.bundleId)));
+      return offer.targets.filter((t) => (allOwned || !t.item.owned) && !_OfferUtils.targetInCart(t, cartItems));
     }
     return offer.targets;
   }
+  /**
+   * Whether every item an offer targets is already in the cart, so the offer has no upsell left to
+   * show.
+   *
+   * This is the set of offers the cart hides: a card inviting the buyer to add what they have already
+   * added says nothing, so it is dropped. Which makes it exactly the set whose discount nothing can
+   * currently claim: an offer is only good for one line, and there is no card left to spend it from.
+   *
+   * An offer with no targets names nothing and so is never in this set.
+   */
+  static allTargetsInCart(offer, cartItems) {
+    return offer.targets.length > 0 && offer.targets.every((target) => _OfferUtils.targetInCart(target, cartItems));
+  }
+  // Matched on the item alone, not the variation: a target narrowed to one variation still counts as
+  // in the cart when another variation of it is. That is the reading the cart's own upsell has always
+  // taken, and the two have to agree or an offer could be hidden and auto-applied at once.
+  static targetInCart(target, cartItems) {
+    return cartItems.some((l) => l.type === target.item.type && target.item.id === (l.type === "Product" ? l.productId : l.bundleId));
+  }
   // The pricing variations a target restricts the offer to. An empty (or missing) variation list
   // means the offer is not narrowed to specific variations, in which case we keep the established
   // single default-variation upsell.
@@ -1854,7 +1882,7 @@ var OfferUtils = class _OfferUtils {
 };
 
 // src/utils/cart.ts
-var CartUtils = class _CartUtils {
+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) {
@@ -1912,8 +1940,13 @@ var CartUtils = class _CartUtils {
   // 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.length === 0 || _CartUtils.offerTargetsLine(offer, item);
+  }
+  // Whether an offer names this line among its targets. An empty variation list on a target leaves
+  // the offer open to every variation of that item. An offer with no targets at all names nothing
+  // here, which is why the "every line" reading stays in `cartOfferAppliesToLine`: it is only true
+  // of a cart offer.
+  static offerTargetsLine(offer, item) {
     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
@@ -1990,6 +2023,148 @@ var CartUtils = class _CartUtils {
       return aggregate + DiscountUtils.apply(offer.discount, { [currency]: unitPrice })[currency] * item.quantity;
     }, 0);
   }
+  /**
+   * The item-scope offer worth attaching to a single line, or `undefined` when none is.
+   *
+   * Ranked by what it would actually take off this line rather than by percentage, the same way
+   * `bestCartOffer` ranks a cart: a flat amount off can beat a bigger-looking percentage on a cheap
+   * line, and the other way round on an expensive one.
+   *
+   * `unavailableOfferIds` are offers the rest of the cart has already claimed. An offer is only ever
+   * good for one line, since the cart treats an offer held by any line as in use. So a caller walking
+   * the cart must reserve each one as it goes, or two lines would both count on the same offer and
+   * the API would honour it once. `assignItemOffers` does that bookkeeping for a whole cart.
+   */
+  static bestItemOffer(catalog, item, currency, context, unavailableOfferIds) {
+    let best;
+    for (const candidate of _CartUtils.itemOfferCandidates(catalog, [item], currency, context, unavailableOfferIds)) {
+      if (!best || candidate.value > best.value)
+        best = candidate;
+    }
+    return best == null ? void 0 : best.offer;
+  }
+  /**
+   * Which item-scope offer to attach to which line, for the lines not already carrying one.
+   *
+   * Chosen for what the pairings are worth together rather than by cart order. An offer is only good
+   * for one line, so walking the cart and taking the best offer for each line in turn hands a
+   * multi-target offer to whichever line the buyer happened to add first, which is arbitrary and can
+   * be the cheapest one. A buyer claiming these from the upsell cards would have placed them where
+   * they are worth most, so that is what this does.
+   *
+   * Lines already holding an offer are left alone and their offers reserved: an offer on a line is
+   * intent, whether the buyer's from the upsell or the API's from a refreshed order, and this is not
+   * the place to second-guess it.
+   */
+  static assignItemOffers(catalog, order, currency, context) {
+    const conditionContext = context != null ? context : _CartUtils.conditionContext(catalog, order, currency);
+    const claimed = new Set(order.items.map((i) => i.offerId).filter((id) => !!id));
+    return _CartUtils.maximalItemOfferAssignment(
+      _CartUtils.itemOfferCandidates(catalog, order.items.filter((i) => !i.offerId), currency, conditionContext, claimed)
+    );
+  }
+  /**
+   * The pairings worth the most together, given each offer can only be spent once.
+   *
+   * Taking the most valuable pairing first is not enough: with one offer worth 100 on line A and 99 on
+   * line B, and a second offer worth 98 on line A alone, claiming the 100 strands the second offer and
+   * saves 100, where putting the first offer on B and the second on A saves 197. The pairings have to
+   * be chosen as a set.
+   *
+   * Walked line by line, memoised on which offers are still free. The candidates have already been
+   * through targeting and eligibility, so in a real cart there are a handful; past `searchableOffers`
+   * distinct offers it takes the most valuable pairing first instead, which is never worse than
+   * applying nothing.
+   */
+  static maximalItemOfferAssignment(candidates) {
+    var _a;
+    const optionsByItem = /* @__PURE__ */ new Map();
+    const offerBits = /* @__PURE__ */ new Map();
+    for (const { item, offer, value } of candidates) {
+      let bit = offerBits.get(offer.id);
+      if (bit === void 0) {
+        bit = offerBits.size;
+        offerBits.set(offer.id, bit);
+      }
+      const options = (_a = optionsByItem.get(item.id)) != null ? _a : [];
+      options.push({ offerId: offer.id, bit, value });
+      optionsByItem.set(item.id, options);
+    }
+    if (offerBits.size > _CartUtils.searchableOffers)
+      return _CartUtils.mostValuableItemOfferPairings(candidates);
+    const itemIds = [...optionsByItem.keys()];
+    const memo = /* @__PURE__ */ new Map();
+    const from = (index, spent) => {
+      var _a2;
+      if (index >= itemIds.length)
+        return { value: 0, assignments: [] };
+      const key = `${index}:${spent}`;
+      const memoised = memo.get(key);
+      if (memoised)
+        return memoised;
+      let best = from(index + 1, spent);
+      const itemId = itemIds[index];
+      for (const option of (_a2 = optionsByItem.get(itemId)) != null ? _a2 : []) {
+        if (spent & 1 << option.bit)
+          continue;
+        const rest = from(index + 1, spent | 1 << option.bit);
+        const value = option.value + rest.value;
+        if (value > best.value)
+          best = { value, assignments: [{ itemId, offerId: option.offerId }, ...rest.assignments] };
+      }
+      memo.set(key, best);
+      return best;
+    };
+    return from(0, 0).assignments;
+  }
+  // The fallback for a candidate set too large to search: repeatedly take the most valuable pairing
+  // still available. Can strand a better combination, which is the whole reason it is only a fallback.
+  static mostValuableItemOfferPairings(candidates) {
+    const assignments = [];
+    const assignedItemIds = /* @__PURE__ */ new Set();
+    const spentOfferIds = /* @__PURE__ */ new Set();
+    for (const { item, offer } of [...candidates].sort((a, b) => b.value - a.value)) {
+      if (assignedItemIds.has(item.id) || spentOfferIds.has(offer.id))
+        continue;
+      assignedItemIds.add(item.id);
+      spentOfferIds.add(offer.id);
+      assignments.push({ itemId: item.id, offerId: offer.id });
+    }
+    return assignments;
+  }
+  // Every line-and-offer pairing the cart could make, and what each would save. Enumerated in cart
+  // order and then catalog order, which `sort` preserves for equal savings, so an unchanged cart
+  // always resolves the same way.
+  static itemOfferCandidates(catalog, items, currency, context, unavailableOfferIds) {
+    var _a;
+    const candidates = [];
+    for (const item of items) {
+      const unitPrice = _CartUtils.unitPrice(catalog, item, currency);
+      if (unitPrice === void 0)
+        continue;
+      for (const offer of (_a = catalog.offers) != null ? _a : []) {
+        if (offer.scope === "Cart" || (unavailableOfferIds == null ? void 0 : unavailableOfferIds.has(offer.id)))
+          continue;
+        if (!_CartUtils.offerTargetsLine(offer, item))
+          continue;
+        if (!OfferUtils.allTargetsInCart(offer, context.order.items))
+          continue;
+        if (!OfferUtils.eligible(offer, context))
+          continue;
+        const value = _CartUtils.itemOfferUnitDiscount(offer, unitPrice, currency) * item.quantity;
+        if (value <= 0)
+          continue;
+        candidates.push({ item, offer, value });
+      }
+    }
+    return candidates;
+  }
+  // What an item offer takes off one unit of a line. Measured off the post-product-discount price,
+  // which is what an item offer comes off in the API's order: product discount -> line offer -> cart
+  // offer -> coupons.
+  static itemOfferUnitDiscount(offer, unitPrice, currency) {
+    return DiscountUtils.apply(offer.discount, { [currency]: unitPrice })[currency];
+  }
   // 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
@@ -2000,9 +2175,14 @@ var CartUtils = class _CartUtils {
     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];
+    return unitPrice - _CartUtils.itemOfferUnitDiscount(itemOffer, unitPrice, currency);
   }
 };
+// How many distinct offers can compete for the same cart before the exact search is given up on.
+// 12 leaves 4096 states per line, which is nothing, and no real storefront has a dozen item offers
+// eligible against one cart at once.
+_CartUtils.searchableOffers = 12;
+var CartUtils = _CartUtils;
 
 // src/utils/image.ts
 var imageWidths = [16, 32, 48, 64, 96, 128, 192, 256, 384, 512, 768, 1024, 1536, 2048];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonbase.sh/storefront-api",
   "type": "module",
-  "version": "3.0.0",
+  "version": "3.1.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",