@forgecart/cli 2.202607161748.0 → 2.202607202320.0

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

@@ -0,0 +1,158 @@
+/**
+ * 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;
+  /**
+   * 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));
+}
+
+/**
+ * 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,
+  { sessionToken, userAgent, forwardedFor }: ForwardHeaders,
+): Promise<UpstreamOutcome> {
+  const upstream = getUpstreamConfig();
+  if (!upstream) return { accepted: false, eventId: null, sessionToken: null };
+
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    'forgecart-token': upstream.channelToken,
+  };
+  if (sessionToken) headers['Authorization'] = `Bearer ${sessionToken}`;
+  if (userAgent) headers['user-agent'] = userAgent;
+  if (forwardedFor) headers['x-forwarded-for'] = forwardedFor;
+
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers,
+      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 minted = payload.extensions?.['forgecart-auth-token'];
+    const capturedToken = typeof minted === 'string' && minted.length > 0 ? minted : null;
+    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/src/middleware.ts

@@ -0,0 +1,199 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { uuidv7 } from 'uuidv7';
+
+/**
+ * Visitor-identity + forced-experiment-entry middleware (design doc S6 + F-B).
+ *
+ * S6 — visitor identity. Mints the durable anonymous visitor key — the
+ * `forgecart-visitor` cookie (UUIDv7, so ids sort by first-touch time) —
+ * exactly once per browser. It is the A/B-test subject key and a
+ * marketing-event property; it is deliberately NOT a session and NOT a
+ * marketing identity.
+ *
+ * Contract:
+ *  - Mint ONLY when the cookie is absent. An identified visitor's response
+ *    carries NO `Set-Cookie` at all — re-sending it on every response would
+ *    make every page uncacheable for shared caches.
+ *  - Zero fetches, zero environment reads: the workspace-pod prewarm boots
+ *    this dev server with no `.env`, and the middleware must be inert
+ *    to that (it never crashes a request, env or not).
+ *  - Harmless on `<Link>` prefetches: they carry cookies like any navigation,
+ *    so an identified visitor's prefetch passes straight through; page-view
+ *    EMISSION stays in the client tracker precisely because prefetches reach
+ *    middleware (design doc §H.1) — this file only persists the id.
+ *  - Infra routes are excluded via the matcher: `/ping` (the pod readiness
+ *    probe polls it forever — it must stay zero-overhead and byte-stable) and
+ *    `/__forge_beacon` (error beacon; a browser that reaches it already has
+ *    the cookie from the page), plus Next static internals.
+ *
+ * F-B — forced campaign entry. Campaign URLs carry
+ * `?fc-exp=<experimentKey>:<variantKey>[,<experimentKey>:<variantKey>…]`
+ * (at most {@link FORCED_URL_ENTRY_CAP} entries; both sides must match the
+ * backend's slug grammar). Valid entries MERGE into the `forgecart-exp-force`
+ * cookie — a JSON map `{ experimentKey: variantKey }`, httpOnly (server-read
+ * only), 30 days — and the request continues WITHOUT a redirect, so the
+ * campaign link stays shareable (the leak is the point). Whether a forced key
+ * actually overrides the hash is decided downstream by the assignment engine
+ * (`allowForcedEntry` + variant existence) — the middleware only persists.
+ *
+ * The merged map is ALSO written back onto this request's own `cookie` header
+ * (`NextResponse.next({ request })`), so the landing render itself already
+ * sees the forced variant — Set-Cookie alone would only reach the NEXT
+ * request. `getVariant()` still never relies on middleware→RSC cookie
+ * propagation for the VISITOR id (it reads-else-mints within a
+ * request-scoped cache); the forced map is different: it either rode in on
+ * the request cookie or is deterministically rewritten here.
+ */
+
+const VISITOR_COOKIE_NAME = 'forgecart-visitor';
+
+/** 400 days — Chrome's upper bound on cookie lifetime (RFC 6265bis). */
+const VISITOR_COOKIE_MAX_AGE_SECONDS = 400 * 24 * 60 * 60;
+
+/** Forced-entry URL param + cookie (design doc F-B). */
+const FORCED_ENTRY_PARAM = 'fc-exp';
+const FORCED_ENTRY_COOKIE_NAME = 'forgecart-exp-force';
+
+/** 30 days — the campaign-entry window the design doc fixes. */
+const FORCED_ENTRY_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+
+/** At most this many `exp:variant` entries are honored per URL (design doc). */
+const FORCED_URL_ENTRY_CAP = 3;
+
+/**
+ * At most this many experiments are retained in the merged cookie (oldest
+ * evicted first). At the slug grammar's 64-char ceiling per side that keeps
+ * the serialized JSON well under the 4096-byte browser cookie cap, so a
+ * hostile chain of campaign URLs can never grow the header unboundedly.
+ */
+const FORCED_COOKIE_ENTRY_CAP = 12;
+
+/**
+ * The backend's experiment/variant slug grammar
+ * (`ExperimentService`'s SLUG_REGEX) — both sides of every `exp:variant`
+ * entry must match it or the entry is dropped.
+ */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * Parse the raw `?fc-exp=` value into at most {@link FORCED_URL_ENTRY_CAP}
+ * slug-valid `experimentKey → variantKey` entries (later duplicates of the
+ * same experiment win; invalid entries are dropped silently — a mangled
+ * campaign URL must still serve the page). `null` when nothing valid remains.
+ */
+function parseForcedEntryParam(raw: string | null): Map<string, string> | null {
+  if (!raw) return null;
+  const entries = new Map<string, string>();
+  for (const item of raw.split(',')) {
+    const separatorAt = item.indexOf(':');
+    if (separatorAt === -1) continue;
+    const experimentKey = item.slice(0, separatorAt);
+    const variantKey = item.slice(separatorAt + 1);
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    if (!entries.has(experimentKey) && entries.size >= FORCED_URL_ENTRY_CAP) continue;
+    entries.set(experimentKey, variantKey);
+  }
+  return entries.size > 0 ? entries : null;
+}
+
+/**
+ * Read the existing `forgecart-exp-force` cookie into slug-valid entries.
+ * Malformed JSON / shapes are discarded wholesale — the cookie is
+ * client-tamperable, and the next valid campaign URL rewrites it anyway.
+ */
+function readForcedEntryCookie(request: NextRequest): Map<string, string> {
+  const entries = new Map<string, string>();
+  const raw = request.cookies.get(FORCED_ENTRY_COOKIE_NAME)?.value;
+  if (!raw) return entries;
+  let parsed: unknown;
+  try {
+    // `request.cookies` already percent-decodes — `raw` is the JSON text.
+    parsed = JSON.parse(raw);
+  } catch {
+    return entries;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return entries;
+  for (const [experimentKey, variantKey] of Object.entries(parsed)) {
+    if (typeof variantKey !== 'string') continue;
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    entries.set(experimentKey, variantKey);
+  }
+  return entries;
+}
+
+/**
+ * Merge URL entries over the stored map (URL wins; re-set keys move to the
+ * newest position) and evict oldest entries past {@link FORCED_COOKIE_ENTRY_CAP}.
+ * Returns the cookie-ready serialized value, or `null` when the URL carried
+ * no valid entry (the common case — zero cookie work on normal traffic).
+ */
+function mergeForcedEntries(request: NextRequest): string | null {
+  const fromUrl = parseForcedEntryParam(request.nextUrl.searchParams.get(FORCED_ENTRY_PARAM));
+  if (!fromUrl) return null;
+  const merged = readForcedEntryCookie(request);
+  for (const [experimentKey, variantKey] of fromUrl) {
+    merged.delete(experimentKey);
+    merged.set(experimentKey, variantKey);
+  }
+  while (merged.size > FORCED_COOKIE_ENTRY_CAP) {
+    const oldest = merged.keys().next().value;
+    if (oldest === undefined) break;
+    merged.delete(oldest);
+  }
+  // RAW JSON on purpose: Next's cookie APIs percent-encode on serialize and
+  // decode on parse — symmetrically for the response Set-Cookie AND the
+  // request-header rewrite below — so pre-encoding here would double-encode.
+  return JSON.stringify(Object.fromEntries(merged));
+}
+
+export function middleware(request: NextRequest): NextResponse {
+  const forcedEntryValue = mergeForcedEntries(request);
+  const mintVisitor = !request.cookies.has(VISITOR_COOKIE_NAME);
+  if (!forcedEntryValue && !mintVisitor) {
+    return NextResponse.next();
+  }
+
+  let response: NextResponse;
+  if (forcedEntryValue) {
+    // Rewrite this request's own cookie header so the landing render already
+    // resolves the forced variant (Set-Cookie alone reaches only the NEXT
+    // request), then persist for subsequent navigations. No redirect — the
+    // campaign URL stays shareable.
+    request.cookies.set(FORCED_ENTRY_COOKIE_NAME, forcedEntryValue);
+    response = NextResponse.next({ request: { headers: request.headers } });
+    response.cookies.set({
+      name: FORCED_ENTRY_COOKIE_NAME,
+      value: forcedEntryValue,
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      maxAge: FORCED_ENTRY_COOKIE_MAX_AGE_SECONDS,
+      path: '/',
+    });
+  } else {
+    response = NextResponse.next();
+  }
+
+  if (mintVisitor) {
+    // `secure` is honored on https (deployed storefronts) and on localhost;
+    // browsers may drop it on other plain-http dev hosts — acceptable, since a
+    // stable visitor identity is a production concern, not a preview one.
+    response.cookies.set({
+      name: VISITOR_COOKIE_NAME,
+      value: uuidv7(),
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      maxAge: VISITOR_COOKIE_MAX_AGE_SECONDS,
+      path: '/',
+    });
+  }
+  return response;
+}
+
+export const config = {
+  // Every page and route EXCEPT Next internals/static assets and the infra
+  // routes documented above.
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|ping|__forge_beacon).*)'],
+};

package/templates/storefront/src/components/ForgeAnalytics.tsx

@@ -1,128 +0,0 @@
-'use client';
-
-import { ForgeCartShopClient } from '@forgecart/sdk';
-import { usePathname } from 'next/navigation';
-import { useEffect } from 'react';
-
-/**
- * Storefront analytics tracker. Renders nothing.
- *
- * Emits the marketing events that drive the dashboard's live-visitor count and
- * realtime map:
- *
- *   - `page_view` on the initial load and on every App-Router route change;
- *   - `heartbeat` every {@link HEARTBEAT_MS} while the tab is VISIBLE (plus one
- *     immediately on refocus), so an idle-but-open tab stays inside the live
- *     window. Heartbeats are liveness plumbing only — the backend excludes
- *     them from every event-counting aggregate.
- *
- * Identity needs no code here: the SDK's WebSocket connect mints an anonymous
- * shop session server-side, captures the returned token, and persists it in
- * localStorage — so every event from this browser rides one identity, and the
- * server enriches geo/device from the connection's own IP/UA.
- *
- * Two deliberate suppressions:
- *   - missing config (the pod image pre-renders the template before
- *     `forgecart init` writes `.env.local`) → the tracker is inert;
- *   - framed embeds (`window.parent !== window`) → the visual editor's
- *     artboard preview never counts its own admin as a live visitor. A normal
- *     top-level tab on the same URL still counts.
- *
- * Unlike `ForgeErrorBeacon` there is NO `NODE_ENV` gate — tracking is a
- * production feature. Every send is fire-and-forget and swallows failures:
- * analytics must never break the storefront.
- */
-
-const HEARTBEAT_MS = 60_000;
-/** Minimum spacing between sends of the same signal (StrictMode remounts, rapid refocus). */
-const DEDUP_MS = 30_000;
-
-let client: ForgeCartShopClient | null = null;
-let lastPageView: { path: string; at: number } | null = null;
-let lastHeartbeatAt = 0;
-
-function getClient(shopApiUrl: string, channelToken: string): ForgeCartShopClient {
-  if (!client) {
-    client = new ForgeCartShopClient({ endpoint: shopApiUrl, channelToken });
-  }
-  return client;
-}
-
-async function send(
-  shopApiUrl: string,
-  channelToken: string,
-  eventType: string,
-  properties?: Record<string, unknown>,
-): Promise<void> {
-  try {
-    await getClient(shopApiUrl, channelToken).marketingEvent.shopTrackEvent({
-      input: { eventType, properties },
-    });
-  } catch {
-    // Best-effort by design: a failed send (offline, rate-limited, booting
-    // backend) must never surface in the storefront.
-  }
-}
-
-export function ForgeAnalytics({
-  shopApiUrl,
-  channelToken,
-}: {
-  shopApiUrl: string;
-  channelToken: string;
-}) {
-  const pathname = usePathname();
-
-  // page_view — initial load + every route change.
-  useEffect(() => {
-    if (!shopApiUrl || !channelToken) return;
-    if (window.parent !== window) return;
-    const now = Date.now();
-    if (lastPageView && lastPageView.path === pathname && now - lastPageView.at < DEDUP_MS) {
-      return;
-    }
-    lastPageView = { path: pathname, at: now };
-    void send(shopApiUrl, channelToken, 'page_view', { path: pathname });
-  }, [shopApiUrl, channelToken, pathname]);
-
-  // heartbeat — while visible, plus one on refocus; paused while hidden.
-  useEffect(() => {
-    if (!shopApiUrl || !channelToken) return;
-    if (window.parent !== window) return;
-
-    let interval: ReturnType<typeof setInterval> | null = null;
-
-    const beat = () => {
-      const now = Date.now();
-      if (now - lastHeartbeatAt < DEDUP_MS) return;
-      lastHeartbeatAt = now;
-      void send(shopApiUrl, channelToken, 'heartbeat');
-    };
-    const start = () => {
-      if (interval !== null) return;
-      interval = setInterval(beat, HEARTBEAT_MS);
-    };
-    const stop = () => {
-      if (interval === null) return;
-      clearInterval(interval);
-      interval = null;
-    };
-    const onVisibility = () => {
-      if (document.visibilityState === 'visible') {
-        beat();
-        start();
-      } else {
-        stop();
-      }
-    };
-
-    document.addEventListener('visibilitychange', onVisibility);
-    if (document.visibilityState === 'visible') start();
-    return () => {
-      document.removeEventListener('visibilitychange', onVisibility);
-      stop();
-    };
-  }, [shopApiUrl, channelToken]);
-
-  return null;
-}