@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/src/lib/shop-session.ts

@@ -0,0 +1,151 @@
+'use client';
+
+// The /shop subpath is the ONLY SDK entry browser code may import: the SDK
+// compiles to CommonJS (never tree-shaken), and only the /shop module graph
+// is guaranteed admin-free — the root barrel would bundle the admin client
+// into every shopper's browser (the pod image build greps chunks for exactly
+// that and fails).
+import { ForgeCartShopClient, extractError } from '@forgecart/sdk/shop';
+
+import { UNREACHABLE_ERROR, type ActionResult } from './action-result';
+import { syncShopSession } from './session-actions';
+
+/**
+ * The shopper's OWN shop websocket — the client half of the progressive
+ * stack. Sockets are session-based, so the session socket lives where the
+ * session lives: in the browser, one long-lived client per tab. The server
+ * never builds session-bearing sockets (its two clients are the anonymous
+ * channel singleton in `forgecart.ts` and the embedded backend's admin
+ * singleton); it only prefetches public data and mirrors the session cookie.
+ *
+ * Lifecycle:
+ *   - `initShopSession(config)` (the CartProvider mount) arms the singleton
+ *     with the channel coordinates; the socket itself opens lazily on the
+ *     first operation and the SDK's `lazyCloseTimeout` parks it when idle.
+ *   - The client boots its auth from the JS-readable mirror cookie
+ *     (`forgecart-session-client`), so a returning shopper's socket adopts
+ *     the same session SSR saw.
+ *   - After every operation, a newly-captured session token (the SDK reads
+ *     it from result extensions on the first mutation) is synced back into
+ *     BOTH cookies via the `syncShopSession` server action — the next SSR
+ *     pass sees the cart this socket built.
+ *
+ * Every operation returns the same `ActionResult` envelope the old Server
+ * Actions used, so calling components keep their error contract: typed
+ * in-band errors, never a throw.
+ */
+
+export interface ShopSessionConfig {
+  apiUrl: string;
+  channelToken: string;
+  /** The request's resolved locale — the session speaks the page's language. */
+  languageCode: string;
+}
+
+const SESSION_MIRROR_COOKIE = 'forgecart-session-client';
+
+/**
+ * Browser-readable mirror of the httpOnly `forgecart-visitor` cookie,
+ * minted by the middleware (#1079 P1). Its value rides the SDK's
+ * `forgecart-visitor` WS connection-params header so visitor-subject
+ * experiment goals stamp server-side.
+ */
+const VISITOR_MIRROR_COOKIE = 'forgecart-visitor-client';
+
+let config: ShopSessionConfig | null = null;
+let client: ForgeCartShopClient | null = null;
+let syncedToken: string | null = null;
+
+/** Read a JS-visible mirror cookie (null outside the browser or when absent). */
+function readMirrorCookie(name: string): string | null {
+  if (typeof document === 'undefined') return null;
+  const entry = document.cookie
+    .split('; ')
+    .find((candidate) => candidate.startsWith(`${name}=`));
+  if (!entry) return null;
+  const value = decodeURIComponent(entry.slice(name.length + 1));
+  return value.length > 0 ? value : null;
+}
+
+/** Read the session mirror cookie (null outside the browser or when absent). */
+export function readMirrorSession(): string | null {
+  return readMirrorCookie(SESSION_MIRROR_COOKIE);
+}
+
+/**
+ * Arm the singleton with the channel coordinates (idempotent; provider mount).
+ *
+ * A locale switch is a full document load — the switcher uses plain anchors
+ * precisely so the language cannot go stale — which resets this module and
+ * rebuilds the client at the new language. The re-sync below covers the
+ * remaining case: a client-side navigation that somehow changes the resolved
+ * locale would otherwise leave a live socket speaking the previous language
+ * for the rest of the session. `setLanguageCode` disposes and re-handshakes
+ * the socket, so it is called ONLY on an actual change.
+ */
+export function initShopSession(next: ShopSessionConfig): void {
+  const previous = config;
+  config = next;
+  if (client && previous && previous.languageCode !== next.languageCode) {
+    client.setLanguageCode(next.languageCode);
+  }
+}
+
+/** Whether the session socket can exist (configured scaffold + browser). */
+export function isSessionReady(): boolean {
+  return config !== null && typeof window !== 'undefined';
+}
+
+function ensureClient(): ForgeCartShopClient {
+  if (!config) {
+    throw new Error(
+      'Shop session not initialized — CartProvider must mount with shopConfig first.',
+    );
+  }
+  if (!client) {
+    client = new ForgeCartShopClient({
+      endpoint: config.apiUrl,
+      channelToken: config.channelToken,
+      // Fixed at handshake — the cart, checkout and every error message on
+      // this socket answer in the language the URL resolved to.
+      languageCode: config.languageCode,
+      // The visitor mirror is minted by the middleware before any page can
+      // mount the provider, so it is present on every real navigation; when
+      // it is somehow absent the client simply sends no visitor header and
+      // visitor-subject goals stay unstamped (never guess — #1079).
+      visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
+    });
+    const existing = readMirrorSession();
+    if (existing) {
+      client.setAuthToken(existing);
+      syncedToken = existing;
+    }
+  }
+  return client;
+}
+
+/**
+ * Run one session operation on the shopper's socket and return the typed
+ * envelope. Session capture: when the operation minted or rotated the
+ * session, the new token is synced into the cookies fire-and-forget —
+ * a sync failure never breaks the shopper's interaction.
+ */
+export async function runSessionOp<T>(
+  op: (client: ForgeCartShopClient) => Promise<T>,
+): Promise<ActionResult<T>> {
+  if (!isSessionReady()) {
+    return { ok: false, error: UNREACHABLE_ERROR };
+  }
+  const live = ensureClient();
+  try {
+    const data = await op(live);
+    const token = live.getAuthToken();
+    if (token && token !== syncedToken) {
+      syncedToken = token;
+      void syncShopSession(token).catch(() => undefined);
+    }
+    return { ok: true, data };
+  } catch (error) {
+    return { ok: false, error: extractError(error) ?? UNREACHABLE_ERROR };
+  }
+}

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

@@ -0,0 +1,200 @@
+/**
+ * Shared marketing-event upstream forwarder (design doc S7 + F-B).
+ *
+ * ONE implementation of "send one trackEvent to the ForgeCart shop API over
+ * plain HTTP GraphQL", used by both server-side emitters:
+ *
+ *   - the `/__fc/track` relay route (client batches — page_view, cta_click,
+ *     heartbeat, …), which loops this per item;
+ *   - `experiments.ts` (F-B), which emits `experiment_exposure` inside
+ *     `next/server` `after()` — the exposure MUST NOT self-call the relay
+ *     over HTTP (an extra localhost round-trip that breaks the moment the
+ *     server is bound behind a proxy) and MUST NOT use the SDK's WebSocket
+ *     singleton (its connection pins one identity; design doc F-B blocker).
+ *
+ * Why raw HTTP GraphQL: the generated SDK transports operations over one
+ * WebSocket whose connection pins ONE identity — the relay/exposure path
+ * instead sends each request with the CURRENT shopper session as
+ * `Authorization: Bearer`, so attribution follows the shopper. The generated
+ * SDK also has no plain-HTTP query path, hence the hand-rolled POST (the shop
+ * API serves HTTP POST at the same `/shop-api` URL).
+ *
+ * Config is env-backed (`forgecart init` writes `.env`); before that
+ * exists (the workspace-pod image prewarm) `getUpstreamConfig()` answers
+ * `null` and every caller stays inert — the storefront never crashes over
+ * missing analytics config.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+
+/**
+ * Conservative bot gate shared by every server-side emitter: only UA
+ * substrings that are unambiguously non-human (crawlers and CLI fetchers).
+ * Real browsers never match; an absent UA does NOT match (absence is not
+ * obvious, and losing real events costs more than relaying a stray
+ * programmatic call the backend's reputation flags catch).
+ */
+const BOT_UA_SUBSTRINGS = ['bot', 'spider', 'crawl', 'curl', 'wget'];
+
+/**
+ * The SDK's own `ShopTrackEvent` document, inlined: the generated client is
+ * WebSocket-only, so this module speaks plain HTTP GraphQL with the same shape.
+ */
+const TRACK_EVENT_MUTATION = `mutation ShopTrackEvent($input: TrackEventInput!) {
+  trackEvent(input: $input) {
+    eventId
+    accepted
+  }
+}`;
+
+/** The channel-scoped upstream the storefront server talks to. */
+export interface UpstreamConfig {
+  shopApiUrl: string;
+  channelToken: string;
+}
+
+/** The shop API's `TrackEventInput` — validated allowlist, never raw client JSON. */
+export interface TrackEventInput {
+  eventType: string;
+  eventId?: string;
+  occurredAt?: string;
+  properties?: Record<string, unknown>;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  currencyCode?: string;
+}
+
+/** Per-request identity/enrichment headers forwarded upstream with one event. */
+export interface ForwardHeaders {
+  /** Current shopper session riding as `Authorization: Bearer`, if any. */
+  sessionToken: string | null;
+  /** The browser's own User-Agent, forwarded for device enrichment. */
+  userAgent: string;
+  /**
+   * The browser's low-entropy Client Hints (`sec-ch-ua`, `sec-ch-ua-mobile`,
+   * `sec-ch-ua-platform`), mirrored verbatim so device identification can
+   * outrank the frozen UA per-field (#1014). Chromium sends the trio on
+   * every request — no handshake, no `Accept-CH` — so this is a pure
+   * pass-through; absent on non-Chromium browsers.
+   */
+  secChUa?: string;
+  secChUaMobile?: string;
+  secChUaPlatform?: string;
+  /**
+   * Client IP as `x-forwarded-for` (the proxy-standard contract the shop API
+   * trusts) — NEVER ForgeCart's edge-secret-gated client-IP override header
+   * (design doc S7): unsigned use would collapse per-IP rate limits onto the
+   * storefront server's IP and geo-seed wrong market/currency defaults.
+   */
+  forwardedFor: string | null;
+}
+
+export interface UpstreamOutcome {
+  accepted: boolean;
+  eventId: string | null;
+  /** Session token surfaced in the response extensions, if any. */
+  sessionToken: string | null;
+}
+
+interface GraphQLTrackResponse {
+  data?: { trackEvent?: { eventId?: string; accepted?: boolean } | null } | null;
+  errors?: unknown[];
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * The configured upstream, or `null` before `forgecart init` writes
+ * `.env` (the image-prewarm contract — callers must stay inert).
+ */
+export function getUpstreamConfig(): UpstreamConfig | null {
+  if (!SHOP_API_URL || !CHANNEL_TOKEN) return null;
+  return { shopApiUrl: SHOP_API_URL, channelToken: CHANNEL_TOKEN };
+}
+
+/** True when the UA is unambiguously a crawler/CLI fetcher — skip emission. */
+export function isObviousBot(userAgent: string): boolean {
+  const normalized = userAgent.toLowerCase();
+  return BOT_UA_SUBSTRINGS.some((substring) => normalized.includes(substring));
+}
+
+/**
+ * The header set every upstream call carries.
+ *
+ * ONE builder, shared with the marketing-identity forwarder
+ * (`identify-forward.ts`), because both speak about the SAME shopper: the
+ * session riding as `Authorization` decides which identity a row is written to,
+ * so a header set that drifted between them would split one visitor in two and
+ * nothing downstream could put them back together.
+ */
+export function buildUpstreamHeaders(
+  channelToken: string,
+  { sessionToken, userAgent, forwardedFor, secChUa, secChUaMobile, secChUaPlatform }: ForwardHeaders,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    'forgecart-token': channelToken,
+  };
+  if (sessionToken) headers['Authorization'] = `Bearer ${sessionToken}`;
+  if (userAgent) headers['user-agent'] = userAgent;
+  if (forwardedFor) headers['x-forwarded-for'] = forwardedFor;
+  if (secChUa) headers['sec-ch-ua'] = secChUa;
+  if (secChUaMobile) headers['sec-ch-ua-mobile'] = secChUaMobile;
+  if (secChUaPlatform) headers['sec-ch-ua-platform'] = secChUaPlatform;
+  return headers;
+}
+
+/**
+ * The session the shop API minted for a cookie-less request, if it minted one.
+ *
+ * Surfaced in the response `extensions` exactly once. Shared with the identity
+ * forwarder for the same reason the headers are: both relays may ESTABLISH the
+ * shopper's `forgecart-session` cookie from this value, and two readings of
+ * "did the upstream mint a session" would eventually mean two cookies.
+ */
+export function readMintedSessionToken(
+  extensions: Record<string, unknown> | undefined,
+): string | null {
+  const minted = extensions?.['forgecart-auth-token'];
+  return typeof minted === 'string' && minted.length > 0 ? minted : null;
+}
+
+/**
+ * Forward one event as a raw HTTP GraphQL POST. Any failure — missing config,
+ * network, HTTP status, GraphQL errors — resolves to `accepted:false`; the
+ * forwarder is best-effort by design (analytics must never break the
+ * storefront) and `accepted:false` is terminal (callers never retry).
+ */
+export async function forwardTrackEvent(
+  input: TrackEventInput,
+  forward: ForwardHeaders,
+): Promise<UpstreamOutcome> {
+  const upstream = getUpstreamConfig();
+  if (!upstream) return { accepted: false, eventId: null, sessionToken: null };
+
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers: buildUpstreamHeaders(upstream.channelToken, forward),
+      body: JSON.stringify({ query: TRACK_EVENT_MUTATION, variables: { input } }),
+    });
+    if (!response.ok) return { accepted: false, eventId: null, sessionToken: null };
+
+    const payload = (await response.json()) as GraphQLTrackResponse;
+    const capturedToken = readMintedSessionToken(payload.extensions);
+    const trackEvent = payload.data?.trackEvent;
+    if (!trackEvent) return { accepted: false, eventId: null, sessionToken: capturedToken };
+    return {
+      accepted: trackEvent.accepted === true,
+      eventId: trackEvent.eventId ?? null,
+      sessionToken: capturedToken,
+    };
+  } catch {
+    // Best-effort by design: an unreachable/booting backend must never break
+    // the storefront, and `accepted:false` is terminal — no caller retries.
+    return { accepted: false, eventId: null, sessionToken: null };
+  }
+}

package/templates/storefront-shadcn/src/lib/uuid.ts

@@ -0,0 +1,19 @@
+/**
+ * v4 UUID that works in EVERY browsing context this storefront serves from.
+ *
+ * `crypto.randomUUID` is secure-context gated: it exists on https origins and
+ * on localhost, but NOT on plain-http LAN/preview hosts — exactly the local
+ * k3s preview origin (`http://<code>.127.0.0.1.nip.io:8081`) the dev recipe
+ * and the dashboard-e2e forge suite drive. A bare call there is a TypeError
+ * mid-render (the checkout AddressStep crash, 2026-08-09). `getRandomValues`
+ * carries no such gate, so mint the same v4 shape by hand when the fast path
+ * is missing.
+ */
+export function mintUuid(): string {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}