@rebuy/rebuy 3.4.0 → 3.5.0

package/dist/index.cjs

@@ -989,6 +989,9 @@ var RebuyClient = class {
 // src/schema/cabShopConfig.ts
 var import_zod2 = require("zod");
 
+// src/schema/driftedMarkets.ts
+var DRIFTED_MARKETS = Object.freeze({ enabled: false });
+
 // src/schema/smartCart.ts
 var import_zod = require("zod");
 var SmartCartTierProduct = import_zod.z.looseObject({
@@ -1128,6 +1131,27 @@ var CabShopConfig = import_zod2.z.object({
    * missing/renamed currency degrades to "unknown" (client falls back to buyer decimals), never a parse fail.
    */
   currency: import_zod2.z.string().optional().catch(void 0),
+  /**
+   * The merchant's "Use Markets in Data Sources" toggle. The engine (CI2) never reads it on the serve
+   * path, so the proxy honouring it before sending market context is what makes the setting mean
+   * anything (REB-21688). Fail-CLOSED, unlike the fail-open siblings: a missing/null/drifted field reads
+   * as markets OFF — market context silently dropped (engine serves shop-default market), never sent
+   * against the merchant's setting. The OFF-reading salvages stay distinguishable: missing AND null are
+   * the engine's normal absent vocabulary (`.nullish()`, like `monetize`/`billingVersion`) and read as
+   * the plain default — not drift — while only a drifted SHAPE `.catch`es, to the {@link DRIFTED_MARKETS}
+   * identity sentinel, so `fetchUserConfig` can emit a `shopConfig` drift for the one case that means an
+   * engine rename/retype; otherwise a markets-enabled merchant degrading to shop-default pricing would
+   * be indistinguishable from markets genuinely off. The missing-key case is EXPLICIT via `.default()`
+   * (a factory, so parses never share a mutable object) rather than inferred from zod running an
+   * optional key's transform on `undefined`; `null` flows past the default through `.nullish()` into the
+   * transform. `Readonly` on the output type because the drifted salvage IS frozen — an assignment to
+   * `markets.enabled` downstream would throw only for drifted shops in production, so surface direct
+   * writes to tsc (a guard for the direct case only: TS doesn't check `readonly` in assignability, so
+   * laundering through a mutable-shaped alias still compiles).
+   * The inner `enabled` stays strict on purpose: `{ enabled: null }` is a genuine retype and drifting is
+   * the correct answer (the editor-path `ShopConfig.markets` would hard-fail the same payload).
+   */
+  markets: import_zod2.z.object({ enabled: import_zod2.z.boolean() }).nullish().catch(DRIFTED_MARKETS).default(() => ({ enabled: false })).transform((markets) => markets ?? { enabled: false }),
   monetize: import_zod2.z.object({ publisherKey: import_zod2.z.string().nullable() }).nullish().catch(void 0),
   shopId: import_zod2.z.number().optional().catch(void 0)
 });

package/dist/index.mjs

@@ -727,6 +727,9 @@ var RebuyClient = class {
 // src/schema/cabShopConfig.ts
 import { z as z2 } from "zod";
 
+// src/schema/driftedMarkets.ts
+var DRIFTED_MARKETS = Object.freeze({ enabled: false });
+
 // src/schema/smartCart.ts
 import { z } from "zod";
 var SmartCartTierProduct = z.looseObject({
@@ -866,6 +869,27 @@ var CabShopConfig = z2.object({
    * missing/renamed currency degrades to "unknown" (client falls back to buyer decimals), never a parse fail.
    */
   currency: z2.string().optional().catch(void 0),
+  /**
+   * The merchant's "Use Markets in Data Sources" toggle. The engine (CI2) never reads it on the serve
+   * path, so the proxy honouring it before sending market context is what makes the setting mean
+   * anything (REB-21688). Fail-CLOSED, unlike the fail-open siblings: a missing/null/drifted field reads
+   * as markets OFF — market context silently dropped (engine serves shop-default market), never sent
+   * against the merchant's setting. The OFF-reading salvages stay distinguishable: missing AND null are
+   * the engine's normal absent vocabulary (`.nullish()`, like `monetize`/`billingVersion`) and read as
+   * the plain default — not drift — while only a drifted SHAPE `.catch`es, to the {@link DRIFTED_MARKETS}
+   * identity sentinel, so `fetchUserConfig` can emit a `shopConfig` drift for the one case that means an
+   * engine rename/retype; otherwise a markets-enabled merchant degrading to shop-default pricing would
+   * be indistinguishable from markets genuinely off. The missing-key case is EXPLICIT via `.default()`
+   * (a factory, so parses never share a mutable object) rather than inferred from zod running an
+   * optional key's transform on `undefined`; `null` flows past the default through `.nullish()` into the
+   * transform. `Readonly` on the output type because the drifted salvage IS frozen — an assignment to
+   * `markets.enabled` downstream would throw only for drifted shops in production, so surface direct
+   * writes to tsc (a guard for the direct case only: TS doesn't check `readonly` in assignability, so
+   * laundering through a mutable-shaped alias still compiles).
+   * The inner `enabled` stays strict on purpose: `{ enabled: null }` is a genuine retype and drifting is
+   * the correct answer (the editor-path `ShopConfig.markets` would hard-fail the same payload).
+   */
+  markets: z2.object({ enabled: z2.boolean() }).nullish().catch(DRIFTED_MARKETS).default(() => ({ enabled: false })).transform((markets) => markets ?? { enabled: false }),
   monetize: z2.object({ publisherKey: z2.string().nullable() }).nullish().catch(void 0),
   shopId: z2.number().optional().catch(void 0)
 });

package/dist/schema/cabShopConfig.d.ts

@@ -16,7 +16,7 @@ export declare const CabActiveExperiment: z.ZodObject<{
 }, z.core.$strip>;
 export type CabActiveExperiment = z.infer<typeof CabActiveExperiment>;
 /**
- * The lean shop config CAB actually consumes — the five load-bearing fields, not the ~30 the
+ * The lean shop config CAB actually consumes — the handful of load-bearing fields, not the ~30 the
  * editor-facing `ShopConfig` carries. `apiKey` stays strict (every offers/monetize/gift/analytics
  * request authenticates with it); the rest use `.catch()` so a peripheral engine change (a renamed
  * field, a new `carousel` enum value like `'css'`, an experiment shape drift) degrades that one field
@@ -40,6 +40,13 @@ export declare const CabShopConfig: z.ZodObject<{
     apiKey: z.ZodString;
     billingVersion: z.ZodDefault<z.ZodCatch<z.ZodNullable<z.ZodString>>>;
     currency: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    markets: z.ZodPipe<z.ZodDefault<z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strip>>>>>, z.ZodTransform<Readonly<{
+        enabled: boolean;
+    }>, {
+        enabled: boolean;
+    } | null>>;
     monetize: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
         publisherKey: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>>>;
@@ -70,6 +77,13 @@ export declare const CabUserConfig: z.ZodObject<{
         apiKey: z.ZodString;
         billingVersion: z.ZodDefault<z.ZodCatch<z.ZodNullable<z.ZodString>>>;
         currency: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        markets: z.ZodPipe<z.ZodDefault<z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            enabled: z.ZodBoolean;
+        }, z.core.$strip>>>>>, z.ZodTransform<Readonly<{
+            enabled: boolean;
+        }>, {
+            enabled: boolean;
+        } | null>>;
         monetize: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
             publisherKey: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>>>>;

package/dist/schema/driftedMarkets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Identity sentinel for a drifted `CabShopConfig.markets` shape: the schema's `.catch` returns THIS
+ * frozen object, and `fetchUserConfig` detects drift by reference (`markets === DRIFTED_MARKETS`).
+ * Reference identity keeps the sentinel out of the wire vocabulary entirely — no key the engine could
+ * ever send (or forge) can mark or unmark drift, unlike a value marker in the object's own shape — and
+ * off the public type, which stays a plain readonly `{ enabled: boolean }`.
+ *
+ * Deliberately NOT re-exported from `src/schema/index.ts` (the barrel lists its files explicitly): each
+ * `exports` subpath bundles separately with no splitting, so identity only holds within one bundle, and
+ * a consumer-held copy from `@rebuy/rebuy` would silently never match a value from `@rebuy/rebuy/server`.
+ * Keeping the symbol off every public barrel makes that cross-bundle comparison unreachable instead of a
+ * documented caveat. Both importers (`cabShopConfig.ts`, `server/userConfig.ts`) land in the `./server`
+ * bundle, where the comparison is exact.
+ */
+export declare const DRIFTED_MARKETS: Readonly<{
+    readonly enabled: false;
+}>;

package/dist/server/index.cjs

@@ -411,6 +411,9 @@ var NotFoundError = class extends Error {
 // src/schema/cabShopConfig.ts
 var import_zod6 = require("zod");
 
+// src/schema/driftedMarkets.ts
+var DRIFTED_MARKETS = Object.freeze({ enabled: false });
+
 // src/schema/smartCart.ts
 var import_zod5 = require("zod");
 var SmartCartTierProduct = import_zod5.z.looseObject({
@@ -550,6 +553,27 @@ var CabShopConfig = import_zod6.z.object({
    * missing/renamed currency degrades to "unknown" (client falls back to buyer decimals), never a parse fail.
    */
   currency: import_zod6.z.string().optional().catch(void 0),
+  /**
+   * The merchant's "Use Markets in Data Sources" toggle. The engine (CI2) never reads it on the serve
+   * path, so the proxy honouring it before sending market context is what makes the setting mean
+   * anything (REB-21688). Fail-CLOSED, unlike the fail-open siblings: a missing/null/drifted field reads
+   * as markets OFF — market context silently dropped (engine serves shop-default market), never sent
+   * against the merchant's setting. The OFF-reading salvages stay distinguishable: missing AND null are
+   * the engine's normal absent vocabulary (`.nullish()`, like `monetize`/`billingVersion`) and read as
+   * the plain default — not drift — while only a drifted SHAPE `.catch`es, to the {@link DRIFTED_MARKETS}
+   * identity sentinel, so `fetchUserConfig` can emit a `shopConfig` drift for the one case that means an
+   * engine rename/retype; otherwise a markets-enabled merchant degrading to shop-default pricing would
+   * be indistinguishable from markets genuinely off. The missing-key case is EXPLICIT via `.default()`
+   * (a factory, so parses never share a mutable object) rather than inferred from zod running an
+   * optional key's transform on `undefined`; `null` flows past the default through `.nullish()` into the
+   * transform. `Readonly` on the output type because the drifted salvage IS frozen — an assignment to
+   * `markets.enabled` downstream would throw only for drifted shops in production, so surface direct
+   * writes to tsc (a guard for the direct case only: TS doesn't check `readonly` in assignability, so
+   * laundering through a mutable-shaped alias still compiles).
+   * The inner `enabled` stays strict on purpose: `{ enabled: null }` is a genuine retype and drifting is
+   * the correct answer (the editor-path `ShopConfig.markets` would hard-fail the same payload).
+   */
+  markets: import_zod6.z.object({ enabled: import_zod6.z.boolean() }).nullish().catch(DRIFTED_MARKETS).default(() => ({ enabled: false })).transform((markets) => markets ?? { enabled: false }),
   monetize: import_zod6.z.object({ publisherKey: import_zod6.z.string().nullable() }).nullish().catch(void 0),
   shopId: import_zod6.z.number().optional().catch(void 0)
 });
@@ -3580,7 +3604,14 @@ var fetchUserConfig = async (input, ctx) => {
   }
   const data = unwrapData(upstream);
   if (isMissingShopPayload(data)) throw new NotFoundError(`Shop config not found: ${input.shop}`);
-  return parseShielded(CabUserConfig, data);
+  const config = parseShielded(CabUserConfig, data);
+  if (config.shop.markets === DRIFTED_MARKETS) {
+    ctx.reportDrift?.({
+      detail: "shop config markets field drifted to disabled (fail-closed salvage) \u2014 market context withheld",
+      kind: "shopConfig"
+    });
+  }
+  return config;
 };
 
 // src/utilities.ts
@@ -3681,19 +3712,16 @@ var reportUnreadableVerdict = (metadata, report) => {
 var dedupeById = (products) => (0, import_es_toolkit6.uniqBy)(products, (product) => product.id);
 var fetchDataSourceResults = async (input, ctx) => {
   const { shop } = await fetchUserConfig({ shop: input.shop }, ctx);
-  const marketHeaders = {
-    ...input.language && { "Accept-Language": input.language },
-    ...input.country && { "X-Country-Code": input.country }
-  };
+  const locale = input.language?.split("-")[0]?.toLowerCase();
+  const marketParams = shop.markets.enabled ? { ...input.country && { country_code: input.country }, ...locale && { locale } } : {};
   let upstream;
   try {
     upstream = await ctx.fetchUpstream(
       `/api/v1${input.dataSourcePath}`,
       {},
       {
-        ...Object.keys(marketHeaders).length > 0 && { headers: marketHeaders },
         host: ctx.host,
-        search: serialize(buildEngineParams(input, shop.apiKey))
+        search: serialize({ ...buildEngineParams(input, shop.apiKey), ...marketParams })
       }
     );
   } catch (err) {
@@ -3864,7 +3892,7 @@ var validateGifts = async (input, ctx) => {
         const { metadata } = await fetchDataSourceResults(
           {
             cart: input.cart,
-            /** Market context threads through so a market-gated gift rule answers for the buyer's market (REB-21102). */
+            /** Market context threads through so a market-gated gift rule answers for the buyer's market — as engine params, inheriting the shop's markets-toggle gate (REB-21688). */
             country: input.country,
             customerId: input.customerId,
             dataSourcePath,
@@ -4313,13 +4341,12 @@ var DataSourceInputSchema = import_zod28.z.object({
    */
   companyLocationId: import_zod28.z.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /**
-   * Buyer's market country (ISO 3166-1 alpha-2) — forwarded to the engine as the `X-Country-Code`
-   * HEADER (REB-21102), so it's regex-bound (not just length-bound like this schema's other passthrough
-   * identifiers): an unfiltered value reaching a header sink can throw a raw `TypeError` (CRLF, or any
-   * non-Latin1 codepoint) that isn't an `UpstreamError`, escaping `fetchDataSourceResults`'s error
-   * handling as an unhandled 500 on this public, unauthenticated route instead of a clean 422 here.
-   * Normalized to uppercase (the wire value is forwarded verbatim as the header) so a case-sensitive
-   * engine lookup can't silently miss a lowercase code — `adsEngine.ts` uppercases for the same reason.
+   * 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
+   * REB-21102, which is why the regex exists — kept because a two-letter bound still turns garbage into
+   * a clean 422 on this public, unauthenticated route instead of an engine round-trip). Normalized to
+   * 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: import_zod28.z.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: import_zod28.z.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
@@ -4334,8 +4361,11 @@ var DataSourceInputSchema = import_zod28.z.object({
     message: `Too many integration keys (max ${REQUEST_BOUNDS.INTEGRATION_KEYS_MAX})`
   }).optional(),
   /**
-   * Buyer's checkout language (BCP 47) — forwarded to the engine as the `Accept-Language` HEADER
-   * (REB-21102); regex-bound for the same header-sink reason as `country` above. MUST be a single tag
+   * Buyer's checkout language (BCP 47) — normalized server-side (the whole subtag tail dropped, region
+   * and script alike, then lowercased: `en-US` ⇒ `en`, `zh-Hant` ⇒ `zh` — PEV2 feeds key on the bare
+   * 2-letter language, and the market half comes from `country`) and forwarded to the engine as the
+   * `locale` PARAM when the shop's markets toggle is on (REB-21688); regex-bound for the same reason as
+   * `country` above. MUST be a single tag
    * (e.g. `fr-CA`) — a q-value list like `fr-CA,fr;q=0.9` (the raw shape of a browser `Accept-Language`
    * 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.
@@ -4356,16 +4386,19 @@ var GiftInputSchema = import_zod28.z.object({
 var GiftValidationInputSchema = import_zod28.z.object({
   cart: CartInputSchema,
   /**
-   * Buyer's market country — threaded into the per-widget data-source evaluations (REB-21102), which
-   * forward it to a header sink; regex-bound and uppercase-normalized for the same reasons as
+   * Buyer's market country — threaded into the per-widget data-source evaluations, which forward it to
+   * the engine as the `country_code` param when the shop's markets toggle is on (REB-21688 — gift
+   * validation inherits the gate, so a market-gated gift rule answers market-blind when the merchant
+   * turns markets off); regex-bound and uppercase-normalized for the same reasons as
    * `DataSourceInputSchema`'s `country`.
    */
   country: import_zod28.z.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: import_zod28.z.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   gifts: import_zod28.z.array(GiftInputSchema).max(REQUEST_BOUNDS.GIFTS_MAX),
   /**
-   * Buyer's checkout language — threaded into the per-widget data-source evaluations (REB-21102). MUST
-   * be a single BCP-47 tag, for the same reason as `DataSourceInputSchema`'s `language` above.
+   * 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: import_zod28.z.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: import_zod28.z.string().max(REQUEST_BOUNDS.STRING_ID_MAX),

package/dist/server/index.mjs

@@ -363,6 +363,9 @@ var NotFoundError = class extends Error {
 // src/schema/cabShopConfig.ts
 import { z as z6 } from "zod";
 
+// src/schema/driftedMarkets.ts
+var DRIFTED_MARKETS = Object.freeze({ enabled: false });
+
 // src/schema/smartCart.ts
 import { z as z5 } from "zod";
 var SmartCartTierProduct = z5.looseObject({
@@ -502,6 +505,27 @@ var CabShopConfig = z6.object({
    * missing/renamed currency degrades to "unknown" (client falls back to buyer decimals), never a parse fail.
    */
   currency: z6.string().optional().catch(void 0),
+  /**
+   * The merchant's "Use Markets in Data Sources" toggle. The engine (CI2) never reads it on the serve
+   * path, so the proxy honouring it before sending market context is what makes the setting mean
+   * anything (REB-21688). Fail-CLOSED, unlike the fail-open siblings: a missing/null/drifted field reads
+   * as markets OFF — market context silently dropped (engine serves shop-default market), never sent
+   * against the merchant's setting. The OFF-reading salvages stay distinguishable: missing AND null are
+   * the engine's normal absent vocabulary (`.nullish()`, like `monetize`/`billingVersion`) and read as
+   * the plain default — not drift — while only a drifted SHAPE `.catch`es, to the {@link DRIFTED_MARKETS}
+   * identity sentinel, so `fetchUserConfig` can emit a `shopConfig` drift for the one case that means an
+   * engine rename/retype; otherwise a markets-enabled merchant degrading to shop-default pricing would
+   * be indistinguishable from markets genuinely off. The missing-key case is EXPLICIT via `.default()`
+   * (a factory, so parses never share a mutable object) rather than inferred from zod running an
+   * optional key's transform on `undefined`; `null` flows past the default through `.nullish()` into the
+   * transform. `Readonly` on the output type because the drifted salvage IS frozen — an assignment to
+   * `markets.enabled` downstream would throw only for drifted shops in production, so surface direct
+   * writes to tsc (a guard for the direct case only: TS doesn't check `readonly` in assignability, so
+   * laundering through a mutable-shaped alias still compiles).
+   * The inner `enabled` stays strict on purpose: `{ enabled: null }` is a genuine retype and drifting is
+   * the correct answer (the editor-path `ShopConfig.markets` would hard-fail the same payload).
+   */
+  markets: z6.object({ enabled: z6.boolean() }).nullish().catch(DRIFTED_MARKETS).default(() => ({ enabled: false })).transform((markets) => markets ?? { enabled: false }),
   monetize: z6.object({ publisherKey: z6.string().nullable() }).nullish().catch(void 0),
   shopId: z6.number().optional().catch(void 0)
 });
@@ -3532,7 +3556,14 @@ var fetchUserConfig = async (input, ctx) => {
   }
   const data = unwrapData(upstream);
   if (isMissingShopPayload(data)) throw new NotFoundError(`Shop config not found: ${input.shop}`);
-  return parseShielded(CabUserConfig, data);
+  const config = parseShielded(CabUserConfig, data);
+  if (config.shop.markets === DRIFTED_MARKETS) {
+    ctx.reportDrift?.({
+      detail: "shop config markets field drifted to disabled (fail-closed salvage) \u2014 market context withheld",
+      kind: "shopConfig"
+    });
+  }
+  return config;
 };
 
 // src/utilities.ts
@@ -3633,19 +3664,16 @@ var reportUnreadableVerdict = (metadata, report) => {
 var dedupeById = (products) => uniqBy2(products, (product) => product.id);
 var fetchDataSourceResults = async (input, ctx) => {
   const { shop } = await fetchUserConfig({ shop: input.shop }, ctx);
-  const marketHeaders = {
-    ...input.language && { "Accept-Language": input.language },
-    ...input.country && { "X-Country-Code": input.country }
-  };
+  const locale = input.language?.split("-")[0]?.toLowerCase();
+  const marketParams = shop.markets.enabled ? { ...input.country && { country_code: input.country }, ...locale && { locale } } : {};
   let upstream;
   try {
     upstream = await ctx.fetchUpstream(
       `/api/v1${input.dataSourcePath}`,
       {},
       {
-        ...Object.keys(marketHeaders).length > 0 && { headers: marketHeaders },
         host: ctx.host,
-        search: serialize(buildEngineParams(input, shop.apiKey))
+        search: serialize({ ...buildEngineParams(input, shop.apiKey), ...marketParams })
       }
     );
   } catch (err) {
@@ -3816,7 +3844,7 @@ var validateGifts = async (input, ctx) => {
         const { metadata } = await fetchDataSourceResults(
           {
             cart: input.cart,
-            /** Market context threads through so a market-gated gift rule answers for the buyer's market (REB-21102). */
+            /** Market context threads through so a market-gated gift rule answers for the buyer's market — as engine params, inheriting the shop's markets-toggle gate (REB-21688). */
             country: input.country,
             customerId: input.customerId,
             dataSourcePath,
@@ -4265,13 +4293,12 @@ var DataSourceInputSchema = z28.object({
    */
   companyLocationId: z28.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   /**
-   * Buyer's market country (ISO 3166-1 alpha-2) — forwarded to the engine as the `X-Country-Code`
-   * HEADER (REB-21102), so it's regex-bound (not just length-bound like this schema's other passthrough
-   * identifiers): an unfiltered value reaching a header sink can throw a raw `TypeError` (CRLF, or any
-   * non-Latin1 codepoint) that isn't an `UpstreamError`, escaping `fetchDataSourceResults`'s error
-   * handling as an unhandled 500 on this public, unauthenticated route instead of a clean 422 here.
-   * Normalized to uppercase (the wire value is forwarded verbatim as the header) so a case-sensitive
-   * engine lookup can't silently miss a lowercase code — `adsEngine.ts` uppercases for the same reason.
+   * 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
+   * REB-21102, which is why the regex exists — kept because a two-letter bound still turns garbage into
+   * a clean 422 on this public, unauthenticated route instead of an engine round-trip). Normalized to
+   * 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: z28.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: z28.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
@@ -4286,8 +4313,11 @@ var DataSourceInputSchema = z28.object({
     message: `Too many integration keys (max ${REQUEST_BOUNDS.INTEGRATION_KEYS_MAX})`
   }).optional(),
   /**
-   * Buyer's checkout language (BCP 47) — forwarded to the engine as the `Accept-Language` HEADER
-   * (REB-21102); regex-bound for the same header-sink reason as `country` above. MUST be a single tag
+   * Buyer's checkout language (BCP 47) — normalized server-side (the whole subtag tail dropped, region
+   * and script alike, then lowercased: `en-US` ⇒ `en`, `zh-Hant` ⇒ `zh` — PEV2 feeds key on the bare
+   * 2-letter language, and the market half comes from `country`) and forwarded to the engine as the
+   * `locale` PARAM when the shop's markets toggle is on (REB-21688); regex-bound for the same reason as
+   * `country` above. MUST be a single tag
    * (e.g. `fr-CA`) — a q-value list like `fr-CA,fr;q=0.9` (the raw shape of a browser `Accept-Language`
    * 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.
@@ -4308,16 +4338,19 @@ var GiftInputSchema = z28.object({
 var GiftValidationInputSchema = z28.object({
   cart: CartInputSchema,
   /**
-   * Buyer's market country — threaded into the per-widget data-source evaluations (REB-21102), which
-   * forward it to a header sink; regex-bound and uppercase-normalized for the same reasons as
+   * Buyer's market country — threaded into the per-widget data-source evaluations, which forward it to
+   * the engine as the `country_code` param when the shop's markets toggle is on (REB-21688 — gift
+   * validation inherits the gate, so a market-gated gift rule answers market-blind when the merchant
+   * turns markets off); regex-bound and uppercase-normalized for the same reasons as
    * `DataSourceInputSchema`'s `country`.
    */
   country: z28.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: z28.string().max(REQUEST_BOUNDS.STRING_ID_MAX).optional(),
   gifts: z28.array(GiftInputSchema).max(REQUEST_BOUNDS.GIFTS_MAX),
   /**
-   * Buyer's checkout language — threaded into the per-widget data-source evaluations (REB-21102). MUST
-   * be a single BCP-47 tag, for the same reason as `DataSourceInputSchema`'s `language` above.
+   * 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: z28.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: z28.string().max(REQUEST_BOUNDS.STRING_ID_MAX),

package/dist/server/shared.d.ts

@@ -10,10 +10,13 @@ export declare const REBUY_ENGINE_HOST = "rebuyengine.com";
  * caller (rebuy-api owns the egress, timeouts, and the `X-Rebuy-Upstream` proxy header); MUST throw
  * {@link UpstreamError} on a non-2xx response so orchestrators can interpret the status.
  *
- * Defaults to GET with `params`/`search` as the query string; `headers` (e.g. an auth token, or the
- * market-context headers `fetchDataSourceResults` sends, REB-21102) apply on GET too — implementations
- * must not gate `headers` behind a `method === 'POST'` branch. Pass `method: 'POST'` with `body` (JSON
- * body) for write-style calls like analytics ingest.
+ * Defaults to GET with `params`/`search` as the query string. `headers` apply regardless of method —
+ * implementations must not gate them behind a `method === 'POST'` branch. Note the only current library
+ * caller sending `headers` is the analytics POST ingest (REB-21688 moved market context off the
+ * REB-21102 headers onto engine params, retiring the GET+headers case and the test that witnessed it),
+ * so a POST-gated implementation would pass every test in this repo today; the invariant stands so a
+ * future GET caller's headers can't silently drop. Pass `method: 'POST'` with `body` (JSON body) for
+ * write-style calls like analytics ingest.
  */
 export type UpstreamFetch = (path: string, params: Record<string, string>, options?: {
     body?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rebuy/rebuy",
-    "version": "3.4.0",
+    "version": "3.5.0",
     "description": "Shared zod schemas, legacy-to-CAB widget transforms, and server orchestrators for Rebuy's Shopify consumers (rebuy-api, admin-nextjs, rebuy-shopify-extensions)",
     "license": "MIT",
     "author": "Rebuy, Inc.",