next-evolve 0.0.0-stage → 0.1.0

package/dist/react/with-evolve.d.ts

@@ -0,0 +1,29 @@
+import { ComponentType, ReactElement } from "react";
+import { Metadata } from "next";
+/** Props Next passes to a page under `app/[evolve]/`. */
+export type EvolvePageProps = {
+  params: Promise<{
+    evolve: string;
+  } & Record<string, string | string[] | undefined>>;
+  searchParams?: Promise<Record<string, string | string[] | undefined>>;
+};
+/**
+ * Wraps a static-mode page under `app/[evolve]/<route>/page.tsx`. Decodes the
+ * variant code from `params.evolve` and makes it available to every
+ * `<Optimizable>` on the page before the body renders.
+ */
+export declare function withEvolve<P extends object>(Page: ComponentType<P>, opts: {
+  path: string;
+}): (props: P & EvolvePageProps) => Promise<ReactElement>;
+/** `generateStaticParams` for `app/[evolve]/`: prerenders control only, so builds need no network. */
+export declare function evolveStaticParams(): {
+  evolve: string;
+}[];
+type MetadataInput = Metadata | ((props: EvolvePageProps) => Metadata | Promise<Metadata>);
+/**
+ * `generateMetadata` for a static-mode page: canonical is the original path
+ * for every variant, and variant renders are `noindex` (bots only ever get
+ * control anyway).
+ */
+export declare function evolveMetadata(path: string, base?: MetadataInput): (props: EvolvePageProps) => Promise<Metadata>;
+export {};

package/dist/react/with-evolve.js

@@ -0,0 +1,57 @@
+import { normalizePath } from "../config/config.js";
+import { requestContext } from "./context.js";
+import { CODE_RE, CONTROL_CODE } from "@next-evolve/protocol";
+import { createElement } from "react";
+import { notFound } from "next/navigation";
+// src/react/with-evolve.ts
+/** Validates the `[evolve]` segment; malformed codes are a 404. */
+async function readCode(params) {
+	const { evolve } = await params;
+	if (typeof evolve !== "string" || !CODE_RE.test(evolve)) notFound();
+	return evolve;
+}
+/**
+* Wraps a static-mode page under `app/[evolve]/<route>/page.tsx`. Decodes the
+* variant code from `params.evolve` and makes it available to every
+* `<Optimizable>` on the page before the body renders.
+*/
+function withEvolve(Page, opts) {
+	const path = normalizePath(opts.path);
+	async function EvolvePage(props) {
+		const code = await readCode(props.params);
+		const ctx = requestContext();
+		ctx.code = code;
+		ctx.path = path;
+		return createElement(Page, props);
+	}
+	Object.defineProperty(EvolvePage, "name", { value: `withEvolve(${Page.displayName ?? Page.name ?? "Page"})` });
+	return EvolvePage;
+}
+/** `generateStaticParams` for `app/[evolve]/`: prerenders control only, so builds need no network. */
+function evolveStaticParams() {
+	return [{ evolve: CONTROL_CODE }];
+}
+/**
+* `generateMetadata` for a static-mode page: canonical is the original path
+* for every variant, and variant renders are `noindex` (bots only ever get
+* control anyway).
+*/
+function evolveMetadata(path, base = {}) {
+	const canonical = normalizePath(path);
+	return async function generateMetadata(props) {
+		const code = await readCode(props.params);
+		const m = typeof base === "function" ? await base(props) : base;
+		return {
+			...m,
+			alternates: {
+				...m.alternates,
+				canonical
+			},
+			...code === CONTROL_CODE ? {} : { robots: {
+				index: false,
+				follow: true
+			} }
+		};
+	};
+}
+export { evolveMetadata, evolveStaticParams, withEvolve };

package/dist/server/collect.d.ts

@@ -0,0 +1,46 @@
+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;
+  isBot: (ua: string | null) => boolean;
+  writer: Writer;
+  now?: () => Date;
+};
+/** 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,131 @@
+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)
+});
+/** 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();
+	const bundle = deps.bundle();
+	const exposures = [];
+	const rows = [];
+	let testedPageviews = 0;
+	for (const e of events) switch (e.t) {
+		case "exp": {
+			const v = bundle?.variants[e.v];
+			const exp = bundle?.routing.experiments[e.e];
+			if (v && exp && v.exp === e.e && exp.variants.some((x) => x.id === e.v)) exposures.push({
+				experiment_id: e.e,
+				anon_id: anon,
+				variant_id: e.v,
+				path: normalizePath(e.p)
+			});
+			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, 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,16 @@
+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), `GET health`.
+ * Sync and aggregate arrive with M3/M4.
+ */
+export declare function createEvolveHandler(opts: EvolveHandlerOptions): {
+  GET: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+};

package/dist/server/handler.js

@@ -0,0 +1,72 @@
+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 { getBundleStore } from "../store/runtime.js";
+import { handleCollect } from "./collect.js";
+import { runtimeWriter, scheduleFlush, setRuntime } from "./runtime.js";
+import { handleTrack } from "./track-route.js";
+import { SUPPORTED_PROTOCOLS } from "@next-evolve/protocol";
+// src/server/handler.ts
+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), `GET health`.
+* Sync and aggregate arrive with M3/M4.
+*/
+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,
+						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()
+				});
+				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/track-route.d.ts

@@ -0,0 +1,25 @@
+import { Goals } from "../config/goals.js";
+import { Writer } from "../db/writer.js";
+import { z } from "zod";
+export declare const MAX_TRACK_EVENTS = 500;
+export declare const trackBodySchema: z.ZodObject<{
+  events: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    anonId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    props: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    source: z.ZodOptional<z.ZodString>;
+    ts: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    dedupeKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * `POST /api/evolve/track`: server-to-server events (Segment, a CRM, a
+ * webhook relay) with `Authorization: Bearer $EVOLVE_TRACK_SECRET`.
+ */
+export declare function handleTrack(req: Request, deps: {
+  secret: string | undefined;
+  goals: Goals | undefined;
+  writer: Writer;
+}): Promise<Response>;

package/dist/server/track-route.js

@@ -0,0 +1,49 @@
+import { eventRow } from "./events.js";
+import { z } from "zod";
+import { timingSafeEqual } from "node:crypto";
+// src/server/track-route.ts
+const MAX_TRACK_EVENTS = 500;
+const trackEvent = z.object({
+	name: z.string().min(1).max(100),
+	userId: z.string().max(256).nullish(),
+	anonId: z.string().max(64).nullish(),
+	value: z.number().finite().nullish(),
+	props: z.record(z.string(), z.unknown()).nullish(),
+	source: z.string().max(64).optional(),
+	ts: z.union([z.string(), z.number()]).optional(),
+	dedupeKey: z.string().max(200).nullish()
+});
+const trackBodySchema = z.object({ events: z.array(trackEvent).min(1).max(500) });
+function bearerOk(req, secret) {
+	const h = req.headers.get("authorization") ?? "";
+	const got = Buffer.from(h.startsWith("Bearer ") ? h.slice(7) : "");
+	const want = Buffer.from(secret);
+	return got.length === want.length && timingSafeEqual(got, want);
+}
+/**
+* `POST /api/evolve/track`: server-to-server events (Segment, a CRM, a
+* webhook relay) with `Authorization: Bearer $EVOLVE_TRACK_SECRET`.
+*/
+async function handleTrack(req, deps) {
+	if (!deps.secret) return Response.json({ error: "track_disabled" }, { status: 404 });
+	if (!bearerOk(req, deps.secret)) return Response.json({ error: "unauthorized" }, { status: 401 });
+	let body;
+	try {
+		const r = trackBodySchema.safeParse(await req.json());
+		if (!r.success) return Response.json({
+			error: "invalid_body",
+			issues: r.error.issues.slice(0, 5)
+		}, { status: 400 });
+		body = r.data;
+	} catch {
+		return Response.json({ error: "invalid_json" }, { status: 400 });
+	}
+	const rows = body.events.flatMap((e) => {
+		const row = eventRow(e.name, e, deps.goals, "webhook");
+		return row ? [row] : [];
+	});
+	deps.writer.events(rows);
+	await deps.writer.flush();
+	return Response.json({ accepted: rows.length });
+}
+export { MAX_TRACK_EVENTS, handleTrack, trackBodySchema };