next-evolve 0.0.0-stage → 0.3.1

package/dist/server/collect.d.ts

@@ -0,0 +1,62 @@
+import { ResolvedConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+import { Writer } from "../db/writer.js";
+import { BundlePayload } from "@next-evolve/protocol";
+import { z } from "zod";
+export declare const MAX_BATCH_BYTES: number;
+export declare const MAX_BATCH_EVENTS = 50;
+declare const beaconEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  t: z.ZodLiteral<"pv">;
+  p: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  t: z.ZodLiteral<"exp">;
+  e: z.ZodString;
+  v: z.ZodString;
+  p: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  t: z.ZodLiteral<"ev">;
+  n: z.ZodString;
+  p: z.ZodOptional<z.ZodString>;
+  props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+  t: z.ZodLiteral<"id">;
+  u: z.ZodString;
+}, z.core.$strip>], "t">;
+/** Beacon payload (spec §8.1). Unknown event types are skipped, not fatal. */
+export declare const collectSchema: z.ZodObject<{
+  v: z.ZodLiteral<1>;
+  events: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export type BeaconEvent = z.infer<typeof beaconEvent>;
+export type CollectDeps = {
+  config: ResolvedConfig;
+  goals: Goals | undefined;
+  bundle: () => BundlePayload | null;
+  /**
+   * Fetches the bundle now (see {@link createBundleRefresher}). Called when a
+   * beacon names an experiment/variant the current bundle doesn't know, so a
+   * cold or stale instance doesn't drop an exposure the proxy just assigned.
+   */
+  refreshBundle?: () => Promise<void>;
+  isBot: (ua: string | null) => boolean;
+  writer: Writer;
+  now?: () => Date;
+};
+/**
+ * Wraps a store refresh for collect: at most one fetch per `minIntervalMs` per
+ * instance (forged beacons with made-up ids can't turn into a cloud fetch each),
+ * and never waits longer than `capMs`.
+ */
+export declare function createBundleRefresher(refresh: () => Promise<void>, opts?: {
+  minIntervalMs?: number;
+  capMs?: number;
+  now?: () => number;
+}): () => Promise<void>;
+/** Same-origin check: `Origin` must match the host; without it, `Sec-Fetch-Site` must say so. */
+export declare function isSameOrigin(req: Request): boolean;
+/**
+ * `POST /api/evolve/collect`. Validates synchronously and queues rows; the
+ * caller flushes after the response. Returns the status code to send.
+ */
+export declare function handleCollect(req: Request, deps: CollectDeps): Promise<number>;
+export {};

package/dist/server/collect.js

@@ -0,0 +1,157 @@
+import { normalizePath } from "../config/config.js";
+import { matchesPageviewGoal } from "../config/goals.js";
+import { ANON_COOKIE } from "../core/cookies.js";
+import { eventRow, utcDay } from "./events.js";
+import { ANON_ID_RE, ID_RE } from "@next-evolve/protocol";
+import { z } from "zod";
+// src/server/collect.ts
+const MAX_BATCH_BYTES = 32768;
+const MAX_BATCH_EVENTS = 50;
+const path = z.string().min(1).max(512).startsWith("/");
+const beaconEvent = z.discriminatedUnion("t", [
+	z.object({
+		t: z.literal("pv"),
+		p: path
+	}),
+	z.object({
+		t: z.literal("exp"),
+		e: z.string().regex(ID_RE),
+		v: z.string().regex(ID_RE),
+		p: path
+	}),
+	z.object({
+		t: z.literal("ev"),
+		n: z.string().min(1).max(100),
+		p: path.optional(),
+		props: z.record(z.string(), z.unknown()).optional()
+	}),
+	z.object({
+		t: z.literal("id"),
+		u: z.string().min(1).max(256)
+	})
+]);
+/** Beacon payload (spec §8.1). Unknown event types are skipped, not fatal. */
+const collectSchema = z.object({
+	v: z.literal(1),
+	events: z.array(z.unknown()).max(50)
+});
+/**
+* Wraps a store refresh for collect: at most one fetch per `minIntervalMs` per
+* instance (forged beacons with made-up ids can't turn into a cloud fetch each),
+* and never waits longer than `capMs`.
+*/
+function createBundleRefresher(refresh, opts = {}) {
+	const minIntervalMs = opts.minIntervalMs ?? 5e3;
+	const capMs = opts.capMs ?? 2e3;
+	const now = opts.now ?? Date.now;
+	let last = -Infinity;
+	return async () => {
+		if (now() - last < minIntervalMs) return;
+		last = now();
+		let timer;
+		await Promise.race([refresh().catch(() => {}), new Promise((r) => {
+			timer = setTimeout(r, capMs);
+		})]);
+		clearTimeout(timer);
+	};
+}
+/** Same-origin check: `Origin` must match the host; without it, `Sec-Fetch-Site` must say so. */
+function isSameOrigin(req) {
+	const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host");
+	const origin = req.headers.get("origin");
+	if (origin) try {
+		return new URL(origin).host === (host ?? new URL(req.url).host);
+	} catch {
+		return false;
+	}
+	return req.headers.get("sec-fetch-site") === "same-origin";
+}
+function cookie(req, name) {
+	const raw = req.headers.get("cookie");
+	if (!raw) return void 0;
+	for (const part of raw.split(";")) {
+		const i = part.indexOf("=");
+		if (i > 0 && part.slice(0, i).trim() === name) return decodeURIComponent(part.slice(i + 1).trim());
+	}
+}
+/**
+* `POST /api/evolve/collect`. Validates synchronously and queues rows; the
+* caller flushes after the response. Returns the status code to send.
+*/
+async function handleCollect(req, deps) {
+	if (Number(req.headers.get("content-length") ?? 0) > 32768) return 413;
+	if (!isSameOrigin(req)) return 403;
+	const text = await req.text();
+	if (text.length > 32768) return 413;
+	let parsed;
+	try {
+		const r = collectSchema.safeParse(JSON.parse(text));
+		if (!r.success) return 400;
+		parsed = r.data;
+	} catch {
+		return 400;
+	}
+	const anon = cookie(req, ANON_COOKIE);
+	if (deps.isBot(req.headers.get("user-agent"))) return 204;
+	if (cookie(req, "evolve_pv")) return 204;
+	if (!anon || !ANON_ID_RE.test(anon)) return 204;
+	if (deps.config.consent?.(req) === false) return 204;
+	const events = parsed.events.flatMap((e) => {
+		const r = beaconEvent.safeParse(e);
+		return r.success ? [r.data] : [];
+	});
+	const now = deps.now?.() ?? /* @__PURE__ */ new Date();
+	let bundle = deps.bundle();
+	const known = (e, v) => {
+		const exp = bundle?.routing.experiments[e];
+		return bundle?.variants[v]?.exp === e && Boolean(exp?.variants.some((x) => x.id === v));
+	};
+	if (deps.refreshBundle && events.some((e) => e.t === "exp" && !known(e.e, e.v))) {
+		await deps.refreshBundle();
+		bundle = deps.bundle();
+	}
+	const exposures = [];
+	const rows = [];
+	let testedPageviews = 0;
+	for (const e of events) switch (e.t) {
+		case "exp":
+			if (known(e.e, e.v)) exposures.push({
+				experiment_id: e.e,
+				anon_id: anon,
+				variant_id: e.v,
+				path: normalizePath(e.p),
+				first_at: now
+			});
+			break;
+		case "pv": {
+			const p = normalizePath(e.p);
+			if ((bundle?.routing.routes[p] ?? []).some((id) => bundle?.routing.experiments[id]?.status === "running") && deps.config.routes.has(p)) testedPageviews++;
+			if (matchesPageviewGoal(deps.goals, p)) {
+				const row = eventRow("$pageview", {
+					anonId: anon,
+					path: p
+				}, void 0, "browser", now);
+				if (row) rows.push(row);
+			}
+			break;
+		}
+		case "ev": {
+			const row = eventRow(e.n, {
+				anonId: anon,
+				props: e.props ?? null,
+				path: e.p ? normalizePath(e.p) : null
+			}, deps.goals, "browser", now);
+			if (row) rows.push(row);
+			break;
+		}
+		case "id": deps.writer.identities([{
+			anon_id: anon,
+			user_id: e.u
+		}]);
+	}
+	deps.writer.exposures(exposures);
+	deps.writer.events(rows);
+	deps.writer.usage(utcDay(now), testedPageviews);
+	return 204;
+}
+export { MAX_BATCH_BYTES, MAX_BATCH_EVENTS, collectSchema, createBundleRefresher, handleCollect, isSameOrigin };

package/dist/server/events.d.ts

@@ -0,0 +1,18 @@
+import { Goals } from "../config/goals.js";
+import { EventRow } from "../db/writer.js";
+/** Props larger than this (as JSON) are dropped from the event. */
+export declare const MAX_PROPS_BYTES = 2048;
+export type TrackInput = {
+  userId?: string | null;
+  anonId?: string | null;
+  value?: number | null;
+  props?: Record<string, unknown> | null;
+  source?: string;
+  ts?: Date | string | number;
+  dedupeKey?: string | null;
+  path?: string | null;
+};
+/** Normalizes one event and runs goal `value` functions (locally, at write time). */
+export declare function eventRow(name: string, input: TrackInput, goals: Goals | undefined, defaultSource: string, now?: Date): EventRow | null;
+/** `YYYY-MM-DD` in UTC. */
+export declare const utcDay: (d?: Date) => string;

package/dist/server/events.js

@@ -0,0 +1,50 @@
+import { computeGoalValues } from "../config/goals.js";
+// src/server/events.ts
+/** Props larger than this (as JSON) are dropped from the event. */
+const MAX_PROPS_BYTES = 2048;
+const clean = (s, max) => typeof s === "string" && s.length > 0 ? s.slice(0, max) : null;
+function capProps(p) {
+	if (!p || typeof p !== "object" || Array.isArray(p)) return null;
+	try {
+		return JSON.stringify(p).length <= 2048 ? p : null;
+	} catch {
+		return null;
+	}
+}
+function toDate(ts, now) {
+	if (ts === void 0) return now;
+	const d = ts instanceof Date ? ts : new Date(ts);
+	return Number.isNaN(d.getTime()) ? now : d;
+}
+/** Normalizes one event and runs goal `value` functions (locally, at write time). */
+function eventRow(name, input, goals, defaultSource, now = /* @__PURE__ */ new Date()) {
+	const n = clean(name, 100);
+	if (!n) return null;
+	const props = capProps(input.props);
+	const value = typeof input.value === "number" && Number.isFinite(input.value) ? input.value : null;
+	const source = clean(input.source, 64) ?? defaultSource;
+	const userId = clean(input.userId, 256);
+	const anonId = clean(input.anonId, 64);
+	return {
+		ts: toDate(input.ts, now),
+		name: n,
+		anon_id: anonId,
+		user_id: userId,
+		value,
+		goal_values: computeGoalValues(goals, {
+			name: n,
+			props: props ?? {},
+			value,
+			source,
+			userId,
+			anonId
+		}),
+		props,
+		source,
+		path: clean(input.path, 512),
+		dedupe_key: clean(input.dedupeKey, 200)
+	};
+}
+/** `YYYY-MM-DD` in UTC. */
+const utcDay = (d = /* @__PURE__ */ new Date()) => d.toISOString().slice(0, 10);
+export { MAX_PROPS_BYTES, eventRow, utcDay };

package/dist/server/evolve.d.ts

@@ -0,0 +1,20 @@
+import { TrackInput } from "./events.js";
+export type TrackOptions = Omit<TrackInput, "path">;
+/**
+ * Records a server-side event in the customer DB. Never throws. Without
+ * `anonId` it uses the visitor's `evolve_id` cookie when called in a request.
+ */
+declare function track(name: string, opts?: TrackOptions): Promise<void>;
+/**
+ * Links a visitor (the `evolve_id` cookie, or `anonId`) to your user id, so
+ * events on other devices or from your server count for their experiments.
+ * The first link for a visitor wins. Never throws.
+ */
+declare function identify(userId: string, opts?: {
+  anonId?: string;
+}): Promise<void>;
+export declare const evolve: {
+  track: typeof track;
+  identify: typeof identify;
+};
+export {};

package/dist/server/evolve.js

@@ -0,0 +1,57 @@
+import "../core/cookies.js";
+import { logRateLimited } from "../core/log.js";
+import { eventRow } from "./events.js";
+import { getRuntime, runtimeWriter, scheduleFlush } from "./runtime.js";
+// src/server/evolve.ts
+async function cookieAnonId() {
+	try {
+		const { cookies } = await import("next/headers");
+		return (await cookies()).get("evolve_id")?.value ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Records a server-side event in the customer DB. Never throws. Without
+* `anonId` it uses the visitor's `evolve_id` cookie when called in a request.
+*/
+async function track(name, opts = {}) {
+	try {
+		const rt = getRuntime();
+		const anonId = opts.anonId !== void 0 ? opts.anonId : await cookieAnonId();
+		const row = eventRow(name, {
+			...opts,
+			anonId
+		}, rt.goals, "server");
+		if (!row) return;
+		const w = runtimeWriter(rt);
+		w.events([row]);
+		await scheduleFlush(w);
+	} catch (e) {
+		logRateLimited("track", "evolve.track failed", e);
+	}
+}
+/**
+* Links a visitor (the `evolve_id` cookie, or `anonId`) to your user id, so
+* events on other devices or from your server count for their experiments.
+* The first link for a visitor wins. Never throws.
+*/
+async function identify(userId, opts = {}) {
+	try {
+		const anonId = opts.anonId ?? await cookieAnonId();
+		if (!anonId || !userId) return;
+		const w = runtimeWriter();
+		w.identities([{
+			anon_id: anonId.slice(0, 64),
+			user_id: String(userId).slice(0, 256)
+		}]);
+		await scheduleFlush(w);
+	} catch (e) {
+		logRateLimited("identify", "evolve.identify failed", e);
+	}
+}
+const evolve = {
+	track,
+	identify
+};
+export { evolve };

package/dist/server/handler.d.ts

@@ -0,0 +1,17 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+export type EvolveHandlerOptions = {
+  config: EvolveConfig;
+  goals?: Goals;
+  env?: Record<string, string | undefined>;
+};
+/**
+ * Route handlers for `app/api/evolve/[...evolve]/route.ts`:
+ * `POST collect` (beacon), `POST track` (bearer webhook), `POST aggregate`
+ * (signed cloud request), `POST sync` (signed cloud webhook → pull the
+ * bundle), `GET health`.
+ */
+export declare function createEvolveHandler(opts: EvolveHandlerOptions): {
+  GET: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+};

package/dist/server/handler.js

@@ -0,0 +1,105 @@
+import { sdkVersion } from "../cloud/manifest.js";
+import { resolveConfig } from "../config/config.js";
+import { serializeGoals } from "../config/goals.js";
+import { createBotDetector } from "../core/bots.js";
+import { logRateLimited } from "../core/log.js";
+import { getSql } from "../db/client.js";
+import { globalConfigSettings, writeGlobalConfig } from "../store/global-config.js";
+import { getBundleStore } from "../store/runtime.js";
+import { handleAggregate } from "./aggregate-route.js";
+import { createBundleRefresher, handleCollect } from "./collect.js";
+import { runtimeWriter, scheduleFlush, setRuntime } from "./runtime.js";
+import { handleSync, revalidateBundle } from "./sync-route.js";
+import { handleTrack } from "./track-route.js";
+import { SUPPORTED_PROTOCOLS, parseSecretKey } from "@next-evolve/protocol";
+// src/server/handler.ts
+const refreshers = /* @__PURE__ */ new WeakMap();
+/** One rate-limited refresher per store (collect, unknown exposures). */
+function collectRefresher(store) {
+	let r = refreshers.get(store);
+	if (!r) {
+		r = createBundleRefresher(() => store.refresh());
+		refreshers.set(store, r);
+	}
+	return r;
+}
+const notFound = () => Response.json({ error: "not_found" }, { status: 404 });
+/**
+* Route handlers for `app/api/evolve/[...evolve]/route.ts`:
+* `POST collect` (beacon), `POST track` (bearer webhook), `POST aggregate`
+* (signed cloud request), `POST sync` (signed cloud webhook → pull the
+* bundle), `GET health`.
+*/
+function createEvolveHandler(opts) {
+	const cfg = resolveConfig(opts.config);
+	if (opts.goals) serializeGoals(opts.goals);
+	setRuntime({
+		config: opts.config,
+		goals: opts.goals,
+		...opts.env ? { env: opts.env } : {}
+	});
+	const isBot = createBotDetector(cfg.botPatterns);
+	const env = () => opts.env ?? process.env;
+	const action = (req) => {
+		const parts = new URL(req.url).pathname.split("/").filter(Boolean);
+		return parts[parts.length - 1] ?? "";
+	};
+	async function post(req) {
+		try {
+			switch (action(req)) {
+				case "collect": {
+					const writer = runtimeWriter();
+					const store = getBundleStore(cfg, { env: env() });
+					const status = await handleCollect(req, {
+						config: cfg,
+						goals: opts.goals,
+						bundle: () => store?.peek() ?? null,
+						...store ? { refreshBundle: collectRefresher(store) } : {},
+						isBot,
+						writer
+					});
+					if (status === 204) await scheduleFlush(writer);
+					return new Response(null, { status });
+				}
+				case "track": return await handleTrack(req, {
+					secret: env().EVOLVE_TRACK_SECRET,
+					goals: opts.goals,
+					writer: runtimeWriter()
+				});
+				case "sync": return await handleSync(req, {
+					env: env(),
+					store: () => getBundleStore(cfg, { env: env() }),
+					onSynced: async (token) => {
+						const gc = globalConfigSettings(cfg.store, env());
+						const site = parseSecretKey(env().EVOLVE_SECRET_KEY ?? "")?.siteId;
+						if (gc && site) await writeGlobalConfig(gc, site, token);
+						await revalidateBundle();
+					}
+				});
+				case "aggregate": return await handleAggregate(req, {
+					config: cfg,
+					env: env(),
+					sql: () => getSql(cfg.databaseUrlEnv, env()),
+					sdkVersion: sdkVersion()
+				});
+				default: return notFound();
+			}
+		} catch (e) {
+			logRateLimited("handler", "evolve route failed", e);
+			return Response.json({ error: "internal" }, { status: 500 });
+		}
+	}
+	async function get(req) {
+		if (action(req) !== "health") return notFound();
+		return Response.json({
+			ok: true,
+			protocol: { supported: SUPPORTED_PROTOCOLS },
+			db: Boolean(env()[cfg.databaseUrlEnv])
+		});
+	}
+	return {
+		GET: get,
+		POST: post
+	};
+}
+export { createEvolveHandler };

package/dist/server/index.d.ts

@@ -0,0 +1,4 @@
+import { TrackOptions, evolve } from "./evolve.js";
+import { EvolveHandlerOptions, createEvolveHandler } from "./handler.js";
+import "server-only";
+export { type EvolveHandlerOptions, type TrackOptions, createEvolveHandler, evolve };

package/dist/server/index.js

@@ -0,0 +1,4 @@
+import { evolve } from "./evolve.js";
+import { createEvolveHandler } from "./handler.js";
+import "server-only";
+export { createEvolveHandler, evolve };

package/dist/server/runtime.d.ts

@@ -0,0 +1,26 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+import { Writer } from "../db/writer.js";
+type Env = Record<string, string | undefined>;
+export type EvolveRuntime = {
+  config?: EvolveConfig;
+  goals?: Goals;
+  /** Inject a writer (tests). */
+  writer?: Writer;
+  env?: Env;
+};
+/**
+ * Makes the app's config and goals known to `evolve.track()` and friends.
+ * Called by `createEvolveHandler()` and `registerEvolve()`.
+ */
+export declare function setRuntime(r: EvolveRuntime): void;
+export declare function getRuntime(): EvolveRuntime;
+/** Test helper. */
+export declare function resetRuntime(): void;
+export declare function runtimeWriter(r?: EvolveRuntime): Writer;
+/**
+ * Flushes after the response on serverless hosts (`after()`), or right away
+ * outside a request. Long-running Node flushes on its own timer.
+ */
+export declare function scheduleFlush(writer: Writer): Promise<void>;
+export {};

package/dist/server/runtime.js

@@ -0,0 +1,45 @@
+import { resolveConfig } from "../config/config.js";
+import { getSql } from "../db/client.js";
+import { getWriter } from "../db/writer.js";
+// src/server/runtime.ts
+const KEY = Symbol.for("next-evolve.runtime");
+const state = () => {
+	const g = globalThis;
+	g[KEY] ??= {};
+	return g[KEY];
+};
+/**
+* Makes the app's config and goals known to `evolve.track()` and friends.
+* Called by `createEvolveHandler()` and `registerEvolve()`.
+*/
+function setRuntime(r) {
+	Object.assign(state(), r);
+}
+function getRuntime() {
+	return state();
+}
+/** Test helper. */
+function resetRuntime() {
+	const s = state();
+	for (const k of Object.keys(s)) delete s[k];
+}
+function runtimeWriter(r = state()) {
+	if (r.writer) return r.writer;
+	const urlEnv = r.config ? resolveConfig(r.config).databaseUrlEnv : "EVOLVE_DATABASE_URL";
+	const env = r.env ?? process.env;
+	return getWriter(() => getSql(urlEnv, env), urlEnv);
+}
+/**
+* Flushes after the response on serverless hosts (`after()`), or right away
+* outside a request. Long-running Node flushes on its own timer.
+*/
+async function scheduleFlush(writer) {
+	if (writer.mode === "node") return;
+	try {
+		const { after } = await import("next/server");
+		after(() => writer.flush());
+	} catch {
+		await writer.flush();
+	}
+}
+export { getRuntime, resetRuntime, runtimeWriter, scheduleFlush, setRuntime };

package/dist/server/sync-route.d.ts

@@ -0,0 +1,28 @@
+import { BundleStore } from "../store/memory.js";
+import { ReplayGuard } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+/** Cache tag on the render-side bundle fetch (spec §7.7). */
+export declare const BUNDLE_TAG = "evolve-bundle";
+/** At most one refresh per window. */
+export declare const SYNC_MIN_INTERVAL_MS = 5000;
+export type SyncThrottle = {
+  last: number;
+  waiting: Promise<void> | null;
+};
+export declare const createSyncThrottle: () => SyncThrottle;
+export type SyncDeps = {
+  env: Env;
+  store: () => BundleStore | null;
+  /** Runs after the response (`after()` by default). */
+  defer?: (task: () => Promise<void>) => void;
+  /** Called with the new token once a refresh installed one (persist + revalidate). */
+  onSynced?: (token: string) => Promise<void>;
+  replay?: ReplayGuard;
+  throttle?: SyncThrottle;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+};
+export declare function handleSync(req: Request, deps: SyncDeps): Promise<Response>;
+/** Drops cached render-side bundle fetches (and pages that used them). */
+export declare function revalidateBundle(): Promise<void>;
+export {};