@forgecart/cli 2.202610052310.0 → 2.202610071755.0

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

@@ -0,0 +1,333 @@
+import {
+  deriveExposureEventId,
+  resolveExperimentAssignment,
+  type AssignmentResult,
+  type AssignmentSource,
+  type ExperimentAssignmentConfig,
+} from '@forgecart/sdk';
+import { cookies, headers } from 'next/headers';
+import { after } from 'next/server';
+import { cache } from 'react';
+import { uuidv7 } from 'uuidv7';
+
+import { SESSION_COOKIE } from './session-cookies';
+import { forwardTrackEvent, getUpstreamConfig, isObviousBot } from './track-forward';
+import type { TrackEventInput, UpstreamConfig } from './track-forward';
+
+/**
+ * Server-side A/B variant resolution (design doc Wave F-B).
+ *
+ * `getVariant(experimentKey)` is the ONE storefront API for experiments:
+ * Server Components call it and branch on the returned `variantKey` (variant
+ * payloads are code branches first, `payload` JSON second). Resolution is
+ * LOCAL — the SDK's deterministic assignment engine over a TTL-cached config
+ * — so variants render with zero flicker and zero added request round-trips.
+ *
+ * How the pieces fit:
+ *  - Config: the public `activeExperiments` shop query, fetched over raw
+ *    HTTP GraphQL with the hand-rolled `forgecart-token` header (the
+ *    `track-forward.ts` pattern — the template's pinned published SDK has no
+ *    plain-HTTP query path) and cached module-scope for
+ *    {@link CONFIG_TTL_MS} keyed by channel token. A fetch failure resolves
+ *    to "no experiments" (every caller renders the default branch) and is
+ *    cached for the same TTL, so a dead backend costs one failed fetch per
+ *    minute — never one per request.
+ *  - Subject: the `forgecart-visitor` cookie (S6). When absent, an id is
+ *    minted IN-REQUEST via a request-scoped `cache()` — never relying on
+ *    middleware→RSC cookie propagation (S6 doc rule; the middleware persists
+ *    the durable cookie, this module only needs a consistent value for the
+ *    current render). Same UUIDv7 value shape as the middleware mint.
+ *  - Forced entry: the `forgecart-exp-force` cookie the middleware merges
+ *    from `?fc-exp=` campaign URLs. The engine honors it only when the
+ *    experiment allows forced entry and the variant exists
+ *    (`assignmentSource: 'forced'`).
+ *  - Exposure: when the engine says `exposed` (hashed or forced), ONE
+ *    `experiment_exposure` marketing event is emitted per request inside
+ *    `next/server` `after()` — after the response, off the critical path —
+ *    through the shared `forwardTrackEvent` (never an HTTP self-call to the
+ *    relay, never the SDK's identity-pinning WebSocket). The event id is the
+ *    SDK's deterministic UUIDv5 over `salt:subjectKey:utcDay`, so re-renders
+ *    and multi-page sessions dedupe server-side to one exposure per subject
+ *    per UTC day.
+ *
+ * `currencyCode` is deliberately ABSENT from the exposure input: §A wants the
+ * session market's currency on exposures, but pre-cart the template server
+ * has no side-effect-free source for it — the shop API surfaces currency only
+ * via `activeOrder` (whose read AUTO-CREATES an order for a session, see
+ * `cart-actions.ts#getCart`) and the geo-seeded market lives in a session
+ * that a first-touch page view does not yet have. Inventing a source here
+ * (e.g. the channel default off a product read) would mislabel the segment;
+ * the field stays unset until the ingest side can stamp the session market
+ * server-side.
+ */
+
+const VISITOR_COOKIE = 'forgecart-visitor';
+const FORCED_ENTRY_COOKIE = 'forgecart-exp-force';
+
+/** Delivery-config cache TTL — the design doc's 60s config-plane freshness. */
+const CONFIG_TTL_MS = 60_000;
+
+/** Canonical textual UUID — the only visitor-cookie shape trusted as subject. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Backend slug grammar (`ExperimentService`) — gates keys read from cookies. */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * The SDK's own `ShopActiveExperiments` document, inlined — same rationale as
+ * `track-forward.ts`: the generated client is WebSocket-only, so the config
+ * read speaks plain HTTP GraphQL with the identical selection.
+ */
+const ACTIVE_EXPERIMENTS_QUERY = `query ShopActiveExperiments {
+  activeExperiments {
+    experimentKey
+    subjectType
+    version
+    salt
+    lifecycle
+    trafficBps
+    allowForcedEntry
+    variants {
+      key
+      weight
+      payload
+    }
+    winnerVariantKey
+  }
+}`;
+
+/** One variant as the `activeExperiments` shop query delivers it. */
+interface ActiveExperimentVariant {
+  key: string;
+  weight: number;
+  payload: Record<string, unknown> | null;
+}
+
+/** The public delivery projection of one experiment (FB2b contract). */
+interface ActiveExperiment {
+  experimentKey: string;
+  subjectType: 'visitor' | 'customer';
+  version: number;
+  salt: string;
+  lifecycle: 'running' | 'paused' | 'completed';
+  trafficBps: number;
+  allowForcedEntry: boolean;
+  variants: ActiveExperimentVariant[];
+  winnerVariantKey: string | null;
+}
+
+/** What a Server Component branches on. */
+export interface ExperimentVariantResult {
+  /**
+   * The assigned variant key, or `null` when the experiment is unknown /
+   * undelivered / malformed — callers treat `null` as "render the default
+   * branch", which keeps every page correct with zero experiments configured.
+   */
+  variantKey: string | null;
+  /**
+   * How the variant was decided: `'hashed'` (randomized cohort), `'forced'`
+   * (campaign entry — excluded from the randomized comparison), `'lifecycle'`
+   * (paused → control / completed → winner), or `null` (non-participant
+   * control or no experiment).
+   */
+  assignmentSource: AssignmentSource | null;
+  /** The variant's optional delivery payload (design doc Q5), if any. */
+  payload: Record<string, unknown> | null;
+}
+
+interface GraphQLActiveExperimentsResponse {
+  data?: { activeExperiments?: unknown } | null;
+  errors?: unknown[];
+}
+
+/** Module-scope 60s TTL cache — one config fetch per server per minute. */
+let configCache: {
+  channelToken: string;
+  expiresAt: number;
+  load: Promise<ActiveExperiment[]>;
+} | null = null;
+
+async function fetchActiveExperiments(upstream: UpstreamConfig): Promise<ActiveExperiment[]> {
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'forgecart-token': upstream.channelToken,
+      },
+      body: JSON.stringify({ query: ACTIVE_EXPERIMENTS_QUERY }),
+    });
+    if (!response.ok) return [];
+    const payload = (await response.json()) as GraphQLActiveExperimentsResponse;
+    const list = payload.data?.activeExperiments;
+    return Array.isArray(list) ? (list as ActiveExperiment[]) : [];
+  } catch {
+    // Experiments must never break the storefront: no config → every caller
+    // renders its default branch until the next TTL window retries.
+    return [];
+  }
+}
+
+function getActiveExperiments(): Promise<ActiveExperiment[]> {
+  const upstream = getUpstreamConfig();
+  // Inert before `forgecart init` writes `.env` (image-prewarm contract).
+  if (!upstream) return Promise.resolve([]);
+  const now = Date.now();
+  if (
+    configCache &&
+    configCache.channelToken === upstream.channelToken &&
+    now < configCache.expiresAt
+  ) {
+    return configCache.load;
+  }
+  configCache = {
+    channelToken: upstream.channelToken,
+    expiresAt: now + CONFIG_TTL_MS,
+    load: fetchActiveExperiments(upstream),
+  };
+  return configCache.load;
+}
+
+/**
+ * The assignment subject for this request: the S6 visitor cookie when it
+ * rode in, else ONE in-request UUIDv7 shared by every `getVariant` call of
+ * the render (request-scoped `cache()`). A cookie-less first page view thus
+ * gets a consistent assignment within its own render; the middleware's
+ * Set-Cookie makes the durable id authoritative from the next request on.
+ */
+const getRequestVisitorId = cache(async (): Promise<string> => {
+  const store = await cookies();
+  const existing = store.get(VISITOR_COOKIE)?.value;
+  if (existing && UUID_PATTERN.test(existing)) return existing;
+  return uuidv7();
+});
+
+/** The forced-entry map from the middleware-merged cookie, slug-validated. */
+const getForcedVariantMap = cache(async (): Promise<Record<string, string>> => {
+  const store = await cookies();
+  const raw = store.get(FORCED_ENTRY_COOKIE)?.value;
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    // `cookies()` already percent-decodes — `raw` is the JSON text.
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {};
+  const map: Record<string, string> = {};
+  for (const [experimentKey, variantKey] of Object.entries(parsed)) {
+    if (typeof variantKey !== 'string') continue;
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    map[experimentKey] = variantKey;
+  }
+  return map;
+});
+
+function toAssignmentConfig(experiment: ActiveExperiment): ExperimentAssignmentConfig {
+  return {
+    salt: experiment.salt,
+    lifecycle: experiment.lifecycle,
+    trafficBps: experiment.trafficBps,
+    allowForcedEntry: experiment.allowForcedEntry,
+    variants: experiment.variants.map(({ key, weight }) => ({ key, weight })),
+    winnerVariantKey: experiment.winnerVariantKey,
+  };
+}
+
+/**
+ * Emit the `experiment_exposure` marketing event inside `after()`. Request
+ * data (UA, client IP, session) is captured HERE, during render — `after()`
+ * callbacks run once the response is done and must not touch request APIs.
+ * The response is already sent when a session-less exposure reaches the shop
+ * API, so a token minted for it cannot be persisted — accepted: the relay's
+ * first client batch establishes the durable shopper session.
+ */
+async function scheduleExposure(
+  experiment: ActiveExperiment,
+  result: AssignmentResult,
+  visitorId: string,
+): Promise<void> {
+  const requestHeaders = await headers();
+  const userAgent = requestHeaders.get('user-agent') ?? '';
+  // Same bot policy as the relay: unambiguous crawlers emit nothing.
+  if (isObviousBot(userAgent)) return;
+  const forwardedFor = requestHeaders.get('x-forwarded-for');
+  const store = await cookies();
+  const sessionToken = store.get(SESSION_COOKIE)?.value ?? null;
+
+  const occurredAt = new Date();
+  const input: TrackEventInput = {
+    eventType: 'experiment_exposure',
+    // Deterministic UUIDv5 over salt:subjectKey:utcDay — every re-render of
+    // this subject today resubmits the SAME id and the backend dedupes.
+    eventId: deriveExposureEventId(experiment.salt, visitorId, occurredAt),
+    occurredAt: occurredAt.toISOString(),
+    properties: {
+      experimentKey: experiment.experimentKey,
+      variantKey: result.variantKey,
+      version: experiment.version,
+      subjectType: experiment.subjectType,
+      assignmentSource: result.assignmentSource,
+      visitorId,
+    },
+  };
+
+  after(async () => {
+    await forwardTrackEvent(input, { sessionToken, userAgent, forwardedFor });
+  });
+}
+
+/**
+ * Resolve the variant for one experiment. Request-scoped `cache()` keeps the
+ * whole render consistent — layout and page asking for the same key get one
+ * resolution and at most ONE exposure emission per request.
+ */
+export const getVariant = cache(async (experimentKey: string): Promise<ExperimentVariantResult> => {
+  const inert: ExperimentVariantResult = {
+    variantKey: null,
+    assignmentSource: null,
+    payload: null,
+  };
+  if (!SLUG_REGEX.test(experimentKey)) return inert;
+
+  const experiments = await getActiveExperiments();
+  const experiment = experiments.find((entry) => entry.experimentKey === experimentKey);
+  if (!experiment) return inert;
+
+  if (experiment.subjectType === 'customer') {
+    // The storefront server has no verified customer id (auth lives behind
+    // the shop API session) — a customer-scoped experiment renders as
+    // non-participant control here, with no exposure. Customer-subject
+    // resolution belongs to clients that KNOW the customer id.
+    const control = experiment.variants[0];
+    if (!control) return inert;
+    return { variantKey: control.key, assignmentSource: null, payload: control.payload ?? null };
+  }
+
+  const visitorId = await getRequestVisitorId();
+  const forcedVariantKey = (await getForcedVariantMap())[experimentKey] ?? null;
+
+  let result: AssignmentResult;
+  try {
+    result = resolveExperimentAssignment(toAssignmentConfig(experiment), {
+      subjectKey: visitorId,
+      forcedVariantKey,
+    });
+  } catch {
+    // A malformed delivery (out-of-bounds weight, empty variants) must
+    // never break rendering — the caller falls back to its default branch.
+    return inert;
+  }
+
+  if (result.exposed && result.variantKey !== null) {
+    await scheduleExposure(experiment, result, visitorId);
+  }
+
+  const variant = experiment.variants.find((entry) => entry.key === result.variantKey);
+  return {
+    variantKey: result.variantKey,
+    assignmentSource: result.assignmentSource,
+    payload: variant?.payload ?? null,
+  };
+});