@decocms/start 6.3.0 → 6.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/templates/server-entry.ts

@@ -89,6 +89,14 @@ const decoWorker = createDecoWorkerEntry(serverEntry, {
     handleRender,
     corsHeaders,
   },
+  // Region splits the cache so a RJ-cached response isn't served to SP visitors
+  // when pages use the website/matchers/location.ts matcher. Without this, the
+  // first geo-resolved response leaks across regions.
+  buildSegment: (request) => {
+    const cf = (request as unknown as { cf?: { regionCode?: string } }).cf;
+    const regionCode = request.headers.get("cf-region-code") ?? cf?.regionCode ?? "";
+    return regionCode ? { regionId: regionCode } : {};
+  },
 });
 
 export default instrumentWorker(decoWorker, {
@@ -155,11 +163,16 @@ const decoWorker = createDecoWorkerEntry(serverEntry, {
   csp: CSP_DIRECTIVES,
   buildSegment: (request) => {
     const vtx = extractVtexContext(request);
+    const cf = (request as unknown as { cf?: { regionCode?: string } }).cf;
+    const geoRegion = request.headers.get("cf-region-code") ?? cf?.regionCode ?? "";
     return {
       device: MOBILE_RE.test(request.headers.get("user-agent") ?? "") ? "mobile" : "desktop",
       loggedIn: vtx.isLoggedIn,
       salesChannel: vtx.salesChannel,
-      regionId: (vtx as any).regionId ?? undefined,
+      // Prefer VTEX regionalization regionId when present; otherwise fall back
+      // to Cloudflare geo so the website/matchers/location.ts matcher gets a
+      // properly segmented cache.
+      regionId: (vtx as any).regionId ?? (geoRegion || undefined),
     };
   },
   admin: {

package/src/admin/schema.ts

@@ -301,35 +301,53 @@ registerMatcherSchemas([
     key: "website/matchers/location.ts",
     title: "Location",
     namespace: "website",
-    propsSchema: {
-      type: "object",
-      properties: {
-        includeLocations: {
-          type: "array",
-          title: "Include Locations",
-          items: {
-            type: "object",
-            properties: {
-              country: { type: "string", title: "Country" },
-              regionCode: { type: "string", title: "Region" },
-              city: { type: "string", title: "City" },
-            },
+    propsSchema: (() => {
+      const locationOrMapItem = {
+        type: "object" as const,
+        properties: {
+          city: {
+            type: "string",
+            title: "City",
+            examples: ["São Paulo"],
+            description: "Exact city name (case-insensitive) as returned by Cloudflare's cf-ipcity header.",
+          },
+          regionCode: {
+            type: "string",
+            title: "Region Code",
+            examples: ["SP", "RJ", "MG", "47"],
+            description:
+              "Matches Cloudflare's cf-region-code header. Usually the ISO 3166-2 subdivision code (SP, RJ, MG, …); for some regions Cloudflare returns numeric codes (e.g. 47). Use the same value cf-region-code returns for your audience — full region names like \"São Paulo\" are NOT matched.",
+          },
+          country: {
+            type: "string",
+            title: "Country",
+            examples: ["BR", "Brasil", "US"],
+            description: "ISO 3166-1 alpha-2 code (BR, US, AR, …) or a full country name (Brasil, United States) — the matcher resolves common aliases.",
+          },
+          coordinates: {
+            type: "string",
+            title: "Area selection",
+            examples: ["-23.5505,-46.6333,5000"],
+            description: "\"latitude,longitude,radius_in_meters\" for haversine-radius matching. Set this for the Map mode.",
           },
         },
-        excludeLocations: {
-          type: "array",
-          title: "Exclude Locations",
-          items: {
-            type: "object",
-            properties: {
-              country: { type: "string", title: "Country" },
-              regionCode: { type: "string", title: "Region" },
-              city: { type: "string", title: "City" },
-            },
+      };
+      return {
+        type: "object" as const,
+        properties: {
+          includeLocations: {
+            type: "array",
+            title: "Include Locations",
+            items: locationOrMapItem,
+          },
+          excludeLocations: {
+            type: "array",
+            title: "Exclude Locations",
+            items: locationOrMapItem,
           },
         },
-      },
-    },
+      };
+    })(),
   },
   {
     key: "website/matchers/userAgent.ts",

package/src/matchers/builtins.test.ts

@@ -0,0 +1,251 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { MatcherContext } from "../cms/resolve";
+import { evaluateMatcher } from "../cms/resolve";
+import { registerBuiltinMatchers } from "./builtins";
+
+const LOCATION_KEY = "website/matchers/location.ts";
+
+beforeEach(() => {
+  registerBuiltinMatchers();
+});
+
+function ctxFromCookies(cookies: Record<string, string>): MatcherContext {
+  return { cookies };
+}
+
+function ctxFromCf(cf: Record<string, unknown>): MatcherContext {
+  const request = new Request("https://example.com/");
+  Object.defineProperty(request, "cf", { value: cf, configurable: true });
+  return { request };
+}
+
+function ctxFromHeaders(headers: Record<string, string>): MatcherContext {
+  return {
+    request: new Request("https://example.com/", { headers }),
+  };
+}
+
+function match(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  return evaluateMatcher({ ...rule, __resolveType: LOCATION_KEY }, ctx);
+}
+
+describe("locationMatcher — typed mode (Location)", () => {
+  it("matches when regionCode equals Cloudflare's cf-region-code (SP)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("matches a raw numeric regionCode (e.g. '47') for parity with deco-cx/apps", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "47", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{ regionCode: "47" }] }, ctx)).toBe(true);
+  });
+
+  it("is case-insensitive on regionCode", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [{ regionCode: "sp" }] }, ctx)).toBe(true);
+  });
+
+  it("does NOT match a region NAME against cf-region-code (parity with original)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match({ includeLocations: [{ regionCode: "São Paulo" }] }, ctx),
+    ).toBe(false);
+  });
+
+  it("does not match when the region differs", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [{ regionCode: "RJ" }] }, ctx)).toBe(false);
+  });
+
+  it("AND's multiple fields on the same entry (regionCode + country)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(
+      match(
+        { includeLocations: [{ regionCode: "SP", country: "BR" }] },
+        ctx,
+      ),
+    ).toBe(true);
+    expect(
+      match(
+        { includeLocations: [{ regionCode: "SP", country: "AR" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("resolves country aliases (Brasil → BR)", () => {
+    const ctx = ctxFromHeaders({ "cf-ipcountry": "BR", "cf-region-code": "SP" });
+    expect(
+      match({ includeLocations: [{ country: "Brasil" }] }, ctx),
+    ).toBe(true);
+  });
+
+  it("OR's across multiple include entries", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "RJ" });
+    expect(
+      match(
+        {
+          includeLocations: [{ regionCode: "SP" }, { regionCode: "RJ" }],
+        },
+        ctx,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("locationMatcher — empty / shape edge cases", () => {
+  it("empty includeLocations array → match (no constraint)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [] }, ctx)).toBe(true);
+  });
+
+  it("missing includeLocations → match", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({}, ctx)).toBe(true);
+  });
+
+  it("entry {} inside includeLocations matches everyone (parity with original)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{}] }, ctx)).toBe(true);
+  });
+
+  it("entry {} inside excludeLocations does NOT exclude anyone (parity)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ excludeLocations: [{}] }, ctx)).toBe(true);
+  });
+
+  it("excludeLocations short-circuits over includeLocations", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match(
+        {
+          includeLocations: [{ regionCode: "SP" }],
+          excludeLocations: [{ regionCode: "SP" }],
+        },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("includeLocations with [{regionCode}] fails when geo is empty", () => {
+    expect(
+      match({ includeLocations: [{ regionCode: "SP" }] }, {}),
+    ).toBe(false);
+  });
+});
+
+describe("locationMatcher — Map mode (haversine)", () => {
+  it("matches when source coords are within target radius", () => {
+    // Target: São Paulo center, 5km. Source: ~500m away.
+    const ctx = ctxFromHeaders({
+      "cf-iplatitude": "-23.5510",
+      "cf-iplongitude": "-46.6340",
+    });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(true);
+  });
+
+  it("does NOT match when source coords are outside the radius", () => {
+    // Target: São Paulo, 5km. Source: Rio (~360km away).
+    const ctx = ctxFromHeaders({
+      "cf-iplatitude": "-22.9068",
+      "cf-iplongitude": "-43.1729",
+    });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("Map-only rule does NOT match when source has no coordinates", () => {
+    // Deliberate divergence from deco-cx/apps: upstream lets coord-only rules
+    // vacuously pass when the visitor has no lat/lng, which matches every
+    // such visitor — a footgun in production. We require both sides to have
+    // coordinates before the haversine check passes.
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("AND's coordinates with regionCode on the same entry", () => {
+    // Source: SP coords, region=SP.
+    const ctx = ctxFromHeaders({
+      "cf-region-code": "SP",
+      "cf-iplatitude": "-23.5510",
+      "cf-iplongitude": "-46.6340",
+    });
+    // Entry asks for region=SP AND within 5km of SP center — matches.
+    expect(
+      match(
+        {
+          includeLocations: [
+            { regionCode: "SP", coordinates: "-23.5505,-46.6333,5000" },
+          ],
+        },
+        ctx,
+      ),
+    ).toBe(true);
+    // Entry asks for region=SP AND within 5km of Rio — fails on coords.
+    expect(
+      match(
+        {
+          includeLocations: [
+            { regionCode: "SP", coordinates: "-22.9068,-43.1729,5000" },
+          ],
+        },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("locationMatcher — data source fallbacks", () => {
+  it("reads from request.cf when headers are absent", () => {
+    const ctx = ctxFromCf({ country: "BR", regionCode: "SP" });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("reads from __cf_geo_* cookies as fallback", () => {
+    const ctx = ctxFromCookies({
+      __cf_geo_country: "BR",
+      __cf_geo_region_code: "SP",
+    });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("decodes URL-encoded cookie values (e.g. city with accent)", () => {
+    const ctx = ctxFromCookies({
+      __cf_geo_country: "BR",
+      __cf_geo_city: encodeURIComponent("São Paulo"),
+    });
+    expect(
+      match({ includeLocations: [{ city: "São Paulo" }] }, ctx),
+    ).toBe(true);
+  });
+
+  it("headers take precedence over request.cf and cookies", () => {
+    const request = new Request("https://example.com/", {
+      headers: { "cf-region-code": "SP" },
+    });
+    Object.defineProperty(request, "cf", {
+      value: { regionCode: "RJ", country: "BR" },
+      configurable: true,
+    });
+    const ctx: MatcherContext = {
+      request,
+      cookies: { __cf_geo_region_code: "MG" },
+    };
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+    expect(match({ includeLocations: [{ regionCode: "RJ" }] }, ctx)).toBe(false);
+  });
+});

package/src/matchers/builtins.ts

@@ -186,95 +186,168 @@ function queryStringMatcher(rule: Record<string, unknown>, ctx: MatcherContext):
 }
 
 // -------------------------------------------------------------------------
-// Location matcher
+// Location matcher — parity with deco-cx/apps/website/matchers/location.ts
+//
+// Each entry in includeLocations/excludeLocations is a union of:
+//   Location: { city?, regionCode?, country? }
+//   Map:      { coordinates?: "lat,lng,radius_in_meters" }
+// Fields may coexist on the same entry; the matcher AND's every constraint
+// that is populated. An entry with zero constraints returns defaultNotMatched
+// (true for includes, false for excludes), matching upstream semantics.
 // -------------------------------------------------------------------------
 
-interface LocationRule {
+interface LocationOrMap {
   country?: string;
   regionCode?: string;
   city?: string;
+  /** "latitude,longitude,radius_in_meters" — e.g. "-23.5505,-46.6333,5000" */
+  coordinates?: string;
 }
 
-interface GeoData {
+interface GeoSource {
   country: string;
   regionCode: string;
-  regionName: string;
   city: string;
+  /** "latitude,longitude" when available */
+  coordinates?: string;
+}
+
+function decodeCookie(value: string | undefined): string {
+  if (!value) return "";
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
 }
 
 /**
  * Extract geo data from the request context.
- * Priority: request.cf (Cloudflare Workers) > geo cookies > geo headers.
+ *
+ * Read order mirrors the original deco-cx/apps matcher (header-first), with
+ * additional fallbacks for environments that don't preserve the cf-* request
+ * headers (e.g. when TanStack Start re-wraps the request and drops them):
+ *   1. cf-* request headers (cf-region-code, cf-ipcity, ...)
+ *   2. request.cf (Cloudflare Workers native)
+ *   3. __cf_geo_* cookies (injected by createDecoWorkerEntry)
  */
-function getGeoData(ctx: MatcherContext): GeoData {
-  // 1. Cloudflare Workers: request.cf has authoritative geo data
-  const req = ctx.request;
-  if (req) {
-    const cf = (req as any).cf as Record<string, unknown> | undefined;
-    if (cf?.country) {
-      return {
-        country: (cf.country as string) ?? "",
-        regionCode: (cf.regionCode as string) ?? (cf.region as string) ?? "",
-        regionName: (cf.region as string) ?? "",
-        city: (cf.city as string) ?? "",
-      };
+function getGeoData(ctx: MatcherContext): GeoSource {
+  const headers = ctx.headers ?? {};
+  const reqHeaders = ctx.request?.headers;
+  const h = (name: string): string =>
+    headers[name] ?? reqHeaders?.get(name) ?? "";
+
+  let regionCode = h("cf-region-code");
+  let country = h("cf-ipcountry") || h("x-vercel-ip-country");
+  let city = h("cf-ipcity");
+  let latitude = h("cf-iplatitude");
+  let longitude = h("cf-iplongitude");
+
+  if (!country || !regionCode || !city || !latitude || !longitude) {
+    const req = ctx.request;
+    const cf = req ? ((req as any).cf as Record<string, unknown> | undefined) : undefined;
+    if (cf) {
+      country = country || ((cf.country as string) ?? "");
+      regionCode = regionCode || ((cf.regionCode as string) ?? "");
+      city = city || ((cf.city as string) ?? "");
+      latitude = latitude || (cf.latitude != null ? String(cf.latitude) : "");
+      longitude = longitude || (cf.longitude != null ? String(cf.longitude) : "");
     }
   }
 
-  // 2. Geo cookies (set by Cloudflare middleware on Fresh/Deno sites)
-  const cookies = ctx.cookies ?? {};
-  const cookieCountry = cookies.__cf_geo_country ? decodeURIComponent(cookies.__cf_geo_country) : "";
-  if (cookieCountry) {
-    return {
-      country: cookieCountry,
-      regionCode: cookies.__cf_geo_region_code ? decodeURIComponent(cookies.__cf_geo_region_code) : "",
-      regionName: cookies.__cf_geo_region ? decodeURIComponent(cookies.__cf_geo_region) : "",
-      city: cookies.__cf_geo_city ? decodeURIComponent(cookies.__cf_geo_city) : "",
-    };
+  if (!country || !regionCode || !city || !latitude || !longitude) {
+    const cookies = ctx.cookies ?? {};
+    country = country || decodeCookie(cookies.__cf_geo_country);
+    regionCode = regionCode || decodeCookie(cookies.__cf_geo_region_code);
+    city = city || decodeCookie(cookies.__cf_geo_city);
+    latitude = latitude || decodeCookie(cookies.__cf_geo_lat);
+    longitude = longitude || decodeCookie(cookies.__cf_geo_lng);
   }
 
-  // 3. Fallback: standard geo headers (Vercel, etc.)
-  const headers = ctx.headers ?? {};
-  return {
-    country: headers["cf-ipcountry"] ?? headers["x-vercel-ip-country"] ?? "",
-    regionCode: headers["cf-region"] ?? headers["x-vercel-ip-country-region"] ?? "",
-    regionName: "",
-    city: "",
-  };
+  const coordinates = latitude && longitude ? `${latitude},${longitude}` : undefined;
+  return { country, regionCode, city, coordinates };
 }
 
-function matchesLocationRule(
-  loc: LocationRule,
-  geo: GeoData,
-): boolean {
-  if (loc.country) {
-    const code = resolveCountryCode(loc.country);
-    if (code.toUpperCase() !== geo.country.toUpperCase()) return false;
-  }
-  if (loc.regionCode) {
-    // Match against both the short code ("SP") and full name ("São Paulo")
-    // so rules authored against either format continue working.
-    const ruleVal = loc.regionCode.toLowerCase();
-    if (geo.regionCode.toLowerCase() !== ruleVal && geo.regionName.toLowerCase() !== ruleVal) return false;
+/**
+ * Haversine "within radius" check.
+ *
+ * @param source "latitude,longitude" from the request's geo.
+ * @param target "latitude,longitude,radius_in_meters" from the rule entry.
+ */
+function haversineWithinRadius(source: string, target: string): boolean {
+  const [slat, slng] = source.split(",").map(Number);
+  const parts = target.split(",").map(Number);
+  const [tlat, tlng, radiusMeters] = parts;
+  if (
+    !Number.isFinite(slat) ||
+    !Number.isFinite(slng) ||
+    !Number.isFinite(tlat) ||
+    !Number.isFinite(tlng) ||
+    !Number.isFinite(radiusMeters)
+  ) {
+    return false;
   }
-  if (loc.city && loc.city.toLowerCase() !== geo.city.toLowerCase()) return false;
-  return true;
+  const R = 6371000;
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const dLat = toRad(tlat - slat);
+  const dLng = toRad(tlng - slng);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(slat)) * Math.cos(toRad(tlat)) * Math.sin(dLng / 2) ** 2;
+  const distance = 2 * R * Math.asin(Math.sqrt(a));
+  return distance <= radiusMeters;
 }
 
-function locationMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
-  const geo = getGeoData(ctx);
-  if (!geo.country) return !((rule.includeLocations as unknown[] | undefined)?.length);
+function matchLocation(defaultNotMatched: boolean, source: GeoSource) {
+  return (target: LocationOrMap): boolean => {
+    const hasRegion = !!target.regionCode;
+    const hasCity = !!target.city;
+    const hasCountry = !!target.country;
+    const hasCoords = !!target.coordinates;
+
+    if (!hasRegion && !hasCity && !hasCountry && !hasCoords) {
+      return defaultNotMatched;
+    }
+
+    let result =
+      !hasRegion ||
+      (target.regionCode!.toLowerCase() === source.regionCode.toLowerCase());
+
+    // Map-mode entries require the visitor to have coordinates — otherwise
+    // we can't tell whether they're inside the target radius, so the
+    // conservative default is "no match". This is a deliberate divergence
+    // from deco-cx/apps, which let coord-only rules vacuously pass when the
+    // visitor had no lat/lng — that behavior matches every visitor without
+    // geo data, which is a footgun in production.
+    result = result &&
+      (!hasCoords ||
+        (!!source.coordinates &&
+          haversineWithinRadius(source.coordinates, target.coordinates!)));
+
+    result = result &&
+      (!hasCity || target.city!.toLowerCase() === source.city.toLowerCase());
+
+    result = result &&
+      (!hasCountry ||
+        resolveCountryCode(target.country!).toUpperCase() ===
+          source.country.toUpperCase());
+
+    return result;
+  };
+}
 
-  const includeLocations = rule.includeLocations as LocationRule[] | undefined;
-  const excludeLocations = rule.excludeLocations as LocationRule[] | undefined;
+function locationMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const source = getGeoData(ctx);
+  const includeLocations = rule.includeLocations as LocationOrMap[] | undefined;
+  const excludeLocations = rule.excludeLocations as LocationOrMap[] | undefined;
 
-  if (excludeLocations?.some((loc) => matchesLocationRule(loc, geo))) {
+  if (excludeLocations?.some(matchLocation(false, source))) {
     return false;
   }
-  if (includeLocations?.length) {
-    return includeLocations.some((loc) => matchesLocationRule(loc, geo));
+  if (!includeLocations || includeLocations.length === 0) {
+    return true;
   }
-  return true;
+  return includeLocations.some(matchLocation(true, source));
 }
 
 // -------------------------------------------------------------------------

package/src/sdk/workerEntry.ts

@@ -489,6 +489,17 @@ export function injectGeoCookies(request: Request): Request {
   }
   headers.set("cookie", combined);
 
+  // Mirror the ASCII-safe geo fields from request.cf into headers so matchers
+  // that read `request.headers.get("cf-region-code")` (parity with the
+  // upstream deco-cx/apps location matcher) still work even if the inbound
+  // request didn't carry them. Non-ASCII fields (region name, city) stay in
+  // the cookies above — putting them in headers would re-trigger the
+  // non-ASCII warning we strip on the loop above.
+  if (cf.country && !headers.has("cf-ipcountry")) headers.set("cf-ipcountry", cf.country);
+  if (cf.regionCode && !headers.has("cf-region-code")) headers.set("cf-region-code", cf.regionCode);
+  if (cf.latitude && !headers.has("cf-iplatitude")) headers.set("cf-iplatitude", cf.latitude);
+  if (cf.longitude && !headers.has("cf-iplongitude")) headers.set("cf-iplongitude", cf.longitude);
+
   return new Request(request, { headers });
 }