@asteby/storefront 0.6.0 → 0.7.0

package/README.md

@@ -237,6 +237,38 @@ paymentErrorView(error)                                           // network (re
 - `promoProgressView(cart.promotions, locale)` and `rewardLabel(reward, locale)` only format what OPS sends (`remaining`, `percent`, `reached`); never subtract or divide in the shop.
 - The mock serves `POST /checkouts/:id/payment` with outcomes by token (`tok_APRO` paid, `tok_FUND`/`tok_SECU`/`tok_EXPI`/`tok_FORM`/`tok_CALL`/`tok_OTHE` rejected, `tok_CONT` in review, `tok_3DS` challenge, `method: 'cash'` voucher), idempotency, `price_mismatch` 422, attempts cap 429 and `409` while another attempt is paid/pending; plus `PUT /carts/:id/note`, `GET /carts/:id/recommendations` and `GET /promotions`.
 
+## Domain and market (single-customer storefront)
+
+A storefront that belongs to ONE organization sends its verified domain plus the
+market it is serving. OPS resolves the organization from the domain and honors
+the market when that organization has it active (otherwise it falls back to the
+domain's own market).
+
+```ts
+import { createStorefrontClient, storefrontDomainHeader } from '@asteby/storefront'
+
+const client = createStorefrontClient({
+  baseUrl: 'https://ops.example.com/api/gw',
+  token: process.env.STOREFRONT_SK!,
+  domain: 'godsnutrition.com', // verified domain of the organization
+  market: 'mx',                // -> X-Storefront-Domain: godsnutrition.com#mx
+})
+
+storefrontDomainHeader('godsnutrition.com', 'MX') // 'godsnutrition.com#mx'
+storefrontDomainHeader('godsnutrition.com')       // 'godsnutrition.com'
+```
+
+Per-request market (one domain, path prefixes `/mx`, `/us`): create the client
+per request with that request's `market`, or build the header yourself with
+`storefrontDomainHeader` and pass it in `headers`.
+
+### Market detection and hreflang
+
+Pure helpers, no DOM: `visitorCountry(headers)` (CDN country headers),
+`preferredLanguages` / `negotiateLocale` (Accept-Language), `suggestMarket`
+(suggests, never redirects; respects crawlers and a saved choice; country wins
+over language) and `hreflangLinks` for per-market SEO.
+
 ## API
 
 `createStorefrontClient(options)`:
@@ -249,6 +281,8 @@ paymentErrorView(error)                                           // network (re
 | `clientIp?` | Shopper IP for server-side calls → `X-Storefront-Client-IP` (see below) |
 | `fetch?` | Custom fetch (default `globalThis.fetch`) |
 | `locale?` | `Accept-Language` |
+| `domain?` | Public host of the storefront → `X-Storefront-Domain` (see below) |
+| `market?` | Market code (`mx`, `us`) → `X-Storefront-Domain: <domain>#<market>`; ignored without `domain` |
 | `headers?` | Extra headers on every request |
 | `timeoutMs?` | Abort after N ms (`StorefrontError` code `timeout`) |
 | `onRequest?(ctx)` | Runs before each request; return a `Response` to short-circuit (SSR cache hit) |

package/dist/index.cjs

@@ -205,6 +205,7 @@ function createStorefrontClient(config) {
     headers.set("Accept", "application/json");
     headers.set("Authorization", `Bearer ${config.token}`);
     if (config.locale) headers.set("Accept-Language", config.locale);
+    if (config.domain) headers.set("X-Storefront-Domain", storefrontDomainHeader(config.domain, config.market));
     const customerToken = options.customerToken !== void 0 ? options.customerToken : config.customerToken;
     if (customerToken) headers.set("X-Customer-Token", customerToken);
     const clientIp = options.clientIp !== void 0 ? options.clientIp : config.clientIp;
@@ -407,6 +408,11 @@ function createStorefrontClient(config) {
   };
   return client;
 }
+function storefrontDomainHeader(domain, market) {
+  const host = domain.trim();
+  const code = (market ?? "").trim().toLowerCase();
+  return code && /^[a-z0-9_-]{1,32}$/.test(code) ? `${host}#${code}` : host;
+}
 
 // src/availability.ts
 var ES = {
@@ -1045,7 +1051,67 @@ function promoProgressView(promotions, locale, overrides) {
   return { discount, shipping };
 }
 
+// src/market.ts
+var COUNTRY_HEADERS = ["cf-ipcountry", "cloudfront-viewer-country", "x-vercel-ip-country", "x-appengine-country", "x-country-code"];
+var BOT = /bot|crawl|spider|slurp|bing|facebookexternalhit|embedly|preview|lighthouse|headless|curl|wget/i;
+function visitorCountry(headers, { trustProxy = true } = {}) {
+  if (!trustProxy) return null;
+  for (const name of COUNTRY_HEADERS) {
+    const value = headers.get(name)?.trim().toUpperCase();
+    if (value && /^[A-Z]{2}$/.test(value) && value !== "XX" && value !== "T1") return value;
+  }
+  return null;
+}
+function preferredLanguages(acceptLanguage) {
+  if (!acceptLanguage) return [];
+  return acceptLanguage.split(",").map((part, index) => {
+    const [tag = "", ...params] = part.trim().split(";");
+    const q = Number(params.find((p) => p.trim().startsWith("q="))?.split("=")[1] ?? 1);
+    return { tag: tag.trim().toLowerCase(), q: Number.isFinite(q) ? q : 0, index };
+  }).filter((l) => l.tag && l.tag !== "*" && l.q > 0).sort((a, b) => b.q - a.q || a.index - b.index).map((l) => l.tag);
+}
+function negotiateLocale(acceptLanguage, available, fallback) {
+  const lowered = new Map(available.map((l) => [l.toLowerCase(), l]));
+  for (const wanted of preferredLanguages(acceptLanguage)) {
+    const exact = lowered.get(wanted);
+    if (exact) return exact;
+    const base = wanted.split("-")[0];
+    const sameBase = available.find((l) => l.toLowerCase().split("-")[0] === base);
+    if (sameBase) return sameBase;
+  }
+  return fallback;
+}
+function suggestMarket({
+  headers,
+  markets,
+  current,
+  chosen,
+  trustProxy = true
+}) {
+  if (chosen || markets.length < 2) return null;
+  if (BOT.test(headers.get("user-agent") ?? "")) return null;
+  const country = visitorCountry(headers, { trustProxy });
+  if (country) {
+    const target = markets.find((m) => m.countries.includes(country));
+    return target && target.code !== current ? { market: target, reason: "country" } : null;
+  }
+  for (const tag of preferredLanguages(headers.get("accept-language"))) {
+    const region = tag.split("-")[1]?.toUpperCase();
+    if (!region) continue;
+    const target = markets.find((m) => m.countries.includes(region));
+    if (target) return target.code !== current ? { market: target, reason: "language" } : null;
+  }
+  return null;
+}
+function hreflangLinks(markets, path, defaultMarket, protocol = "https") {
+  const links = markets.filter((m) => m.host).map((m) => ({ hrefLang: m.locale, href: `${protocol}://${m.host}${path}` }));
+  const fallback = markets.find((m) => m.code === defaultMarket && m.host);
+  if (fallback) links.push({ hrefLang: "x-default", href: `${protocol}://${fallback.host}${path}` });
+  return links;
+}
+
 exports.CLIENT_IP_HEADER = CLIENT_IP_HEADER;
+exports.COUNTRY_HEADERS = COUNTRY_HEADERS;
 exports.NOTE_MAX_LENGTH = NOTE_MAX_LENGTH;
 exports.StorefrontError = StorefrontError;
 exports.appendParams = appendParams;
@@ -1061,8 +1127,10 @@ exports.formatAvailabilityMessage = formatAvailabilityMessage;
 exports.formatMoney = formatMoney;
 exports.formatVoucherExpiry = formatVoucherExpiry;
 exports.generateIdempotencyKey = generateIdempotencyKey;
+exports.hreflangLinks = hreflangLinks;
 exports.isStorefrontError = isStorefrontError;
 exports.isTokenPublishable = isTokenPublishable;
+exports.negotiateLocale = negotiateLocale;
 exports.normalizeClientIp = normalizeClientIp;
 exports.normalizeNote = normalizeNote;
 exports.parseMoney = parseMoney;
@@ -1071,6 +1139,7 @@ exports.paymentErrorView = paymentErrorView;
 exports.paymentIdempotencyKey = paymentIdempotencyKey;
 exports.paymentMessages = paymentMessages;
 exports.paymentOutcome = paymentOutcome;
+exports.preferredLanguages = preferredLanguages;
 exports.productAvailability = productAvailability;
 exports.productListQuery = productListQuery;
 exports.promoProgressView = promoProgressView;
@@ -1079,6 +1148,9 @@ exports.resolveAvailability = resolveAvailability;
 exports.rewardLabel = rewardLabel;
 exports.safeHttpsUrl = safeHttpsUrl;
 exports.schemaAvailability = schemaAvailability;
+exports.storefrontDomainHeader = storefrontDomainHeader;
+exports.suggestMarket = suggestMarket;
 exports.toMoney = toMoney;
+exports.visitorCountry = visitorCountry;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map