@web-my-money/studio-consumer 1.0.0

package/README.md

@@ -0,0 +1,19 @@
+# @web-my-money/studio-consumer
+
+Consumer-side integration for WMM Studio: content, analytics, attribution.
+
+This is a source-only workspace package — no build step, no `dist`. Consumers
+are Next.js apps that already transpile workspace and scoped packages, so
+publishing compiled output here would only add a compile-and-publish cycle
+for no gain.
+
+## Entry points
+
+- `@web-my-money/studio-consumer/analytics`
+- `@web-my-money/studio-consumer/content`
+- `@web-my-money/studio-consumer/attribution`
+
+This package is currently a skeleton: each entry point exports only a
+`PACKAGE_VERSION` constant, used to prove at runtime that a consumer is
+resolving this package rather than a stale copy. Content, analytics, and
+attribution logic land in later tasks.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@web-my-money/studio-consumer",
+  "version": "1.0.0",
+  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
+    "directory": "packages/studio-consumer"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./analytics": "./src/analytics/index.ts",
+    "./content": "./src/content/index.ts",
+    "./attribution": "./src/attribution/index.ts",
+    "./headers": "./src/content/headers.mjs"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19"
+  },
+  "files": ["src"]
+}

package/src/analytics/bucketing.ts

@@ -0,0 +1,101 @@
+/**
+ * A/B assignment, as pure arithmetic (wmm-studio docs/analytics/06-ab-testing.md §2).
+ *
+ * Split out of `lib/experiments.ts` — which keeps its `server-only` marker and
+ * re-exports all of this — because the analytics collector runs in the browser
+ * and has to stamp the visitor's arm on every event. Without that stamp
+ * `funnel_events.variant` is empty and the comparison in Studio has nothing to
+ * compare, which is exactly the state this file was written to fix.
+ *
+ * ## The client may RESOLVE an arm. It must never RENDER one.
+ *
+ * Reading the arm to label an event is safe: the label describes a decision the
+ * server already made. Choosing copy from it is not — a client-side choice
+ * flashes the wrong variant, and the flash itself changes behaviour, which is
+ * the measurement artefact this whole design exists to avoid. Rendering stays
+ * behind `lib/content.ts`, which is server-only and stays that way.
+ *
+ * Four rules, each because the alternative quietly corrupts the result:
+ *
+ *  - **Sticky per visitor.** A visitor who sees both variants poisons both
+ *    numbers, so the bucket is a pure function of their id and the experiment
+ *    key — no randomness at request time, and nothing to store.
+ *  - **Same answer on both sides.** Server and client run this same function
+ *    over the same cookie and the same published experiment list, so the arm
+ *    that was rendered and the arm that gets recorded cannot disagree.
+ *  - **Default is control.** No experiment, unknown path, missing cookie, bad
+ *    config — all serve control. A variant is never served by accident.
+ *  - **One experiment per path**, enforced by a unique index in Studio's schema.
+ *    Overlapping experiments make both results meaningless.
+ */
+
+export type RunningExperiment = {
+  key: string;
+  targetPath: string;
+  /** Percent of visitors sent to variant B, 1-99. */
+  split: number;
+};
+
+export const CONTROL = "control";
+export const VARIANT = "b";
+/** The cookie the proxy sets and the collector reads. */
+export const VISITOR_COOKIE = "wmm_vid";
+
+/**
+ * FNV-1a, 32-bit. A hash, not a PRNG: the same input must bucket the same way on
+ * every request, on every server, forever — including after a deploy. Chosen for
+ * being short enough to read and verify by hand; the distribution only has to be
+ * even, not cryptographic, and nothing here is a secret.
+ */
+function hash(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    // `Math.imul` keeps this a 32-bit multiply; `h * 16777619` loses precision
+    // past 2^53 and stops being the same function across inputs.
+    h = Math.imul(h, 0x01000193);
+  }
+  // `>>> 0` because the XOR above makes h signed.
+  return h >>> 0;
+}
+
+/** A stable 0-99 bucket for a visitor within one experiment. */
+export function bucketFor(visitorId: string, experimentKey: string): number {
+  return hash(`${experimentKey}:${visitorId}`) % 100;
+}
+
+/**
+ * The variant to render for this visitor on this path.
+ *
+ * `experiments` comes from the published content payload, so this costs no
+ * database call. Returns `control` for anything unclear.
+ */
+export function resolveVariant(
+  path: string,
+  visitorId: string | null | undefined,
+  experiments: RunningExperiment[] | null | undefined,
+): { variant: string; experimentKey: string | null } {
+  if (!visitorId || !experiments?.length) {
+    return { variant: CONTROL, experimentKey: null };
+  }
+
+  const experiment = experiments.find((e) => e.targetPath === path);
+  if (!experiment) return { variant: CONTROL, experimentKey: null };
+
+  // Guard the config too: a split outside 1-99 is not an experiment, and
+  // trusting it would send everyone one way while still labelling the data as a
+  // test.
+  if (
+    !Number.isFinite(experiment.split) ||
+    experiment.split < 1 ||
+    experiment.split > 99
+  ) {
+    return { variant: CONTROL, experimentKey: null };
+  }
+
+  const bucket = bucketFor(visitorId, experiment.key);
+  return {
+    variant: bucket < experiment.split ? VARIANT : CONTROL,
+    experimentKey: experiment.key,
+  };
+}

package/src/analytics/collect-handler.ts

@@ -0,0 +1,126 @@
+import { NextResponse } from "next/server";
+
+/**
+ * First-party analytics collector (wmm-studio docs/analytics/01-pipeline.md §5.1).
+ *
+ * The browser posts same-origin here; this route stamps the site key and
+ * forwards the batch server-side to Studio's ingest endpoint with the bearer
+ * token. Two reasons it exists rather than the browser calling Studio directly:
+ * the token stays server-side, and a same-origin request is not what ad-blockers
+ * and third-party cookie policy are looking for.
+ *
+ * It ALWAYS returns 204, whatever happens. An analytics outage must never
+ * surface an error on a marketing page or interfere with a form — so failures
+ * are logged here and are invisible to the visitor.
+ *
+ * Inert with no `FUNNEL_INGEST_URL`: nothing is forwarded and the site behaves
+ * exactly as it did before this route existed. That is the correct state before
+ * rollout, which is what lets this merge ahead of being switched on.
+ */
+
+/** Mirrors the ingest endpoint's cap. Refused here so we don't forward a 413. */
+const MAX_BATCH = 50;
+
+const noContent = () => new NextResponse(null, { status: 204 });
+
+/**
+ * Where events are forwarded.
+ *
+ * Defaulted rather than required, so onboarding a new consumer site is ONE
+ * secret instead of two settings — and so a typo in a per-project env var cannot
+ * silently send a client's events nowhere. Override it only for a non-production
+ * Studio.
+ */
+const DEFAULT_INGEST_URL = "https://studio.webmymoney.com/api/ingest/funnel-events";
+
+/** The shape every per-site ingest key has. See wmm-studio `lib/analytics/ingest-auth.ts`. */
+const KEY_PREFIX = "wmmk_";
+
+/**
+ * Warn once, not per request.
+ *
+ * A key without the `wmmk_` prefix is the legacy GLOBAL token: Studio still
+ * accepts it, but it derives nothing from it, so events are filed under whatever
+ * `site_key` the payload claims — and the gate that deletes that path is next.
+ * The failure mode this catches is the whole point: everything stays green (204s,
+ * rows arriving, checklist passing) right up until the legacy path is removed and
+ * the site's analytics go dark. This is the collector's hot path, so the flag is
+ * module-level and the line is printed once per process, not once per batch.
+ */
+let warnedAboutKeyShape = false;
+
+function warnOnceAboutKeyShape(key: string): void {
+  if (warnedAboutKeyShape || key.startsWith(KEY_PREFIX)) return;
+  warnedAboutKeyShape = true;
+  console.warn(
+    `[analytics] FUNNEL_INGEST_TOKEN does not look like a per-site ingest key ` +
+      `(expected a "${KEY_PREFIX}" prefix). This is the legacy global token: Studio ` +
+      `will file these events under the site key in the payload rather than deriving ` +
+      `it from the key, and that path is being removed. Mint this site's own key at ` +
+      `Studio -> /sites/new.`,
+  );
+}
+
+/** Test-only: forget that the one-time warning has already been printed. */
+export function resetIngestKeyShapeWarning(): void {
+  warnedAboutKeyShape = false;
+}
+
+export function createCollectHandler(config: {
+  siteKey: string;
+  ingestUrl: string;
+  ingestKey: string;
+}): (request: Request) => Promise<Response> {
+  return async function POST(request: Request): Promise<Response> {
+    const url = config.ingestUrl || DEFAULT_INGEST_URL;
+    const token = config.ingestKey;
+    // The token is the only thing that genuinely has to be configured per site.
+    if (!token) return noContent();
+    warnOnceAboutKeyShape(token);
+
+    let events: unknown[];
+    try {
+      const body = (await request.json()) as { events?: unknown };
+      if (!Array.isArray(body.events)) return noContent();
+      events = body.events;
+    } catch {
+      return noContent();
+    }
+
+    if (events.length === 0) return noContent();
+    if (events.length > MAX_BATCH) {
+      console.warn(`[analytics] refusing oversized batch: ${events.length}`);
+      return noContent();
+    }
+
+    // The site key is stamped here, never trusted from the client: a browser must
+    // not be able to write events into another site's namespace by editing a
+    // payload. Anything the client sent under that key is overwritten.
+    const stamped = events.map((e) => ({
+      ...(e && typeof e === "object" ? e : {}),
+      siteKey: config.siteKey,
+    }));
+
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ events: stamped }),
+      });
+      if (!res.ok) {
+        // One line, no payload echo: a rejected batch is a code or config problem
+        // and the status is what identifies which.
+        console.warn(`[analytics] ingest rejected batch: ${res.status}`);
+      }
+    } catch (err) {
+      console.warn(
+        `[analytics] ingest unreachable: ${err instanceof Error ? err.message : "unknown"}`,
+      );
+    }
+
+    return noContent();
+  };
+}