@web-my-money/studio-consumer 1.0.0

package/src/content/index.ts

@@ -0,0 +1,27 @@
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "1.0.0";
+
+export {
+  createContentClient,
+  type ContentClient,
+  type ContentManifest,
+  type ManifestSlot,
+  type StudioForm,
+} from "./payload";
+export { createManifestHandler } from "./manifest-handler";
+export { createRevalidateHandler } from "./revalidate-handler";
+export { studioFrameAncestors } from "./headers";
+export {
+  overrideValueForDict,
+  resolveLocalized,
+  setPath,
+  withSlotOverride,
+} from "./dict-overrides";
+export {
+  WmmEditOverlay,
+  StudioSlotPreviewBridge,
+  StudioFormPreviewBridge,
+  type PreviewableSlot,
+  type StudioPreviewFormProps,
+  type StudioPreviewFormComponent,
+} from "./preview";

package/src/content/manifest-handler.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from "next/server";
+import type { ContentManifest } from "./payload";
+
+/**
+ * Public content manifest route handler — what this site declares as editable,
+ * with each slot's current code baseline resolved from the app's own dictionary.
+ * Studio pulls this to reconcile its slots (structure + defaults; overrides
+ * untouched). Public and non-sensitive: it only exposes copy that already ships
+ * in the site's HTML.
+ *
+ * Takes the app's own `getManifest` so the manifest itself — the content model —
+ * stays in the consuming app, not in this package.
+ *
+ * The consumer's route file must ALSO export `export const dynamic =
+ * "force-dynamic";` alongside `export const GET = createManifestHandler(...)`.
+ * The source route carried that export at module scope, and Next requires it
+ * literally in the route file — re-exporting it through this factory would not
+ * register with Next's route config, so this package cannot carry it for you.
+ * Leaving it off silently changes the route from always-fresh to
+ * statically-cached at build time, which means Studio's manifest sync would
+ * reconcile against stale slot defaults instead of the live dictionary.
+ */
+export function createManifestHandler(
+  getManifest: () => Promise<ContentManifest>,
+): () => Promise<Response> {
+  return async function GET() {
+    const manifest = await getManifest();
+    return NextResponse.json(manifest, {
+      headers: {
+        "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
+      },
+    });
+  };
+}

package/src/content/payload.ts

@@ -0,0 +1,414 @@
+import "server-only";
+import { cache } from "react";
+import { cookies, headers } from "next/headers";
+// Shared with the Studio slot-preview bridge, which runs this same merge in the
+// browser. One implementation on purpose — see content/dict-overrides.ts.
+import { overrideValueForDict, setPath } from "./dict-overrides";
+import {
+  CONTROL,
+  VARIANT,
+  VISITOR_COOKIE,
+  resolveVariant,
+  type RunningExperiment,
+} from "../analytics/bucketing";
+
+/**
+ * Studio content reader (spec: Feature B — zero secrets).
+ *
+ * Reads the site's human OVERRIDES from Studio's PUBLIC content API — no Supabase
+ * credentials, no service key. The only config is `studioUrl` (a public,
+ * non-secret URL). The override map is fetched once per render (React `cache`
+ * dedupes within a request; Next ISR-caches it across requests and the revalidate
+ * webhook busts it). The code copy (dictionary/fallback) is always the base;
+ * only overrides are layered on top, so a slot tracking code can't go stale.
+ * Any failure returns the caller's fallback, so the site never breaks if Studio
+ * is down, unset, or a slot is missing.
+ */
+
+/**
+ * A form the team authored in Studio rather than in this repo's manifest (§4.3 —
+ * see docs/studio-authored-forms.md).
+ *
+ * `key` is the slot key and the CRM-facing contract; `slug` is the public URL
+ * segment, kept separate so the URL can be renamed without moving the CRM
+ * mapping; `listed` is the explicit "make it public" flag, which new forms start
+ * without so a half-built funnel is never indexable.
+ */
+export type StudioForm = { key: string; slug: string; listed: boolean };
+
+/**
+ * The minimal shape `applyDictOverrides` needs from the consuming app's own
+ * content manifest. The manifest itself stays in the app (its slots are the
+ * app's content model) — this client only ever reads `key`/`type`/`dictPath`
+ * off of it.
+ */
+export interface ManifestSlot {
+  key: string;
+  type: string;
+  dictPath?: string;
+}
+
+export interface ContentManifest {
+  slots: ManifestSlot[];
+}
+
+type ContentPayload = {
+  content?: Record<string, unknown>;
+  /** Absent on a Studio deploy predating §4.3 — read as "no authored forms". */
+  forms?: unknown;
+  /** Absent on a Studio deploy predating A/B — read as "no experiments running". */
+  experiments?: unknown;
+  /**
+   * Absent on a Studio deploy predating winner declarations — read as "no
+   * decided test is overriding anything", which is the safe answer: everyone
+   * gets control, exactly as before this existed.
+   */
+  decidedWinners?: unknown;
+};
+
+export interface ContentClient {
+  getSlot<T>(slotKey: string, fallback: T): Promise<T>;
+  getLocalizedSlot(slotKey: string, locale: string, fallback: string): Promise<string>;
+  applyDictOverrides<T>(dict: T, locale: string): Promise<T>;
+  activeVariant(): Promise<string>;
+  getRunningExperiments(): Promise<RunningExperiment[]>;
+  getDecidedWinners(): Promise<{ targetPath: string; winner: string }[]>;
+  getStudioForms(): Promise<StudioForm[]>;
+}
+
+/**
+ * Build a content client bound to one site.
+ *
+ * Call this ONCE, at module scope in the consuming app, and reuse the returned
+ * client everywhere — same reason `lib/content-manifest.ts`'s `getManifest` is a
+ * singleton: the `cache()` wrapping `getPayload` and `activeVariant` below dedupes
+ * per React render by closing over ONE function reference, so a client rebuilt on
+ * every call would defeat that dedupe and let one page's slots disagree about the
+ * arm.
+ */
+export function createContentClient({
+  studioUrl,
+  siteKey,
+  getManifest,
+}: {
+  /** Studio's public content origin, or null/undefined if unset — a public,
+   *  non-secret URL. */
+  studioUrl: string | null | undefined;
+  siteKey: string;
+  /** The app's own manifest — stays in the app; this client reads only
+   *  `slots[].{key,type,dictPath}` off of it. */
+  getManifest: () => Promise<ContentManifest>;
+}): ContentClient {
+  function studioBase(): string | null {
+    return studioUrl ? studioUrl.replace(/\/+$/, "") : null;
+  }
+
+  /**
+   * One fetch for the whole payload — overrides AND the published-forms list.
+   *
+   * Deliberately not two requests. The forms list is the second source of the
+   * submit route's allow-list, consulted on every form POST, so giving it its own
+   * round trip would put an extra network call in the money path. Riding here means
+   * it shares the same React `cache` (deduped per render), the same ISR window and
+   * the same revalidate tag, and costs nothing.
+   */
+  const getPayload = cache(async (): Promise<ContentPayload | null> => {
+    const base = studioBase();
+    if (!base) return null;
+    try {
+      const res = await fetch(`${base}/api/public/content/${siteKey}`, {
+        // ISR: keep slot-backed pages static; the revalidate webhook invalidates
+        // on edit, and this TTL is the freshness backstop if the webhook is missed.
+        next: { revalidate: 30, tags: ["wmm-content"] },
+      });
+      if (!res.ok) return null;
+      return (await res.json()) as ContentPayload;
+    } catch {
+      return null;
+    }
+  });
+
+  async function getContent(): Promise<Record<string, unknown> | null> {
+    return (await getPayload())?.content ?? null;
+  }
+
+  /**
+   * The forms Studio has published, as the submit allow-list's second source.
+   *
+   * Parsed defensively rather than trusted. This list widens which slots may write
+   * to the CRM, so a malformed or partial entry is DROPPED rather than guessed at —
+   * an entry missing its key or slug is not a form we can safely accept. A Studio
+   * that doesn't serve `forms` yields an empty list, which is exactly the
+   * pre-§4.3 behaviour, so the two repos can deploy in either order.
+   */
+  async function getStudioForms(): Promise<StudioForm[]> {
+    const raw = (await getPayload())?.forms;
+    if (!Array.isArray(raw)) return [];
+    const out: StudioForm[] = [];
+    for (const item of raw) {
+      if (!item || typeof item !== "object") continue;
+      const f = item as { key?: unknown; slug?: unknown; listed?: unknown };
+      if (typeof f.key !== "string" || f.key.length === 0) continue;
+      if (typeof f.slug !== "string" || f.slug.length === 0) continue;
+      // `listed` must be explicitly true. Anything else — absent, null, "false",
+      // 0 — means unlisted, so a malformed payload cannot accidentally publish a
+      // half-built funnel to search engines.
+      out.push({ key: f.key, slug: f.slug, listed: f.listed === true });
+    }
+    return out;
+  }
+
+  /**
+   * The experiments Studio has running, for server-side A/B assignment
+   * (wmm-studio docs/analytics/06-ab-testing.md §2.3).
+   *
+   * Rides the same payload as content and forms, so assignment adds no request and
+   * no database call to a public page — it reads a value the page already fetched
+   * and ISR-cached.
+   *
+   * Parsed defensively, and a malformed entry is DROPPED rather than repaired. The
+   * consequence of guessing is worse than the consequence of not running the test:
+   * a bad `split` would send everyone one way while the data still claimed to be an
+   * experiment, which is a wrong answer rather than no answer. `../analytics/bucketing`
+   * defends against the same thing again at assignment time.
+   */
+  async function getRunningExperiments(): Promise<RunningExperiment[]> {
+    const raw = (await getPayload())?.experiments;
+    if (!Array.isArray(raw)) return [];
+    const out: RunningExperiment[] = [];
+    for (const item of raw) {
+      if (!item || typeof item !== "object") continue;
+      const e = item as { key?: unknown; targetPath?: unknown; split?: unknown };
+      if (typeof e.key !== "string" || e.key.length === 0) continue;
+      if (typeof e.targetPath !== "string" || e.targetPath.length === 0) continue;
+      if (typeof e.split !== "number" || !Number.isFinite(e.split)) continue;
+      if (e.split < 1 || e.split > 99) continue;
+      out.push({ key: e.key, targetPath: e.targetPath, split: e.split });
+    }
+    return out;
+  }
+
+  /**
+   * Declared A/B winners whose cleanup has not been confirmed
+   * (wmm-studio migration 0019).
+   *
+   * A test that has been decided serves its WINNING arm to every visitor on that
+   * path, with no deploy and no bucketing. That is what makes "declare a winner"
+   * move 100% of traffic: a `<key>__b` value and a page that branches on
+   * `activeVariant() === 'b'` both follow, because both read the same arm.
+   *
+   * The override is temporary by design. Studio drops the row from this payload
+   * once someone confirms the cleanup — by then the winning content has been
+   * promoted onto the control keys and the code branch has shipped unconditionally,
+   * so there is nothing left to override and the page is testable again.
+   *
+   * Parsed as defensively as the running experiments above, and for a sharper
+   * reason: an unrecognised winner must not resolve to an arm. Serving `b` on a
+   * guess would put every visitor on content nobody chose.
+   */
+  async function getDecidedWinners(): Promise<
+    { targetPath: string; winner: string }[]
+  > {
+    const raw = (await getPayload())?.decidedWinners;
+    if (!Array.isArray(raw)) return [];
+    const out: { targetPath: string; winner: string }[] = [];
+    for (const item of raw) {
+      if (!item || typeof item !== "object") continue;
+      const e = item as { targetPath?: unknown; winner?: unknown };
+      if (typeof e.targetPath !== "string" || e.targetPath.length === 0) continue;
+      // Only the two arms that exist. Anything else is dropped, not coerced.
+      if (e.winner !== CONTROL && e.winner !== VARIANT) continue;
+      out.push({ targetPath: e.targetPath, winner: e.winner });
+    }
+    return out;
+  }
+
+  /**
+   * The A/B variant for the current request: `control` or `b`.
+   *
+   * Reads the path from the header middleware set and the visitor id from the
+   * `wmm_vid` cookie, then resolves against the running experiments in the content
+   * payload. `cache`d, so every slot lookup in one render agrees — a page that
+   * resolved half its copy as control and half as B would be unmeasurable.
+   *
+   * ## A STATICALLY RENDERED PAGE CANNOT VARY. Read this before running a test.
+   *
+   * `cookies()` and `headers()` throw during static generation — that is how Next
+   * decides a route must be server-rendered. This function CATCHES that and returns
+   * control, which is a deliberate trade with a sharp edge:
+   *
+   *  - **Kept:** every page that was statically generated still is. `getSlot` runs
+   *    on every page through the dictionary merge, so re-throwing would turn the
+   *    whole site dynamic and lose ISR — a large, permanent cost for a feature used
+   *    a few times a year.
+   *  - **Cost:** a statically generated page is rendered once, at build time, as
+   *    control. An experiment targeting it will assign visitors, record their
+   *    variant on every event, and show a comparison — while **both arms see
+   *    identical copy**. The numbers would look valid and mean nothing.
+   *
+   * So a page under test must opt into dynamic rendering:
+   *
+   * ```ts
+   * // app/[lang]/[country]/med-spa/page.tsx
+   * export const dynamic = "force-dynamic"; // required while an A/B test runs here
+   * ```
+   *
+   * `docs/funnel-analytics.md` carries the same warning next to the run-a-test
+   * steps. The better long-term fix is a middleware rewrite that gives each variant
+   * its own cache entry, which keeps static rendering AND varies — not built.
+   */
+  const activeVariant = cache(async (): Promise<string> => {
+    try {
+      const [headerList, cookieStore, experiments, decided] = await Promise.all([
+        headers(),
+        cookies(),
+        getRunningExperiments(),
+        getDecidedWinners(),
+      ]);
+      /*
+        The editor's preview override, set by the proxy from `?wmm-variant=b`.
+        Checked before the experiment lookup because it exists precisely for the
+        case where there is no experiment yet: Studio's workflow is make a
+        variant, look at it, THEN launch, and without this the editor renders
+        control while claiming to show B. Preview traffic is marked internal by
+        the collector, so this cannot feed the arm it is previewing.
+      */
+      if (headerList.get("x-wmm-variant") === VARIANT) return VARIANT;
+
+      const path = headerList.get("x-wmm-path");
+      if (!path) return CONTROL;
+
+      /*
+        A RUNNING test wins over a declared winner, and the order matters.
+
+        Studio refuses to start a test on a path whose previous test is decided but
+        not cleaned up, so in practice these never overlap. Resolving bucketing
+        first anyway means that if they ever did — a stale payload, a hand-edited
+        row — the live test keeps working rather than being silently overridden by
+        an old verdict, which is the failure that would be hardest to notice.
+      */
+      const bucketed = resolveVariant(
+        path,
+        cookieStore.get(VISITOR_COOKIE)?.value,
+        experiments,
+      );
+      if (bucketed.experimentKey) return bucketed.variant;
+
+      /*
+        No test running: a declared winner takes 100% of this path.
+
+        Exact path match, like `resolveVariant` — a prefix match would apply a
+        home-page verdict to every page under it.
+      */
+      const winner = decided.find((d) => d.targetPath === path);
+      return winner ? winner.winner : CONTROL;
+    } catch {
+      // Static render, or middleware did not run. Control is the only safe answer:
+      // serving a variant by accident would put untracked visitors into an arm.
+      //
+      // See the warning above — this is also the path that makes an experiment on a
+      // static page silently ineffective.
+      return CONTROL;
+    }
+  });
+
+  /**
+   * A slot's Studio override, or `fallback` (the code copy) when not overridden.
+   *
+   * **A/B: a `__b` suffix on any slot key is that slot's variant B.** When an
+   * experiment is running for this path and this visitor is bucketed into B, a
+   * published `hero.title__b` is used in place of `hero.title`. If no `__b` value
+   * exists the visitor simply sees control, so a half-authored experiment degrades
+   * to no experiment rather than to a broken page.
+   *
+   * This is what makes a test runnable with **no code change**: every
+   * Studio-editable slot on the site becomes testable by publishing one extra
+   * value. Same principle as instrumenting the form renderer once — the alternative
+   * is a code deploy per experiment, which is how A/B testing quietly stops
+   * happening.
+   */
+  async function getSlot<T>(slotKey: string, fallback: T): Promise<T> {
+    const content = await getContent();
+
+    if (content) {
+      const variant = await activeVariant();
+      if (variant === VARIANT) {
+        const override = content[`${slotKey}__${VARIANT}`];
+        if (override !== undefined && override !== null) return override as T;
+      }
+    }
+
+    const override = content?.[slotKey];
+    return (override ?? fallback) as T;
+  }
+
+  /**
+   * Convenience for localized `{ en, es }` text slots: returns the string for the
+   * given locale ("en-US" / "es-US"), falling back to EN, then to `fallback`
+   * (typically the current dictionary value).
+   */
+  async function getLocalizedSlot(
+    slotKey: string,
+    locale: string,
+    fallback: string,
+  ): Promise<string> {
+    const value = await getSlot<{ en?: string; es?: string } | null>(slotKey, null);
+    if (!value) return fallback;
+    const isEs = locale.toLowerCase().startsWith("es");
+    return (isEs ? value.es : value.en) || value.en || fallback;
+  }
+
+  /**
+   * Deep-merge the site's Studio overrides onto a dictionary for `locale`
+   * (dict-merge pattern — spec Phase 5 / Option A). For each manifest slot with a
+   * `dictPath`, if the team overrode it in Studio, the override is resolved for
+   * `locale` and written into a clone of the dict at that path. Slots tracking
+   * code are left untouched, so the dict (live code copy) stays the base. Called
+   * once in the [lang]/[country] layout, so every dict-backed component becomes
+   * editable with no component changes. Returns the original dict unchanged if
+   * Studio is unset/unreachable.
+   *
+   * Slot shapes handled:
+   *  - text/richtext → a `{ en, es }` object resolved to the locale string.
+   *  - list → a `{ items: [...] }` object; each item is flattened so any
+   *    `{ en, es }` field (e.g. a testimonial `quote`) becomes the locale string,
+   *    matching what the dict-driven component expects (e.g. `reviews[]`).
+   */
+  async function applyDictOverrides<T>(dict: T, locale: string): Promise<T> {
+    const overrides = await getContent();
+    if (!overrides) return dict;
+
+    const manifest = await getManifest();
+    const isEs = locale.toLowerCase().startsWith("es");
+    const clone = structuredClone(dict);
+    // Most of the site's copy arrives through this function rather than through
+    // getSlot, so the `__b` mechanism has to apply here too or an experiment could
+    // only ever test the handful of directly-read slots.
+    const variant = await activeVariant();
+
+    for (const slot of manifest.slots) {
+      if (!slot.dictPath) continue;
+
+      const raw =
+        variant === VARIANT && overrides[`${slot.key}__${VARIANT}`] !== undefined
+          ? overrides[`${slot.key}__${VARIANT}`]
+          : overrides[slot.key];
+
+      const value = overrideValueForDict(slot.type, raw, isEs);
+      if (value === undefined) continue;
+
+      setPath(clone as Record<string, unknown>, slot.dictPath, value);
+    }
+    return clone;
+  }
+
+  return {
+    getSlot,
+    getLocalizedSlot,
+    applyDictOverrides,
+    activeVariant,
+    getRunningExperiments,
+    getDecidedWinners,
+    getStudioForms,
+  };
+}