@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/templates/storefront-shadcn/src/lib/identify-forward.ts

@@ -0,0 +1,152 @@
+import {
+  buildUpstreamHeaders,
+  getUpstreamConfig,
+  readMintedSessionToken,
+  type ForwardHeaders,
+} from './track-forward';
+
+/**
+ * Marketing-identity upstream forwarder (#1596).
+ *
+ * ONE implementation of "tell the ForgeCart shop API which ad click this
+ * shopper arrived from". The click IDs a landing URL carries (`gclid`,
+ * `fbclid`, `ttclid`) are read on the client by `lib/marketing-params.ts`,
+ * posted to the same-origin `/__fc/identify` relay, and land here as a single
+ * `setMarketingIdentifiers` mutation.
+ *
+ * Why a module of its own rather than a branch inside `track-forward.ts`: a
+ * click ID is not an event. It names the IDENTITY the events belong to, it is
+ * sent once per landing instead of once per batch, and the ad platforms read it
+ * back out of that identity months later when a conversion is reported. The two
+ * forwarders share their TRANSPORT and nothing else — `getUpstreamConfig`,
+ * `buildUpstreamHeaders` and `readMintedSessionToken` live next door and are
+ * imported rather than restated, so the session a request rides can never
+ * differ between them; the shapes stay apart because they describe different
+ * things.
+ *
+ * Same discipline as the event forwarder, for the same reasons: raw HTTP
+ * GraphQL (the generated SDK transports over one WebSocket whose connection
+ * pins ONE identity, and has no plain-HTTP query path), inert while
+ * `forgecart init` has not written `.env` yet, and EVERY failure mode —
+ * missing config, network, HTTP status, GraphQL errors — resolving to a typed
+ * negative outcome instead of a throw. Attribution must never break the page
+ * the shopper came for.
+ */
+
+/**
+ * The SDK's own `ShopSetMarketingIdentifiers` document, inlined verbatim.
+ *
+ * Kept character-identical to the shipped operation
+ * (`app/client-sdk-generators/src/operations/shop/marketing-identity.graphql`)
+ * so checking the two for drift is a diff rather than a reading. `identityId`
+ * belongs to that document and is deliberately not read below: the storefront
+ * has no use for the backend's internal id, and the client it answers has even
+ * less.
+ */
+const SET_MARKETING_IDENTIFIERS_MUTATION = `mutation ShopSetMarketingIdentifiers($input: SetMarketingIdentifiersInput!) {
+  setMarketingIdentifiers(input: $input) {
+    identityId
+    accepted
+    rejected
+  }
+}`;
+
+/**
+ * One click ID, shaped for the API's `MarketingIdentifierInput`.
+ *
+ * The client parser's `MarketingIdentifier` is the same pair by design — this
+ * declaration exists because the SERVER side of the hop mirrors the SDL (the
+ * sibling's `TrackEventInput` does the same), and the relay route rebuilds the
+ * pair from untrusted JSON rather than trusting anything the client typed.
+ */
+export interface MarketingIdentifierInput {
+  /** The registered identifier key the value is stored under. */
+  key: string;
+  /** The click ID exactly as the ad platform wrote it into the URL. */
+  value: string;
+}
+
+/**
+ * What the upstream made of the identifiers.
+ *
+ * `rejected` is NOT an error and must never be turned into one. The backend
+ * partitions the submitted keys against its identifier registry, stores the
+ * ones it knows, drops the ones it does not and REPORTS both — no throw, no
+ * rollback, no partial failure (`MarketingIdentityService.setIdentifiersForShop`).
+ * A key landing in `rejected` wrote no row and broke nothing; it means only
+ * that this storefront and the backend registry disagree about a spelling,
+ * which is a deployment fact worth being able to read and not a runtime
+ * condition to handle. Nothing downstream may treat a non-empty `rejected` as a
+ * reason to retry, to fail the request, or to hold up the page.
+ */
+export interface IdentifyOutcome {
+  /** Identifier keys the backend recognised and stored. */
+  accepted: readonly string[];
+  /** Keys it does not know — dropped upstream; see the note above. */
+  rejected: readonly string[];
+  /** Session token surfaced in the response extensions, if any. */
+  sessionToken: string | null;
+}
+
+interface GraphQLIdentifyResponse {
+  data?: {
+    setMarketingIdentifiers?: { accepted?: string[]; rejected?: string[] } | null;
+  } | null;
+  errors?: unknown[];
+  extensions?: Record<string, unknown>;
+}
+
+/** The outcome every failure mode answers with: nothing stored, nothing minted. */
+const NO_IDENTIFIERS_STORED: IdentifyOutcome = { accepted: [], rejected: [], sessionToken: null };
+
+/**
+ * Forward the captured click IDs as one raw HTTP GraphQL POST.
+ *
+ * One call for the whole list — the mutation takes an array and the backend
+ * writes them against a single identity, so there is no per-item sequencing to
+ * get wrong here (the event relay loops only because `trackEvent` takes one
+ * event at a time).
+ *
+ * Any failure — missing config, network, HTTP status, GraphQL errors —
+ * resolves to an empty outcome; the forwarder is best-effort by design and the
+ * outcome is terminal (callers never retry).
+ */
+export async function forwardMarketingIdentifiers(
+  identifiers: readonly MarketingIdentifierInput[],
+  forward: ForwardHeaders,
+): Promise<IdentifyOutcome> {
+  const upstream = getUpstreamConfig();
+  if (!upstream) return NO_IDENTIFIERS_STORED;
+
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers: buildUpstreamHeaders(upstream.channelToken, forward),
+      body: JSON.stringify({
+        query: SET_MARKETING_IDENTIFIERS_MUTATION,
+        variables: { input: { identifiers } },
+      }),
+    });
+    if (!response.ok) return NO_IDENTIFIERS_STORED;
+
+    const payload = (await response.json()) as GraphQLIdentifyResponse;
+    // Read the mint even when the mutation itself did not answer: a cookie-less
+    // request mints the session in middleware, BEFORE the resolver runs, so the
+    // token is real regardless of what happened to the identifiers — and the
+    // relay must persist it or the next request mints a second identity.
+    const capturedToken = readMintedSessionToken(payload.extensions);
+    const result = payload.data?.setMarketingIdentifiers;
+    if (!result) return { accepted: [], rejected: [], sessionToken: capturedToken };
+    return {
+      accepted: result.accepted ?? [],
+      rejected: result.rejected ?? [],
+      sessionToken: capturedToken,
+    };
+  } catch {
+    // Best-effort by design: an unreachable or still-booting backend must never
+    // break the landing page. The click ID is lost with the page view it came
+    // with, which is the accepted cost of never letting analytics hold up a
+    // shopper — no caller retries.
+    return NO_IDENTIFIERS_STORED;
+  }
+}

package/templates/storefront-shadcn/src/lib/locale/channel-locales-loader.ts

@@ -0,0 +1,169 @@
+import 'server-only';
+
+import { createChannelLocalesCache } from './channel-locales';
+import type { ChannelLocales, ChannelLocalesResolution } from './channel-locales';
+import { toChannelLocales } from './channel-locales-map';
+import type { RawChannelLocales } from './channel-locales-map';
+
+/**
+ * Binds the channel-language cache to the shop API (#1346, W1-8 / S1).
+ *
+ * Transport is a plain GraphQL POST, deliberately — NOT the SDK's shop client.
+ * This read happens inside the root layout, which is outside every Suspense
+ * boundary, so it sits on the first byte of every route. The SDK client's
+ * language is a per-CONNECTION header fixed at socket handshake, so using it
+ * here would put a WebSocket handshake plus an anonymous-session mint on that
+ * path, and a hung socket would hold the document open with no bound. The
+ * experiments config-fetch (`experiments.ts`) already reads the shop API this
+ * way for the same reason; this follows it, and adds the timeout that path
+ * lacks.
+ *
+ * Failure policy, in three layers, because this module decides what a
+ * storefront looks like when its backend is unwell:
+ *
+ *  1. Not configured yet — no fetch at all. The workspace-pod prewarm boots
+ *     this server with no `.env`, and the layout must render anyway.
+ *  2. Fetch fails with a warm cache — the cache serves the last good snapshot
+ *     and retries on the next request. Nothing here to do.
+ *  3. Fetch fails on a COLD process — {@link FALLBACK_LOCALES}. A site-wide
+ *     500 is the worst thing a crawler can be shown (5xx throttles crawl rate
+ *     and drops URLs), so the storefront renders instead. The fallback is
+ *     English-only, which is byte-for-byte what the root layout hardcoded
+ *     before this slice existed — so an outage degrades to the previous
+ *     behaviour rather than to something new. It renders, and it says so:
+ *     `resolved: false` rides the snapshot, and the metadata floor turns that
+ *     into `noindex` (#1347). Serving a guessed language is survivable;
+ *     letting a crawler INDEX the guess is not.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+
+/**
+ * The bound on how long the document shell may wait for the channel read.
+ * Short by intent: past this, serving the fallback beats holding the shell.
+ */
+const CHANNEL_FETCH_TIMEOUT_MS = 2_000;
+
+/**
+ * The channel snapshot the storefront's shell renders from.
+ *
+ * `ChannelLocales` plus the two facts that are not about languages but come
+ * from the same `activeChannel` document, and must come from the same SNAPSHOT
+ * of it: a shell that paired one window's language set with another window's
+ * shop name would be a torn read of the identical kind the locale resolution
+ * itself is built to avoid.
+ */
+export interface StorefrontChannel extends ChannelLocales {
+  /**
+   * The merchant's shop name, or null when unset. The title suffix (#1347) —
+   * `null` and `''` both mean "no suffix", and that emptiness rule lives with
+   * the title rule, not here: this module reports what the channel said.
+   */
+  shopName: string | null;
+  /**
+   * Whether this snapshot came from a real `activeChannel` read.
+   *
+   * FALSE is the honest admission that the storefront does not know what
+   * channel it is serving — an unconfigured scaffold, or a cold process whose
+   * backend it could not reach. It rides on the snapshot rather than being
+   * derived by the caller because it is a property OF the snapshot: a stale
+   * one still says `true`, and correctly so — its languages were established,
+   * they are merely a minute old.
+   */
+  resolved: boolean;
+}
+
+/**
+ * What an unconfigured scaffold, or a cold process with an unreachable
+ * backend, serves. For the UNCONFIGURED case `en` is not a guess about the
+ * merchant — it is the value `<html lang>` carried unconditionally before the
+ * locale layer existed, and nothing real is being served anyway (the prewarm
+ * contract: answer the request, do not crash).
+ *
+ * For a CONFIGURED store on a cold process it IS a guess, and it is marked as
+ * one: `resolved: false`. A channel whose default is not English briefly
+ * serves `<html lang="en">` over its own language and 404s its default-language
+ * prefix instead of canonicalizing it, and no value here can fix that — the
+ * scaffold never learns the channel's default language, since `.env` carries
+ * the token and the URLs and nothing else.
+ *
+ * What CAN be fixed is the asserting. A storefront that does not know its
+ * channel makes no indexable claim at all: `resolved: false` closes the
+ * metadata floor (`lib/seo/metadata.ts`), so the shell renders — the prewarm
+ * contract holds — while telling crawlers to ignore it. That is the same
+ * posture this template already takes for a deployment with no public origin,
+ * and it closes the #1346 hand-off recorded on #1347.
+ */
+const FALLBACK_LOCALES: StorefrontChannel = {
+  languageCodes: ['en'],
+  defaultLanguageCode: 'en',
+  shopName: null,
+  resolved: false,
+};
+
+const ACTIVE_CHANNEL_QUERY = `query ActiveChannelLocales {
+  activeChannel {
+    defaultLanguageCode
+    availableLanguageCodes
+    shopName
+  }
+}`;
+
+/**
+ * The shop name rides this read rather than one of its own: the layout already
+ * awaits this document on the first byte of every route, and a second cached
+ * fetch for one string would double that cost for a value the same response
+ * already carries.
+ */
+type RawActiveChannel = RawChannelLocales & { shopName?: string | null };
+
+interface ActiveChannelResponse {
+  data?: { activeChannel?: RawActiveChannel | null } | null;
+}
+
+/**
+ * THROWS on any failure, deliberately. The cache distinguishes "refresh
+ * failed, keep the good snapshot" from "cold start, nothing to serve", and it
+ * can only do that if this reports failure as failure. Returning a fallback
+ * here instead would cache English-only for a full TTL window on the first
+ * blip — rendering every locale in English while looking perfectly healthy.
+ */
+async function loadChannelLocales(): Promise<StorefrontChannel> {
+  if (!SHOP_API_URL || !CHANNEL_TOKEN) return FALLBACK_LOCALES;
+
+  const response = await fetch(SHOP_API_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'forgecart-token': CHANNEL_TOKEN },
+    body: JSON.stringify({ query: ACTIVE_CHANNEL_QUERY }),
+    signal: AbortSignal.timeout(CHANNEL_FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    throw new Error(`activeChannel read failed: HTTP ${response.status}`);
+  }
+  const payload = (await response.json()) as ActiveChannelResponse;
+  const channel = payload.data?.activeChannel;
+  if (!channel?.defaultLanguageCode) {
+    throw new Error('activeChannel read returned no defaultLanguageCode');
+  }
+  return { ...toChannelLocales(channel), shopName: channel.shopName ?? null, resolved: true };
+}
+
+const channelLocales = createChannelLocalesCache(loadChannelLocales);
+
+/**
+ * The channel and whether it offers `candidate`, from one snapshot — and never
+ * rejecting, whatever the backend is doing. This is the boundary where layer 3
+ * of the failure policy is applied: the cache propagates a cold-start failure
+ * so that the decision is made HERE, in one visible place, rather than being
+ * invented inside the cache.
+ */
+export async function resolveChannelLocales(
+  candidate: string | null,
+): Promise<ChannelLocalesResolution<StorefrontChannel>> {
+  try {
+    return await channelLocales.resolve(candidate);
+  } catch {
+    return { channel: FALLBACK_LOCALES, offered: false };
+  }
+}

package/templates/storefront-shadcn/src/lib/locale/channel-locales-map.ts

@@ -0,0 +1,46 @@
+import { isLocaleSegment } from './grammar';
+import type { ChannelLocales } from './channel-locales';
+
+/**
+ * The channel payload → {@link ChannelLocales} coercion (#1346, W1-8 / S1).
+ *
+ * Pure and SDK-type-free on purpose: this is the one place the shop API's
+ * shape can be got wrong, and keeping it importable by the template spec
+ * project means it is pinned exhaustively instead of exercised only through a
+ * live channel.
+ */
+
+/** The shape the shop API returns, with its own nullability. */
+export interface RawChannelLocales {
+  defaultLanguageCode: string;
+  /**
+   * NULLABLE in the schema (`availableLanguageCodes: [String!]`) and in the
+   * SDK (`Maybe<Array<...>>`). The schema's own comment says null means "none
+   * enabled beyond the default" and that storefronts coalesce to
+   * `[defaultLanguageCode]` — which is exactly what this function does.
+   */
+  availableLanguageCodes?: readonly string[] | null;
+}
+
+/**
+ * Coerce the channel payload into the non-null set the grammar consumes.
+ *
+ * Union-with-the-default FIRST, which makes the result null-safe and
+ * empty-safe in one expression and lets the single-language channel fall out
+ * of the rule rather than needing its own branch: its only language IS the
+ * default, so it never serves a prefix.
+ *
+ * The extras are filtered through {@link isLocaleSegment}, the default is not.
+ * A stray `en-GB` from a channel configured outside the platform's 2-char
+ * registry is unreachable as a URL — the grammar can never parse a prefix for
+ * it — so admitting it would only mint a language-switcher link to a page that
+ * 404s. The default is exempt because it is never URL-visible: it is the
+ * language served UNPREFIXED, so its spelling never has to survive a parse.
+ */
+export function toChannelLocales(raw: RawChannelLocales): ChannelLocales {
+  const codes = new Set<string>([raw.defaultLanguageCode]);
+  for (const code of raw.availableLanguageCodes ?? []) {
+    if (isLocaleSegment(code)) codes.add(code);
+  }
+  return { languageCodes: [...codes], defaultLanguageCode: raw.defaultLanguageCode };
+}

package/templates/storefront-shadcn/src/lib/locale/channel-locales.ts

@@ -0,0 +1,191 @@
+/**
+ * The channel's language set, cached per server process (#1346, epic
+ * launch#54 W1-8 / S1).
+ *
+ * The middleware cannot validate a locale — it is zero-fetch by contract — so
+ * a two-letter first segment reaches the layout as a CANDIDATE and is decided
+ * here, in the request-time hole.
+ *
+ * This cache sits on the critical path of the DOCUMENT SHELL of every route:
+ * the root layout must know the locale before it can write `<html lang>`, and
+ * that is structurally outside every Suspense boundary. Three requirements
+ * follow, and together they are the whole design of this module:
+ *
+ *  - **A language added a moment ago must work on its very first request.** A
+ *    plain TTL cache would 404 the new locale for up to a minute — exactly the
+ *    "I added German and the German page is broken" report this slice exists
+ *    to prevent. Hence: a MISS forces a live refetch before the answer is
+ *    allowed to be `false`.
+ *  - **But a miss is also what an unknown locale looks like.** Refetching on
+ *    every miss would turn `/zz/`, `/qq/`, `/aa/` … into one live call per
+ *    request, aimed at the storefront's own backend. Hence: at most ONE
+ *    miss-driven refetch per TTL window.
+ *  - **An expiry must never block a render, and a backend blip must never
+ *    become a 5xx.** A stale snapshot is served immediately while a refresh
+ *    runs behind it, and a refresh that fails leaves the last good snapshot in
+ *    place. Without this, one slow backend puts a full round-trip on the first
+ *    byte of every route once per window, and one unreachable backend turns
+ *    every page — including every 404 — into a site-wide 500. That is the most
+ *    damaging thing a crawler can see: 5xx throttles crawl rate site-wide and
+ *    drops URLs if it persists.
+ *
+ * Net behaviour: a real new language costs one extra fetch, once. A flood of
+ * junk locales costs one extra fetch, once, then is free. An expiry costs a
+ * background fetch and no latency. An outage costs nothing until the process
+ * restarts, and the caller decides what a cold start with no backend serves.
+ *
+ * The loader and the clock are injected so this logic is unit-testable with no
+ * network and no wall-clock waiting. The SDK loader is bound where the cache
+ * is consumed; this module stays free of both the SDK and the clock so the
+ * spec project can import it.
+ */
+
+/** The channel's advertised languages. */
+export interface ChannelLocales {
+  /** Every language the channel offers, including the default. */
+  languageCodes: readonly string[];
+  /** The language served UNPREFIXED. */
+  defaultLanguageCode: string;
+}
+
+/**
+ * One request's answer, derived from ONE snapshot.
+ *
+ * Returning both together is the point: resolving the channel and the
+ * candidate through two separate reads lets a request decide "render prefixed"
+ * against an old `defaultLanguageCode` while `offered` came from a snapshot in
+ * which that locale had BECOME the default — a torn read whose symptom is a
+ * page that should have 308'd rendering prefixed instead.
+ */
+export interface ChannelLocalesResolution<T extends ChannelLocales = ChannelLocales> {
+  channel: T;
+  offered: boolean;
+}
+
+/**
+ * Generic in the SNAPSHOT, because deciding `offered` is the only thing this
+ * cache does with it — everything else about the channel is a passenger.
+ *
+ * The passenger is not hypothetical: the storefront's shell also needs the
+ * shop name (the title suffix) and whether the read was authoritative at all
+ * (#1347). Both come from the SAME `activeChannel` document this cache already
+ * fetches, and they have to arrive on the same snapshot or the shell can pair
+ * one window's languages with another window's name. A second cached read
+ * would put a second round-trip on the first byte of every route, which is
+ * precisely what the docblock above rules out.
+ *
+ * Generic rather than widening {@link ChannelLocales} with those fields: this
+ * module is the LOCALE grammar's cache, its type is consumed by
+ * `decideRequestLocale`, and a shop name has no business in either. The
+ * constraint states exactly what is required of a snapshot, and anything
+ * further rides through untouched.
+ */
+export interface ChannelLocalesCache<T extends ChannelLocales = ChannelLocales> {
+  /** The current snapshot; refreshes behind the response once it is stale. */
+  get(): Promise<T>;
+  /**
+   * The channel AND whether it offers `candidate`, from a single snapshot. A
+   * miss against an existing snapshot forces one live reload before answering
+   * `false` — bounded to once per window, see the module docblock.
+   */
+  resolve(candidate: string | null): Promise<ChannelLocalesResolution<T>>;
+}
+
+export interface ChannelLocalesCacheOptions {
+  ttlMs?: number;
+  /** Injected clock — the specs drive time instead of waiting on it. */
+  now?: () => number;
+}
+
+/** The window S1 fixes for the channel-language snapshot. */
+export const CHANNEL_LOCALES_TTL_MS = 60_000;
+
+export function createChannelLocalesCache<T extends ChannelLocales>(
+  load: () => Promise<T>,
+  options: ChannelLocalesCacheOptions = {},
+): ChannelLocalesCache<T> {
+  const ttlMs = options.ttlMs ?? CHANNEL_LOCALES_TTL_MS;
+  const now = options.now ?? Date.now;
+
+  let snapshot: T | null = null;
+  let loadedAt = 0;
+  /** When a MISS last forced a reload, so the next miss can be answered free. */
+  let missReloadedAt: number | null = null;
+  /**
+   * The in-flight load, shared by every caller that arrives during it. A
+   * server handles requests concurrently; without this, a cold start under
+   * load would fan one expired snapshot out into N identical round-trips.
+   */
+  let inFlight: Promise<T> | null = null;
+
+  function isFresh(): boolean {
+    return snapshot !== null && now() - loadedAt < ttlMs;
+  }
+
+  async function reload(): Promise<T> {
+    if (inFlight) return inFlight;
+    inFlight = load();
+    try {
+      const loaded = await inFlight;
+      snapshot = loaded;
+      loadedAt = now();
+      return loaded;
+    } finally {
+      // Cleared on failure too, so a transient backend error does not pin a
+      // rejected promise as the permanent answer for every later request.
+      inFlight = null;
+    }
+  }
+
+  /**
+   * Refresh behind the response. The rejection is swallowed deliberately: the
+   * caller already has a usable snapshot, and an unhandled rejection here
+   * would take down the process for a failure that costs the request nothing.
+   * `loadedAt` is untouched on failure, so the next request retries.
+   */
+  function refreshInBackground(): void {
+    if (inFlight) return;
+    void reload().catch(() => undefined);
+  }
+
+  async function get(): Promise<T> {
+    if (snapshot !== null) {
+      if (!isFresh()) refreshInBackground();
+      return snapshot;
+    }
+    // Cold start only: there is nothing to serve, so this one awaits — and may
+    // reject. The caller decides what an unreachable backend serves on a cold
+    // process; this module will not invent a language set.
+    return reload();
+  }
+
+  async function resolve(candidate: string | null): Promise<ChannelLocalesResolution<T>> {
+    const hadSnapshot = snapshot !== null;
+    const channel = await get();
+    if (candidate === null) return { channel, offered: false };
+    if (channel.languageCodes.includes(candidate)) return { channel, offered: true };
+
+    // Loaded live in this very call, so the miss is authoritative — reloading
+    // again would ask the same question twice.
+    if (!hadSnapshot) return { channel, offered: false };
+
+    // Bounded: one miss-driven reload per window, however many junk locales
+    // arrive inside it.
+    if (missReloadedAt !== null && now() - missReloadedAt < ttlMs) {
+      return { channel, offered: false };
+    }
+
+    // Stamped on the ATTEMPT, not the result. Stamping after the await would
+    // leave the bound disarmed whenever the loader rejects — exactly the
+    // condition it exists to protect: a backend already failing, being asked
+    // again by every junk locale that arrives.
+    missReloadedAt = now();
+    // A failed miss-reload answers from the snapshot we already had rather
+    // than rejecting: this runs inside the document shell, where a throw is a
+    // site-wide 500 rather than a degraded section.
+    const reloaded = await reload().catch(() => channel);
+    return { channel: reloaded, offered: reloaded.languageCodes.includes(candidate) };
+  }
+
+  return { get, resolve };
+}