@rebuy/rebuy 3.16.3 → 3.17.0

package/dist/server/index.d.ts

@@ -14,5 +14,5 @@ export { fetchUserConfig } from '../server/userConfig';
 export { validateGifts } from '../server/giftValidation';
 export { fetchMonetizeOffers, type MonetizeOffers } from '../server/monetizeOffers';
 export { postAnalyticsEvents, translateAnalyticsEvent, type CabAnalyticsEventName } from '../server/analytics';
-export { AnalyticsEventInputSchema, AnalyticsInputSchema, CartInputSchema, CartLineInputSchema, DataSourceInputSchema, GiftInputSchema, GiftValidationInputSchema, MonetizeInputSchema, MonetizeTransactionItemSchema, REQUEST_BOUNDS, UserConfigInputSchema, WidgetSettingsInputSchema, } from '../server/requestSchemas';
-export { NotFoundError, REBUY_ENGINE_HOST, UpstreamError, type AnalyticsEventInput, type AnalyticsInput, type CartInput, type CartLineInput, type DataSourceInput, type GiftInput, type GiftValidationInput, type MonetizeInput, type MonetizeTransactionItem, type ServerContext, type ServerDrift, type UpstreamFetch, type UserConfigInput, type WidgetSettingsInput, } from '../server/shared';
+export { AnalyticsEventInputSchema, AnalyticsInputSchema, CartInputSchema, CartLineInputSchema, DataSourceInputSchema, GiftAdjustmentSchema, GiftInputSchema, GiftValidationInputSchema, GiftValidationResponseSchema, MonetizeInputSchema, MonetizeTransactionItemSchema, REQUEST_BOUNDS, UserConfigInputSchema, WidgetSettingsInputSchema, } from '../server/requestSchemas';
+export { NotFoundError, REBUY_ENGINE_HOST, UpstreamError, type AnalyticsEventInput, type AnalyticsInput, type CartInput, type CartLineInput, type DataSourceInput, type GiftAdjustment, type GiftInput, type GiftValidationInput, type GiftValidationResponse, type MonetizeInput, type MonetizeTransactionItem, type ServerContext, type ServerDrift, type UpstreamFetch, type UserConfigInput, type WidgetSettingsInput, } from '../server/shared';

package/dist/server/index.mjs

@@ -23,6 +23,9 @@ var isDefinitiveRuleAnswer = (metadata) => metadata != null && (metadata.matched
 var hasLostDiscount = (gift) => !gift.discounted && gift.cost > 0;
 var shouldRemoveGift = (gift, validIds) => !validIds.has(gift.productId) || hasLostDiscount(gift);
 
+// src/gwp/types.ts
+var GIFT_KINDS = ["gwp", "sgwp"];
+
 // src/schema/metadata.ts
 import { z as z2 } from "zod";
 
@@ -382,6 +385,14 @@ var NotFoundError = class extends Error {
   }
 };
 
+// src/server/shopSubtotal.ts
+var shopCurrencyRate = (cart) => {
+  const rate = cart.currencyRate ?? 1;
+  return Number.isFinite(rate) && rate > 0 ? rate : 1;
+};
+var shopSubtotalCents = (cart) => Math.round((cart.subtotal - (cart.discountTotal ?? 0)) / shopCurrencyRate(cart));
+var toShopCents = (majorPresentment, rate) => Math.round(majorPresentment * 100 / rate);
+
 // src/schema/cabShopConfig.ts
 import { z as z6 } from "zod";
 
@@ -3875,9 +3886,7 @@ var buildEngineParams = (input, key) => {
     variant_id: variantId
   }));
   const itemCount = cart.items.reduce((total, { quantity }) => total + quantity, 0);
-  const currencyRate = cart.currencyRate ?? 1;
-  const rate = Number.isFinite(currencyRate) && currencyRate > 0 ? currencyRate : 1;
-  const subtotal = Math.round((cart.subtotal - (cart.discountTotal ?? 0)) / rate);
+  const subtotal = shopSubtotalCents(cart);
   return {
     cart: {
       attributes: encodeAttributes(cart.attributes),
@@ -4350,26 +4359,92 @@ var convertWidgetSettings = async (input, ctx) => {
   return experiment && isCABTree(result) ? { ...result, experiment } : result;
 };
 
-// src/server/giftValidation.ts
-var resolveDataSourcePath = async (widgetId, shop, ctx) => {
-  const raw = await ctx.fetchUpstream("/api/v1/widgets/settings", { id: String(widgetId), shop }, { host: ctx.host });
-  const data = raw && typeof raw === "object" && "data" in raw ? raw.data : raw;
-  const endpoint = deepCamelCase(data)?.endpoint;
+// src/server/giftWidgets.ts
+import { z as z29 } from "zod";
+var SettingsNumber = z29.union([
+  z29.number(),
+  z29.string().trim().regex(/^-?\d+(\.\d+)?$/)
+]).pipe(z29.coerce.number());
+var SgwpMilestoneSchema = z29.object({
+  selectable_product_quantity: SettingsNumber.pipe(z29.number().int().nonnegative()),
+  unlock_price: SettingsNumber
+});
+var fetchGiftWidgetSettings = async (widgetId, shop, ctx) => unwrapData(await ctx.fetchUpstream("/api/v1/widgets/settings", { id: String(widgetId), shop }, { host: ctx.host }));
+var readDataSourcePath = (settings) => {
+  const endpoint = deepCamelCase(settings)?.endpoint;
   return typeof endpoint === "string" && endpoint ? endpoint : void 0;
 };
-var groupByWidget = (gifts) => {
+var readMilestones = (settings, report) => {
+  const raw = settings && typeof settings === "object" ? settings.milestones : void 0;
+  if (raw == null) return [];
+  const parsed = z29.array(SgwpMilestoneSchema).safeParse(raw);
+  if (parsed.success) return parsed.data;
+  report?.({
+    detail: [
+      "selectable-gift milestones unreadable",
+      ...parsed.error.issues.slice(0, 1).map((issue) => [issue.path.join("."), issue.message].filter(Boolean).join(": "))
+    ].join(": "),
+    kind: "giftMilestones"
+  });
+  return [];
+};
+var groupGiftsByWidget = (gifts, kind) => {
   const byWidget = /* @__PURE__ */ new Map();
   for (const gift of gifts) {
+    if (gift.kind !== kind) continue;
     byWidget.set(gift.widgetId, [...byWidget.get(gift.widgetId) ?? [], gift]);
   }
   return byWidget;
 };
-var validateGifts = async (input, ctx) => {
+
+// src/server/sgwpCapacity.ts
+var sgwpQualifyingSubtotalCents = (cart, gifts) => {
+  const giftMajor = gifts.filter((gift) => gift.kind === "sgwp").reduce((total, gift) => total + gift.cost, 0);
+  return shopSubtotalCents(cart) - toShopCents(giftMajor, shopCurrencyRate(cart));
+};
+var unlockedCapacity = (milestones, subtotalCents) => milestones.reduce(
+  (capacity, milestone) => Math.round(milestone.unlock_price * 100) <= subtotalCents ? capacity + milestone.selectable_product_quantity : capacity,
+  0
+);
+
+// src/server/sgwpValidation.ts
+var computeSgwpAdjustments = (gifts, capacity) => {
+  let surplus = gifts.reduce((units, gift) => units + gift.quantity, 0) - capacity;
+  const adjust = [];
+  for (const gift of gifts) {
+    if (surplus <= 0) break;
+    const trimmed = Math.min(gift.quantity, surplus);
+    adjust.push({ lineId: gift.lineId, quantity: gift.quantity - trimmed });
+    surplus -= trimmed;
+  }
+  return adjust;
+};
+var validateSelectableGifts = async (input, ctx) => {
+  const byWidget = groupGiftsByWidget(input.gifts, "sgwp");
+  if (byWidget.size === 0) return [];
+  const subtotalCents = sgwpQualifyingSubtotalCents(input.cart, input.gifts);
   const perWidget = await Promise.all(
-    [...groupByWidget(input.gifts)].map(async ([widgetId, gifts]) => {
+    [...byWidget].map(async ([widgetId, gifts]) => {
+      try {
+        const settings = await fetchGiftWidgetSettings(widgetId, input.shop, ctx);
+        const milestones = readMilestones(settings, ctx.reportDrift);
+        if (milestones.length === 0) return [];
+        return computeSgwpAdjustments(gifts, unlockedCapacity(milestones, subtotalCents));
+      } catch {
+        return [];
+      }
+    })
+  );
+  return perWidget.flat();
+};
+
+// src/server/giftValidation.ts
+var validateGwpGifts = async (input, ctx) => {
+  const perWidget = await Promise.all(
+    [...groupGiftsByWidget(input.gifts, "gwp")].map(async ([widgetId, gifts]) => {
       const discountLost = gifts.filter(hasLostDiscount).map((gift) => gift.lineId);
       try {
-        const dataSourcePath = await resolveDataSourcePath(widgetId, input.shop, ctx);
+        const dataSourcePath = readDataSourcePath(await fetchGiftWidgetSettings(widgetId, input.shop, ctx));
         if (!dataSourcePath) return discountLost;
         const { metadata } = await fetchDataSourceResults(
           {
@@ -4402,7 +4477,17 @@ var validateGifts = async (input, ctx) => {
       }
     })
   );
-  return { remove: perWidget.flat() };
+  return perWidget.flat();
+};
+var validateGifts = async (input, ctx) => {
+  const [remove, adjust] = await Promise.all([validateGwpGifts(input, ctx), validateSelectableGifts(input, ctx)]);
+  const removed = new Set(remove);
+  const targets = /* @__PURE__ */ new Map();
+  for (const { lineId, quantity } of adjust) {
+    if (removed.has(lineId)) continue;
+    targets.set(lineId, Math.min(quantity, targets.get(lineId) ?? quantity));
+  }
+  return { adjust: [...targets].map(([lineId, quantity]) => ({ lineId, quantity })), remove: [...removed] };
 };
 
 // src/server/analytics.ts
@@ -4524,7 +4609,7 @@ var postAnalyticsEvents = async (input, ctx) => {
 };
 
 // src/server/requestSchemas.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 var REQUEST_BOUNDS = {
   /** Cart-level attributes per cart. */
   CART_ATTRIBUTES_MAX: 100,
@@ -4555,42 +4640,42 @@ var REQUEST_BOUNDS = {
   /** Rich ads transaction lines — the engine's ads contract. */
   TRANSACTION_ITEMS_MAX: 50
 };
-var KeyValue = z29.object({
-  key: z29.string().max(REQUEST_BOUNDS.STRING_KEY_MAX),
-  value: z29.string().max(REQUEST_BOUNDS.STRING_VALUE_MAX).optional()
+var KeyValue = z30.object({
+  key: z30.string().max(REQUEST_BOUNDS.STRING_KEY_MAX),
+  value: z30.string().max(REQUEST_BOUNDS.STRING_VALUE_MAX).optional()
 });
-var CartLineInputSchema = z29.object({
-  productId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
-  properties: z29.array(KeyValue).max(REQUEST_BOUNDS.LINE_PROPERTIES_MAX).optional(),
-  quantity: z29.number(),
-  subscriptionId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  variantId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX)
+var CartLineInputSchema = z30.object({
+  productId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  properties: z30.array(KeyValue).max(REQUEST_BOUNDS.LINE_PROPERTIES_MAX).optional(),
+  quantity: z30.number(),
+  subscriptionId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  variantId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX)
 });
-var CartInputSchema = z29.object({
-  attributes: z29.array(KeyValue).max(REQUEST_BOUNDS.CART_ATTRIBUTES_MAX).optional(),
+var CartInputSchema = z30.object({
+  attributes: z30.array(KeyValue).max(REQUEST_BOUNDS.CART_ATTRIBUTES_MAX).optional(),
   /**
    * Presentment-per-shop-currency FX rate (buyer price ÷ shop price, e.g. `1.35` for a USD shop
    * selling in CAD). Money rule thresholds are authored in SHOP currency, so the engine subtotal is
    * divided by this before evaluation. Omit (or send 1) when the cart is already in the shop's currency.
    */
-  currencyRate: z29.number().optional(),
+  currencyRate: z30.number().optional(),
   /** Applied discount codes; the engine evaluates `discount_code` rules against them (sent as `[{code}]`). */
-  discountCodes: z29.array(z29.string().max(REQUEST_BOUNDS.STRING_KEY_MAX)).max(REQUEST_BOUNDS.DISCOUNT_CODES_MAX).optional(),
+  discountCodes: z30.array(z30.string().max(REQUEST_BOUNDS.STRING_KEY_MAX)).max(REQUEST_BOUNDS.DISCOUNT_CODES_MAX).optional(),
   /** Presentment cents of cart-level discount allocations, subtracted from `subtotal` for the engine. */
-  discountTotal: z29.number().optional(),
-  items: z29.array(CartLineInputSchema).max(REQUEST_BOUNDS.CART_ITEMS_MAX),
+  discountTotal: z30.number().optional(),
+  items: z30.array(CartLineInputSchema).max(REQUEST_BOUNDS.CART_ITEMS_MAX),
   /** Presentment subtotal in cents. */
-  subtotal: z29.number()
+  subtotal: z30.number()
 });
-var UserConfigInputSchema = z29.object({ shop: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX) });
-var DataSourceInputSchema = z29.object({
+var UserConfigInputSchema = z30.object({ shop: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX) });
+var DataSourceInputSchema = z30.object({
   cart: CartInputSchema,
   /**
    * Numeric Shopify company-location id when the buyer is a B2B session (`buyerIdentity.purchasingCompany`).
    * Present ⇒ the orchestrator filters results by the location's catalog via admin-api (REB-23713); the
    * client's country-context market check is bypassed for B2B (it false-negatives B2B-catalog products).
    */
-  companyLocationId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  companyLocationId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /**
    * Buyer's market country (ISO 3166-1 alpha-2) — forwarded to the engine as the `country_code` PARAM
    * when the shop's markets toggle is on (REB-21688; the sink was the `X-Country-Code` header under
@@ -4599,16 +4684,16 @@ var DataSourceInputSchema = z29.object({
    * uppercase (the wire value is forwarded verbatim as the param) so a case-sensitive engine lookup
    * can't silently miss a lowercase code — `adsEngine.ts` uppercases for the same reason.
    */
-  country: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z]{2}$/, "must be an ISO 3166-1 alpha-2 country code (e.g. CA)").transform((value) => value.toUpperCase()).optional(),
-  customerId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  dataSourcePath: z29.string().max(REQUEST_BOUNDS.STRING_KEY_MAX),
+  country: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z]{2}$/, "must be an ISO 3166-1 alpha-2 country code (e.g. CA)").transform((value) => value.toUpperCase()).optional(),
+  customerId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  dataSourcePath: z30.string().max(REQUEST_BOUNDS.STRING_KEY_MAX),
   /**
    * Engine `filter_inputs` override: `'no'` keeps in-cart (input) products in the results/rule
    * outputs — gift validation sends it so a gift's own product can appear in its answer. Omitted = the
    * engine's default filtering.
    */
-  filterInputs: z29.enum(["no", "yes"]).optional(),
-  integrations: z29.record(z29.string().max(REQUEST_BOUNDS.STRING_KEY_MAX), z29.boolean()).refine((record) => Object.keys(record).length <= REQUEST_BOUNDS.INTEGRATION_KEYS_MAX, {
+  filterInputs: z30.enum(["no", "yes"]).optional(),
+  integrations: z30.record(z30.string().max(REQUEST_BOUNDS.STRING_KEY_MAX), z30.boolean()).refine((record) => Object.keys(record).length <= REQUEST_BOUNDS.INTEGRATION_KEYS_MAX, {
     message: `Too many integration keys (max ${REQUEST_BOUNDS.INTEGRATION_KEYS_MAX})`
   }).optional(),
   /**
@@ -4621,20 +4706,31 @@ var DataSourceInputSchema = z29.object({
    * request header) fails the regex. Callers should send the buyer's resolved locale (e.g. Shopify
    * checkout's `localization.language.isoCode`), not the request header verbatim.
    */
-  language: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z0-9-]+$/, "must be a single BCP-47 tag (e.g. fr-CA), not a q-value list").optional(),
-  limit: z29.number().max(REQUEST_BOUNDS.LIMIT_MAX),
-  productType: z29.enum(["both", "one-time", "subscription"]).optional(),
-  shop: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
-  visitorId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+  language: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z0-9-]+$/, "must be a single BCP-47 tag (e.g. fr-CA), not a q-value list").optional(),
+  limit: z30.number().max(REQUEST_BOUNDS.LIMIT_MAX),
+  productType: z30.enum(["both", "one-time", "subscription"]).optional(),
+  shop: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  visitorId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
 });
-var GiftInputSchema = z29.object({
-  cost: z29.number(),
-  discounted: z29.boolean(),
-  lineId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
-  productId: z29.number(),
-  widgetId: z29.number()
+var GiftInputSchema = z30.object({
+  cost: z30.number(),
+  discounted: z30.boolean(),
+  /**
+   * Which gift attribution the line carries (REB-24363). Defaults to `gwp` because a client that predates
+   * the field only ever sent GWP lines — without the default an older extension's request would 422.
+   */
+  kind: z30.enum(GIFT_KINDS).default("gwp"),
+  lineId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  productId: z30.number(),
+  /**
+   * The line's unit count (REB-24363) — the selectable-GWP verdict trims surplus units against milestone
+   * capacity. The second deliberate default: a client predating the field sent only GWP lines, whose
+   * verdict is whole-line, so a missing quantity reads as one unit rather than 422ing the older request.
+   */
+  quantity: z30.number().int().min(1).default(1),
+  widgetId: z30.number()
 });
-var GiftValidationInputSchema = z29.object({
+var GiftValidationInputSchema = z30.object({
   cart: CartInputSchema,
   /**
    * Buyer's market country — threaded into the per-widget data-source evaluations, which forward it to
@@ -4643,59 +4739,76 @@ var GiftValidationInputSchema = z29.object({
    * turns markets off); regex-bound and uppercase-normalized for the same reasons as
    * `DataSourceInputSchema`'s `country`.
    */
-  country: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z]{2}$/, "must be an ISO 3166-1 alpha-2 country code (e.g. CA)").transform((value) => value.toUpperCase()).optional(),
-  customerId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  gifts: z29.array(GiftInputSchema).max(REQUEST_BOUNDS.GIFTS_MAX),
+  country: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z]{2}$/, "must be an ISO 3166-1 alpha-2 country code (e.g. CA)").transform((value) => value.toUpperCase()).optional(),
+  customerId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  gifts: z30.array(GiftInputSchema).max(REQUEST_BOUNDS.GIFTS_MAX),
   /**
    * Buyer's checkout language — threaded into the per-widget data-source evaluations, which normalize
    * and forward it as the engine `locale` param under the same markets-toggle gate (REB-21688). MUST be
    * a single BCP-47 tag, for the same reason as `DataSourceInputSchema`'s `language` above.
    */
-  language: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z0-9-]+$/, "must be a single BCP-47 tag (e.g. fr-CA), not a q-value list").optional(),
-  shop: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
-  visitorId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+  language: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).regex(/^[A-Za-z0-9-]+$/, "must be a single BCP-47 tag (e.g. fr-CA), not a q-value list").optional(),
+  shop: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  visitorId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+});
+var GiftAdjustmentSchema = z30.object({
+  lineId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  quantity: z30.number().int().nonnegative()
 });
-var MonetizeTransactionItemSchema = z29.object({
-  id: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
-  priceCents: z29.number(),
-  quantity: z29.number(),
-  title: z29.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX),
-  type: z29.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX)
+var GiftValidationResponseSchema = z30.object({
+  adjust: z30.array(GiftAdjustmentSchema).max(REQUEST_BOUNDS.GIFTS_MAX).default([]),
+  remove: z30.array(z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX)).max(REQUEST_BOUNDS.GIFTS_MAX).refine(
+    (remove) => new Set(remove).size === remove.length,
+    "a line id may appear at most once in `remove`"
+  )
+}).refine(
+  ({ adjust, remove }) => !adjust.some(({ lineId }) => remove.includes(lineId)),
+  "a line id may not appear in both `remove` and `adjust`"
+).refine(
+  ({ adjust }) => new Set(adjust.map(({ lineId }) => lineId)).size === adjust.length,
+  "a line id may appear at most once in `adjust`"
+);
+var MonetizeTransactionItemSchema = z30.object({
+  id: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  priceCents: z30.number(),
+  quantity: z30.number(),
+  title: z30.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX),
+  type: z30.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX)
 });
-var MonetizeInputSchema = z29.object({
+var MonetizeInputSchema = z30.object({
   cart: CartInputSchema,
   /** Client-minted render-beacon correlation id; forwarded to the ads engine as `client_request_id`. */
-  clientRequestId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  country: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  currency: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  clientRequestId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  country: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  currency: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /** Ads-targeting identity/geo/locale fields (React parity); folded into the engine query verbatim. */
-  customerEmail: z29.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
-  customerFirstName: z29.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
-  customerId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  customerLastName: z29.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
-  language: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  customerEmail: z30.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
+  customerFirstName: z30.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
+  customerId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  customerLastName: z30.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
+  language: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /** Buyer-facing order name (e.g. `#1001`) for the server-composed "Order … Confirmed" chrome line. */
-  orderName: z29.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
+  orderName: z30.string().max(REQUEST_BOUNDS.STRING_TEXT_MAX).optional(),
   /** Ads surface label, forwarded verbatim; `customer_account` is measured/floored as its own surface (the account-area order list). */
-  placement: z29.enum(["customer_account", "order_status", "thank_you_page"]),
+  placement: z30.enum(["customer_account", "order_status", "thank_you_page"]),
   /** Privacy Policy footer href — the Monetize widget's `privacy_policy_url` setting (React parity). */
-  privacyPolicyUrl: z29.string().max(REQUEST_BOUNDS.STRING_URL_MAX).optional(),
+  privacyPolicyUrl: z30.string().max(REQUEST_BOUNDS.STRING_URL_MAX).optional(),
   /** 30-min rolling session id (React parity); used for the ads `session_id`, else the visitor id. */
-  sessionId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  shop: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  sessionId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  shop: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
   /** Editor/QA indicator; OR-ed into the ads-engine `testing` flag so it stays out of billing/reporting. */
-  testing: z29.boolean().optional(),
-  timezone: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  testing: z30.boolean().optional(),
+  timezone: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /** Decorated (numeric) order id → the ads `transaction_id`. */
-  transactionId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  transactionId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /** Rich per-line ads items; capped at the engine's ads contract. Preferred over `cart.items`. */
-  transactionItems: z29.array(MonetizeTransactionItemSchema).max(REQUEST_BOUNDS.TRANSACTION_ITEMS_MAX).optional(),
+  transactionItems: z30.array(MonetizeTransactionItemSchema).max(REQUEST_BOUNDS.TRANSACTION_ITEMS_MAX).optional(),
   /** Order total in presentment cents (React prefers total over subtotal); else `cart.subtotal`. */
-  transactionTotal: z29.number().optional(),
-  visitorId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  zipCode: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+  transactionTotal: z30.number().optional(),
+  visitorId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  zipCode: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
 });
-var WidgetSettingsInputSchema = z29.object({
+var WidgetSettingsInputSchema = z30.object({
   /**
    * Same domain as `CabShopConfig.cacheKey`, for the same reason: this side WINS the orchestrator's
    * `input.cacheKey ?? config.shop.cacheKey` (and an explicit value skips the config read entirely), so
@@ -4703,9 +4816,9 @@ var WidgetSettingsInputSchema = z29.object({
    * and pin the edge copy permanently stale. `.catch(undefined)` because a bogus buster should degrade
    * the read to un-busted, never 400 a widget render.
    */
-  cacheKey: z29.number().int().positive().optional().catch(void 0),
-  id: z29.number(),
-  key: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  cacheKey: z30.number().int().positive().optional().catch(void 0),
+  id: z30.number(),
+  key: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /**
    * Monetize context for inline hydration: when present AND the widget converts to a Monetize marker,
    * the server fetches/composes the offer cards inside this same request (no second `/cab/monetize`
@@ -4714,25 +4827,25 @@ var WidgetSettingsInputSchema = z29.object({
    * `privacyPolicyUrl` comes from the widget settings server-side (more authoritative than a relay).
    */
   monetize: MonetizeInputSchema.omit({ privacyPolicyUrl: true, shop: true }).optional(),
-  shop: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  shop: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
   /** Stable per-buyer id; when present, enables sticky server-side A/B variant selection. */
-  visitorId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+  visitorId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
 });
-var AnalyticsEventInputSchema = z29.object({
-  name: z29.string().max(REQUEST_BOUNDS.STRING_KEY_MAX),
-  properties: z29.record(z29.string().max(REQUEST_BOUNDS.STRING_KEY_MAX), z29.unknown()).optional(),
-  sentAt: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+var AnalyticsEventInputSchema = z30.object({
+  name: z30.string().max(REQUEST_BOUNDS.STRING_KEY_MAX),
+  properties: z30.record(z30.string().max(REQUEST_BOUNDS.STRING_KEY_MAX), z30.unknown()).optional(),
+  sentAt: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
 });
-var AnalyticsInputSchema = z29.object({
+var AnalyticsInputSchema = z30.object({
   /** Rebuy cart token (the `r_cart_token` cart attribute), when available — primary aggregation key. */
-  cartToken: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  cartToken: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /** Shopify checkout token, when available — drives cart/checkout aggregation downstream. */
-  checkoutToken: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
-  events: z29.array(AnalyticsEventInputSchema).max(REQUEST_BOUNDS.EVENTS_MAX),
-  shop: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
-  visitorId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  checkoutToken: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
+  events: z30.array(AnalyticsEventInputSchema).max(REQUEST_BOUNDS.EVENTS_MAX),
+  shop: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
+  visitorId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX),
   /** The widget id (smartBlockId) the events belong to. */
-  widgetId: z29.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
+  widgetId: z30.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional()
 });
 export {
   AnalyticsEventInputSchema,
@@ -4740,8 +4853,10 @@ export {
   CartInputSchema,
   CartLineInputSchema,
   DataSourceInputSchema,
+  GiftAdjustmentSchema,
   GiftInputSchema,
   GiftValidationInputSchema,
+  GiftValidationResponseSchema,
   MonetizeInputSchema,
   MonetizeTransactionItemSchema,
   NotFoundError,

package/dist/server/requestSchemas.d.ts

@@ -4,7 +4,8 @@
  * `*Input` twins in `./shared` are now `z.infer` of these schemas (single source of truth, no drift).
  *
  * These model the wire shape only: no `.default()`s (a request field is either sent or omitted — defaulting
- * would diverge `z.infer` from the twin it replaces and hide a missing field), and unknown keys are stripped
+ * would diverge `z.infer` from the twin it replaces and hide a missing field) — the two exceptions are
+ * `GiftInputSchema.kind` and `.quantity`, additive fields whose defaults ARE the cross-version contract — and unknown keys are stripped
  * by the plain `z.object`, which is the intended lenient request-parse behavior. Upper bounds
  * (`REQUEST_BOUNDS`) ARE part of the wire contract: the `/cab/*` routes are public and unauthenticated, so
  * the schema is the only edge guard against unbounded payloads.
@@ -128,8 +129,13 @@ export declare const DataSourceInputSchema: z.ZodObject<{
 export declare const GiftInputSchema: z.ZodObject<{
     cost: z.ZodNumber;
     discounted: z.ZodBoolean;
+    kind: z.ZodDefault<z.ZodEnum<{
+        gwp: "gwp";
+        sgwp: "sgwp";
+    }>>;
     lineId: z.ZodString;
     productId: z.ZodNumber;
+    quantity: z.ZodDefault<z.ZodNumber>;
     widgetId: z.ZodNumber;
 }, z.core.$strip>;
 /** Input for `validateGifts`. */
@@ -159,14 +165,39 @@ export declare const GiftValidationInputSchema: z.ZodObject<{
     gifts: z.ZodArray<z.ZodObject<{
         cost: z.ZodNumber;
         discounted: z.ZodBoolean;
+        kind: z.ZodDefault<z.ZodEnum<{
+            gwp: "gwp";
+            sgwp: "sgwp";
+        }>>;
         lineId: z.ZodString;
         productId: z.ZodNumber;
+        quantity: z.ZodDefault<z.ZodNumber>;
         widgetId: z.ZodNumber;
     }, z.core.$strip>>;
     language: z.ZodOptional<z.ZodString>;
     shop: z.ZodString;
     visitorId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** One per-line quantity target in the gift-validation receipt; `0` means remove the line. */
+export declare const GiftAdjustmentSchema: z.ZodObject<{
+    lineId: z.ZodString;
+    quantity: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * The gift-validation RECEIPT: whole-line removals beside per-line quantity targets. `validateGifts`
+ * derives its return type from this, so the two lists stay one contract. `adjust` defaults so a proxy that
+ * predates the field still answers a valid `{ remove }` receipt. One verdict per line: a line id in both
+ * lists, or twice in either, is a server bug — the client would have to pick a winner (or mutate a line
+ * twice), so the contract forbids all three here and `validateGifts` upholds them (strictest verdict wins,
+ * named once) even when a request names one `lineId` more than once.
+ */
+export declare const GiftValidationResponseSchema: z.ZodObject<{
+    adjust: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        lineId: z.ZodString;
+        quantity: z.ZodNumber;
+    }, z.core.$strip>>>;
+    remove: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 /**
  * A rich transaction line the ads engine prices/targets on — the full per-line detail React sends. Distinct
  * from a cart line: it carries the merchandise title/type/unit-price the rule-evaluation cart context omits.
@@ -318,8 +349,10 @@ export type AnalyticsInput = z.infer<typeof AnalyticsInputSchema>;
 export type CartInput = z.infer<typeof CartInputSchema>;
 export type CartLineInput = z.infer<typeof CartLineInputSchema>;
 export type DataSourceInput = z.infer<typeof DataSourceInputSchema>;
+export type GiftAdjustment = z.infer<typeof GiftAdjustmentSchema>;
 export type GiftInput = z.infer<typeof GiftInputSchema>;
 export type GiftValidationInput = z.infer<typeof GiftValidationInputSchema>;
+export type GiftValidationResponse = z.infer<typeof GiftValidationResponseSchema>;
 export type MonetizeInput = z.infer<typeof MonetizeInputSchema>;
 export type MonetizeTransactionItem = z.infer<typeof MonetizeTransactionItemSchema>;
 export type UserConfigInput = z.infer<typeof UserConfigInputSchema>;

package/dist/server/sgwpCapacity.d.ts

@@ -0,0 +1,25 @@
+import { type SgwpMilestone } from '../server/giftWidgets';
+import { type CartInput, type GiftInput } from '../server/shared';
+/**
+ * The subtotal a selectable-GWP milestone is judged against: the rule subtotal in shop cents
+ * ({@link shopSubtotalCents} — the same figure the GWP rules see) minus the cost of EVERY selectable gift
+ * line in the cart, from every widget and regardless of price. A gift may legitimately carry a price (a $3
+ * gift covering shipping), and counting it would let the gift hold its own threshold met after the
+ * qualifying items are gone (React `getSgwpUnlockSubtotalCents`). `cost` is a presentment MAJOR-unit
+ * line total, so the gift costs are summed in presentment first and converted through the rate ONCE —
+ * rounding each line separately can drift a cent from the summed figure at a threshold boundary.
+ *
+ * `gwp` lines are NOT subtracted, on purpose (React excluded selectable lines only). A discounted GWP gift
+ * is free, so it adds nothing to spend; one that lost its discount is in the same receipt's `remove`, and
+ * once the client applies that the next validation judges the milestones against the reduced subtotal —
+ * self-healing within a round trip, with any residue on the merchant's side, never the buyer's.
+ */
+export declare const sgwpQualifyingSubtotalCents: (cart: CartInput, gifts: GiftInput[]) => number;
+/**
+ * Gift units the cart has unlocked: Σ `selectable_product_quantity` over the milestones whose unlock price is
+ * at or below the subtotal, both in shop cents. `unlock_price` is authored in shop MAJOR units, so it is
+ * ×100 and rounded exactly as React's `getMilestoneUnlockPriceCents` did (a float residue like 150.5 × 100
+ * = 15050.000000000002 must not push a threshold a cent past a subtotal that meets it). Cumulative, not
+ * stepped: every met milestone contributes — the retired React validator's semantics, reproduced.
+ */
+export declare const unlockedCapacity: (milestones: SgwpMilestone[], subtotalCents: number) => number;

package/dist/server/sgwpValidation.d.ts

@@ -0,0 +1,19 @@
+import { type GiftAdjustment, type GiftInput, type GiftValidationInput, type ServerContext } from '../server/shared';
+/**
+ * Per-line quantity targets that bring one widget's selectable gifts back within `capacity` units. Surplus
+ * units come off the FIRST lines in request order: the request mirrors `shopify.lines`, whose index 0 is
+ * the most recently added line (Shopify's cart convention), so this is LIFO by add time — the earliest-
+ * claimed gifts survive, exactly as the retired React `computeSgwpLineAdjustments` walked them. A line the
+ * surplus consumes whole targets `0` (remove); a line it only dents targets its reduced quantity; a line it
+ * never reaches gets no entry.
+ */
+export declare const computeSgwpAdjustments: (gifts: GiftInput[], capacity: number) => GiftAdjustment[];
+/**
+ * The selectable-GWP half of the gift-validation receipt: for each `sgwp` widget in the request, read its
+ * `milestones` from its widget settings and trim the widget's lines to the capacity the cart has unlocked.
+ * Entirely fail-safe, like the GWP qualification path: an upstream failure, a deleted widget, or absent,
+ * empty, or malformed milestones all keep the widget's gifts (no entries). The GWP charged-gift rule never
+ * applies here — a selectable gift may be legitimately priced. Widgets are independent: one failing
+ * fetch never disturbs another's verdict.
+ */
+export declare const validateSelectableGifts: (input: GiftValidationInput, ctx: ServerContext) => Promise<GiftAdjustment[]>;

package/dist/server/shared.d.ts

@@ -27,14 +27,15 @@ export type UpstreamFetch = (path: string, params: Record<string, string>, optio
 }) => Promise<unknown>;
 /**
  * A drift signal the orchestrators emit when a per-item payload salvage drops something: a malformed
- * offer product, an invalid/unknown section stubbed out, an unreadable rule verdict, or a shop-config
- * entry the shared schema inerted (`shopConfig`). Distinct from a hard {@link UpstreamError} — the
+ * offer product, an invalid/unknown section stubbed out, an unreadable rule verdict, a shop-config
+ * entry the shared schema inerted (`shopConfig`), or unreadable selectable-gift milestones
+ * (`giftMilestones` — the widget's gifts are then kept). Distinct from a hard {@link UpstreamError} — the
  * request still succeeds (degraded), so this is the only trace that an upstream contract moved. Optional
  * on {@link ServerContext}; the host (rebuy-api) wires it to its logger.
  */
 export type ServerDrift = {
     detail: string;
-    kind: 'b2bAvailability' | 'dataSource' | 'monetizeOffer' | 'product' | 'ruleVerdict' | 'section' | 'shopConfig';
+    kind: 'b2bAvailability' | 'dataSource' | 'giftMilestones' | 'monetizeOffer' | 'product' | 'ruleVerdict' | 'section' | 'shopConfig';
 };
 /** A {@link ServerDrift} sink, as the orchestrators pass it around internally. */
 export type Reporter = (event: ServerDrift) => void;
@@ -69,4 +70,4 @@ export declare class NotFoundError extends Error {
  * requests against the exact contract the orchestrators are typed on. Kept re-exported here so the
  * `@rebuy/rebuy/server` type surface is unchanged.
  */
-export type { AnalyticsEventInput, AnalyticsInput, CartInput, CartLineInput, DataSourceInput, GiftInput, GiftValidationInput, MonetizeInput, MonetizeTransactionItem, UserConfigInput, WidgetSettingsInput, } from '../server/requestSchemas';
+export type { AnalyticsEventInput, AnalyticsInput, CartInput, CartLineInput, DataSourceInput, GiftAdjustment, GiftInput, GiftValidationInput, GiftValidationResponse, MonetizeInput, MonetizeTransactionItem, UserConfigInput, WidgetSettingsInput, } from '../server/requestSchemas';