next-evolve 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velocinator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# next-evolve
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Self-improving Next.js sites: server-side variants with no flicker, measured in your own Postgres. Needs an Evolve Cloud account.
+
+> Alpha. The setup below is what `npx next-evolve init` will write (E11).
+
+## Database
+
+Raw events (exposures, goal events, identities) stay in **your** Postgres (≥ 14), in a separate `evolve` schema. Evolve Cloud only ever receives aggregate counts.
+
+```sh
+EVOLVE_DATABASE_URL=postgres://… npx next-evolve migrate
+```
+
+Use the pooled URL on serverless hosts (e.g. Neon's `-pooler` host).
+
+## Goals
+
+```ts
+// evolve.goals.ts
+import { defineGoals } from "next-evolve/config";
+
+export default defineGoals({
+  cta_click: { event: "cta_click", window: "1d" },
+  signup_page: { pageview: "/signup", window: "1d" },
+  paid: {
+    event: "subscription_started",
+    source: "stripe",
+    window: "30d",
+    value: (e) => e.props.amount as number,
+  },
+});
+```
+
+Function values run in your app when the event is written; only `{ kind: "local-fn" }` is sent to the cloud.
+
+## Routes and beacon
+
+```ts
+// app/api/evolve/[...evolve]/route.ts
+import { createEvolveHandler } from "next-evolve/server";
+import evolveConfig from "@/evolve.config";
+import goals from "@/evolve.goals";
+
+export const { GET, POST } = createEvolveHandler({ config: evolveConfig, goals });
+export const maxDuration = 60;
+```
+
+Put `<EvolveScript />` (from `next-evolve/client`) in the root layout. It sends page views, exposures and clicks on `[data-evolve-goal]` elements (forms: on submit) to `/api/evolve/collect` on your own origin.
+
+## Tracking
+
+```ts
+import { evolve } from "next-evolve/server";
+
+await evolve.track("project_created", { userId: user.id });
+await evolve.identify(user.id); // links the visitor's evolve_id cookie; first link wins
+```
+
+In the browser: `import { track, identify } from "next-evolve/client"`.
+
+### Server-to-server events
+
+`POST /api/evolve/track` with `Authorization: Bearer $EVOLVE_TRACK_SECRET` and `{ "events": [{ "name", "userId"?, "anonId"?, "value"?, "props"?, "source"?, "ts"?, "dedupeKey"? }] }` (≤ 500 events). Unset secret → 404; wrong bearer → 401.
+
+### Stripe recipe
+
+Call `evolve.track` from your own Stripe webhook handler, after you verify the signature:
+
+```ts
+// app/api/stripe/route.ts
+import { evolve } from "next-evolve/server";
+
+if (event.type === "invoice.paid") {
+  const invoice = event.data.object;
+  await evolve.track("subscription_started", {
+    userId: invoice.metadata.userId,
+    source: "stripe",
+    props: { amount: invoice.amount_paid / 100 },
+    dedupeKey: event.id, // Stripe retries: stored once
+  });
+}
+```

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { createSql } from "../db/client.js";
+import { migrate } from "../db/migrate.js";
+import { existsSync } from "node:fs";
+// src/cli/index.ts
+const HELP = `Usage: next-evolve <command>
+
+Commands:
+  migrate [--url <postgres-url>]   Create or update the evolve schema in your database
+                                   (default: $EVOLVE_DATABASE_URL, read from .env.local / .env)
+`;
+function loadEnvFiles() {
+	for (const f of [".env.local", ".env"]) if (existsSync(f)) process.loadEnvFile(f);
+}
+async function runMigrate(args) {
+	loadEnvFiles();
+	const i = args.indexOf("--url");
+	const url = i >= 0 ? args[i + 1] : process.env.EVOLVE_DATABASE_URL;
+	if (!url) {
+		console.error("next-evolve migrate: set EVOLVE_DATABASE_URL or pass --url");
+		return 1;
+	}
+	const sql = createSql(url, { max: 1 });
+	try {
+		const r = await migrate(sql);
+		console.warn(r.applied.length ? `Applied ${r.applied.join(", ")}` : `Up to date (${r.skipped.join(", ") || "nothing to apply"})`);
+		return 0;
+	} catch (e) {
+		console.error("next-evolve migrate failed:", e instanceof Error ? e.message : e);
+		return 1;
+	} finally {
+		await sql.end({ timeout: 5 });
+	}
+}
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === "migrate") process.exitCode = await runMigrate(rest);
+else {
+	process.stdout.write(HELP);
+	process.exitCode = cmd && cmd !== "help" && cmd !== "--help" ? 1 : 0;
+}

package/dist/client/beacon.d.ts

@@ -0,0 +1,11 @@
+type BeaconEvent = Record<string, unknown>;
+export declare const COLLECT_URL = "/api/evolve/collect";
+export declare function push(e: BeaconEvent): void;
+export declare function flush(): void;
+/** Records a browser event (e.g. `track("cta_click", { plan: "pro" })`). */
+export declare function track(name: string, props?: Record<string, unknown>): void;
+/** Links this visitor to your user id. Prefer `evolve.identify()` on the server. */
+export declare function identify(userId: string): void;
+/** Test helper. */
+export declare function _reset(): void;
+export {};

package/dist/client/beacon.js

@@ -0,0 +1,51 @@
+// src/client/beacon.ts
+const COLLECT_URL = "/api/evolve/collect";
+const MAX = 50;
+let queue = [];
+let timer;
+/** Off on the server and under automation (`navigator.webdriver`). */
+const off = () => typeof window === "undefined" || !!navigator.webdriver;
+function push(e) {
+	if (off()) return;
+	queue.push(e);
+	if (queue.length >= MAX) flush();
+	else timer ??= setTimeout(flush, 2e3);
+}
+function flush() {
+	clearTimeout(timer);
+	timer = void 0;
+	while (queue.length) {
+		const body = JSON.stringify({
+			v: 1,
+			events: queue.splice(0, MAX)
+		});
+		if (!navigator.sendBeacon?.("/api/evolve/collect", body)) fetch(COLLECT_URL, {
+			method: "POST",
+			body,
+			keepalive: true
+		}).catch(() => {});
+	}
+}
+/** Records a browser event (e.g. `track("cta_click", { plan: "pro" })`). */
+function track(name, props) {
+	push({
+		t: "ev",
+		n: name,
+		p: location.pathname,
+		...props ? { props } : {}
+	});
+}
+/** Links this visitor to your user id. Prefer `evolve.identify()` on the server. */
+function identify(userId) {
+	push({
+		t: "id",
+		u: String(userId)
+	});
+}
+/** Test helper. */
+function _reset() {
+	clearTimeout(timer);
+	timer = void 0;
+	queue = [];
+}
+export { COLLECT_URL, _reset, flush, identify, push, track };

package/dist/client/evolve-script.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Evolve beacon. Place once in the root layout. Not needed to show a variant.
+ * Queues a page view and one exposure per counted region on every route, and
+ * clicks/submits on `[data-evolve-goal]`; flushes every 2 s and on page hide.
+ */
+export declare function EvolveScript(): null;

package/dist/client/evolve-script.js

@@ -0,0 +1,60 @@
+"use client";
+import { flush, push } from "./beacon.js";
+import { useEffect } from "react";
+import { usePathname } from "next/navigation";
+// src/client/evolve-script.tsx
+/**
+* Evolve beacon. Place once in the root layout. Not needed to show a variant.
+* Queues a page view and one exposure per counted region on every route, and
+* clicks/submits on `[data-evolve-goal]`; flushes every 2 s and on page hide.
+*/
+function EvolveScript() {
+	const path = usePathname();
+	useEffect(() => {
+		document.documentElement.dataset.evolve = "ready";
+		const onGoal = (ev) => {
+			const el = ev.target?.closest?.("[data-evolve-goal]");
+			const n = el?.getAttribute("data-evolve-goal");
+			if (!n || ev.type === "submit" !== (el?.tagName === "FORM")) return;
+			push({
+				t: "ev",
+				n,
+				p: location.pathname
+			});
+		};
+		const onHide = () => document.visibilityState === "hidden" && flush();
+		document.addEventListener("click", onGoal, true);
+		document.addEventListener("submit", onGoal, true);
+		document.addEventListener("visibilitychange", onHide);
+		addEventListener("pagehide", flush);
+		return () => {
+			document.removeEventListener("click", onGoal, true);
+			document.removeEventListener("submit", onGoal, true);
+			document.removeEventListener("visibilitychange", onHide);
+			removeEventListener("pagehide", flush);
+		};
+	}, []);
+	useEffect(() => {
+		const p = location.pathname;
+		push({
+			t: "pv",
+			p
+		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const el of document.querySelectorAll("[data-evolve-e]:not([data-evolve-x])")) {
+			const e = el.getAttribute("data-evolve-e");
+			const v = el.getAttribute("data-evolve-v");
+			if (e && v && !seen.has(e)) {
+				seen.add(e);
+				push({
+					t: "exp",
+					e,
+					v,
+					p
+				});
+			}
+		}
+	}, [path]);
+	return null;
+}
+export { EvolveScript };

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+import { identify, track } from "./beacon.js";
+import { EvolveScript } from "./evolve-script.js";
+export { EvolveScript, identify, track };

package/dist/client/index.js

@@ -0,0 +1,3 @@
+import { identify, track } from "./beacon.js";
+import { EvolveScript } from "./evolve-script.js";
+export { EvolveScript, identify, track };

package/dist/cloud/manifest.d.ts

@@ -0,0 +1,12 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+import { Manifest } from "@next-evolve/protocol";
+/** The manifest this app sends to the cloud (spec §8.4). Configuration only. */
+export declare function buildManifest(config: EvolveConfig, goals: Goals | undefined, opts?: {
+  appUrl?: string | null;
+}): Manifest;
+/**
+ * The app's public base URL: EVOLVE_APP_URL, else Vercel's production URL.
+ * Null when unknown (the dashboard asks for it).
+ */
+export declare function detectAppUrl(env?: Record<string, string | undefined>): string | null;

package/dist/cloud/manifest.js

@@ -0,0 +1,42 @@
+import { resolveConfig } from "../config/config.js";
+import { serializeGoals } from "../config/goals.js";
+import { PROTOCOL_VERSION, SUPPORTED_PROTOCOLS, computeManifestHash } from "@next-evolve/protocol";
+import { createRequire } from "node:module";
+// src/cloud/manifest.ts
+const require = createRequire(import.meta.url);
+const versionOf = (load) => {
+	try {
+		return load().version;
+	} catch {
+		return null;
+	}
+};
+/** The manifest this app sends to the cloud (spec §8.4). Configuration only. */
+function buildManifest(config, goals, opts = {}) {
+	const routes = {};
+	for (const [path, r] of resolveConfig(config).routes) routes[path] = { mode: r.mode };
+	const serialized = goals ? serializeGoals(goals) : {};
+	return {
+		pv: PROTOCOL_VERSION,
+		sdkVersion: versionOf(() => require("next-evolve/package.json")) ?? "0.0.0",
+		protocol: { supported: [...SUPPORTED_PROTOCOLS] },
+		nextVersion: versionOf(() => require("next/package.json")),
+		routes,
+		goals: serialized,
+		hash: computeManifestHash({
+			routes,
+			goals: serialized
+		}),
+		appUrl: opts.appUrl ?? null
+	};
+}
+/**
+* The app's public base URL: EVOLVE_APP_URL, else Vercel's production URL.
+* Null when unknown (the dashboard asks for it).
+*/
+function detectAppUrl(env = process.env) {
+	if (env.EVOLVE_APP_URL) return env.EVOLVE_APP_URL.replace(/\/$/, "");
+	if (env.VERCEL_ENV === "production" && env.VERCEL_PROJECT_PRODUCTION_URL) return `https://${env.VERCEL_PROJECT_PRODUCTION_URL}`;
+	return null;
+}
+export { buildManifest, detectAppUrl };

package/dist/cloud/push.d.ts

@@ -0,0 +1,21 @@
+type Env = Record<string, string | undefined>;
+export type PushResult = {
+  ok: true;
+} | {
+  ok: false;
+  status: number | "network" | "no_key";
+};
+/**
+ * POSTs configuration (manifest, regions) to the cloud with the site's secret
+ * key. Never throws and never blocks a request: callers run it in `after()`
+ * or at startup. Without a secret key it's a no-op.
+ *
+ * Uses node:http, not `fetch`: Next patches `fetch` during prerender, and an
+ * uncached fetch there counts as dynamic usage (the push would fail at build,
+ * where static-mode regions are rendered).
+ */
+export declare function pushToCloud(path: "/v1/manifest" | "/v1/regions", body: unknown, opts?: {
+  env?: Env;
+  timeoutMs?: number;
+}): Promise<PushResult>;
+export {};

package/dist/cloud/push.js

@@ -0,0 +1,56 @@
+import "../store/runtime.js";
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+// src/cloud/push.ts
+/**
+* POSTs configuration (manifest, regions) to the cloud with the site's secret
+* key. Never throws and never blocks a request: callers run it in `after()`
+* or at startup. Without a secret key it's a no-op.
+*
+* Uses node:http, not `fetch`: Next patches `fetch` during prerender, and an
+* uncached fetch there counts as dynamic usage (the push would fail at build,
+* where static-mode regions are rendered).
+*/
+function pushToCloud(path, body, opts = {}) {
+	const env = opts.env ?? process.env;
+	const key = env.EVOLVE_SECRET_KEY;
+	const cloud = env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+	if (!key || !cloud) return Promise.resolve({
+		ok: false,
+		status: "no_key"
+	});
+	return new Promise((resolve) => {
+		try {
+			const url = new URL(path, cloud);
+			const data = Buffer.from(JSON.stringify(body));
+			const req = (url.protocol === "https:" ? request$1 : request)(url, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${key}`,
+					"content-type": "application/json",
+					"content-length": data.length
+				},
+				timeout: opts.timeoutMs ?? 3e3
+			}, (res) => {
+				res.resume();
+				const status = res.statusCode ?? 0;
+				resolve(status >= 200 && status < 300 ? { ok: true } : {
+					ok: false,
+					status
+				});
+			});
+			req.on("timeout", () => req.destroy(/* @__PURE__ */ new Error("timeout")));
+			req.on("error", () => resolve({
+				ok: false,
+				status: "network"
+			}));
+			req.end(data);
+		} catch {
+			resolve({
+				ok: false,
+				status: "network"
+			});
+		}
+	});
+}
+export { pushToCloud };

package/dist/cloud/regions.d.ts

@@ -0,0 +1,8 @@
+import { RegionRegistration } from "@next-evolve/protocol";
+/**
+ * Registers a region with the cloud (spec §5.2), once per process per
+ * (id, schema, path). Errors are swallowed; a failed push is retried on a later render.
+ */
+export declare function registerRegion(r: Omit<RegionRegistration, "pv">): Promise<void>;
+/** Test helper. */
+export declare function resetRegionRegistry(): void;

package/dist/cloud/regions.js

@@ -0,0 +1,25 @@
+import { pushToCloud } from "./push.js";
+import { PROTOCOL_VERSION } from "@next-evolve/protocol";
+// src/cloud/regions.ts
+const sent = /* @__PURE__ */ new Set();
+const MAX_SENT = 1e3;
+/**
+* Registers a region with the cloud (spec §5.2), once per process per
+* (id, schema, path). Errors are swallowed; a failed push is retried on a later render.
+*/
+async function registerRegion(r) {
+	const key = `${r.id}|${r.schemaHash}|${r.path}`;
+	if (sent.has(key)) return;
+	sent.add(key);
+	if (sent.size > MAX_SENT) sent.delete(sent.values().next().value);
+	const res = await pushToCloud("/v1/regions", {
+		pv: PROTOCOL_VERSION,
+		...r
+	});
+	if (!res.ok && res.status !== "no_key") sent.delete(key);
+}
+/** Test helper. */
+function resetRegionRegistry() {
+	sent.clear();
+}
+export { registerRegion, resetRegionRegistry };

package/dist/config/config.d.ts

@@ -0,0 +1,51 @@
+export type RouteConfig = {
+  /** static (default): ISR per variant under `app/[evolve]/`. dynamic: page reads `x-evolve-a`. */
+  mode: "static" | "dynamic";
+};
+export type EvolveConfig = {
+  /** Routes Evolve may test, keyed by exact pathname (e.g. "/", "/pricing"). */
+  routes: Record<string, RouteConfig>;
+  store?: "auto" | "memory" | "global-config";
+  sync?: {
+    pollSeconds?: number;
+  };
+  database?: {
+    urlEnv?: string;
+  };
+  aggregate?: {
+    maxMs?: number;
+    statementTimeoutMs?: number;
+  };
+  cookies?: {
+    maxAgeDays?: number;
+    domain?: string;
+  };
+  /** Return false to serve control and set no cookies (e.g. before consent). */
+  consent?: (req: Request) => boolean;
+  bots?: {
+    extraPatterns?: string[];
+  };
+  debug?: boolean;
+};
+export type ResolvedConfig = {
+  routes: ReadonlyMap<string, RouteConfig>;
+  store: "auto" | "memory" | "global-config";
+  pollSeconds: number;
+  databaseUrlEnv: string;
+  aggregate: {
+    maxMs: number;
+    statementTimeoutMs: number;
+  };
+  cookies: {
+    maxAgeDays: number;
+    domain: string | undefined;
+  };
+  consent: ((req: Request) => boolean) | undefined;
+  botPatterns: readonly string[];
+  debug: boolean;
+};
+/** Normalizes a pathname: no trailing slash (except "/"), no empty segments. */
+export declare function normalizePath(p: string): string;
+/** Identity helper for `evolve.config.ts` with types and validation. */
+export declare function defineConfig<const C extends EvolveConfig>(config: C): C;
+export declare function resolveConfig(config: EvolveConfig): ResolvedConfig;

package/dist/config/config.js

@@ -0,0 +1,47 @@
+// src/config/config.ts
+/** Normalizes a pathname: no trailing slash (except "/"), no empty segments. */
+function normalizePath(p) {
+	if (p === "/" || p === "") return "/";
+	const s = p.replace(/\/{2,}/g, "/");
+	return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+/** Identity helper for `evolve.config.ts` with types and validation. */
+function defineConfig(config) {
+	resolveConfig(config);
+	return config;
+}
+const resolved = /* @__PURE__ */ new WeakMap();
+function resolveConfig(config) {
+	const hit = resolved.get(config);
+	if (hit) return hit;
+	const routes = /* @__PURE__ */ new Map();
+	for (const [raw, route] of Object.entries(config.routes)) {
+		if (!raw.startsWith("/")) throw new Error(`[evolve] route "${raw}" must start with "/"`);
+		const path = normalizePath(raw);
+		if (path.split("/")[1]?.startsWith("ev_")) throw new Error(`[evolve] route "${raw}" can't start with ev_`);
+		if (/[[\]*?#]/.test(path)) throw new Error(`[evolve] route "${raw}" must be a concrete path`);
+		if (route.mode !== "static" && route.mode !== "dynamic") throw new Error(`[evolve] route "${raw}": mode must be "static" or "dynamic"`);
+		routes.set(path, route);
+	}
+	const dev = process.env.NODE_ENV !== "production";
+	const r = {
+		routes,
+		store: config.store ?? "auto",
+		pollSeconds: config.sync?.pollSeconds ?? (dev ? 5 : 60),
+		databaseUrlEnv: config.database?.urlEnv ?? "EVOLVE_DATABASE_URL",
+		aggregate: {
+			maxMs: config.aggregate?.maxMs ?? 25e3,
+			statementTimeoutMs: config.aggregate?.statementTimeoutMs ?? 2e4
+		},
+		cookies: {
+			maxAgeDays: config.cookies?.maxAgeDays ?? 365,
+			domain: config.cookies?.domain
+		},
+		consent: config.consent,
+		botPatterns: config.bots?.extraPatterns ?? [],
+		debug: config.debug ?? dev
+	};
+	resolved.set(config, r);
+	return r;
+}
+export { defineConfig, normalizePath, resolveConfig };

package/dist/config/goals.d.ts

@@ -0,0 +1,50 @@
+import { SerializedGoal } from "@next-evolve/protocol";
+/** `<n>m`, `<n>h` or `<n>d`, at most 365 days. */
+export type GoalWindow = `${number}${"m" | "h" | "d"}`;
+type Common = {
+  /** Attribution window after first exposure. Default `7d`. */
+  window?: GoalWindow;
+  /** Count per visitor (default) or per identified user. */
+  unit?: "visitor" | "user";
+  /** Whether higher is better. Default `increase`. */
+  direction?: "increase" | "decrease";
+};
+/** An event as a goal's `value` function sees it (at write time, in your app). */
+export type GoalEvent = {
+  name: string;
+  props: Record<string, unknown>;
+  value: number | null;
+  source: string;
+  userId: string | null;
+  anonId: string | null;
+};
+export type EventGoal = Common & {
+  event: string;
+  /** Only events from this source (e.g. `stripe`). */
+  source?: string;
+  /** Only events whose props equal these values. */
+  where?: Record<string, string | number | boolean>;
+  /** A numeric prop path (`"amount"`, `"order.total"`) or a function run locally at write time. */
+  value?: string | ((e: GoalEvent) => number | null | undefined);
+};
+export type PageviewGoal = Common & {
+  /** Exact path, or a prefix ending in `*` (e.g. `/docs/*`). */
+  pageview: string;
+};
+export type GoalDefinition = EventGoal | PageviewGoal;
+export type Goals = Record<string, GoalDefinition>;
+/** Identity helper for `evolve.goals.ts`: types plus validation (throws on mistakes). */
+export declare function defineGoals<const G extends Goals>(goals: G): G;
+/**
+ * Goal definitions as sent to the cloud. Function values become
+ * `{ kind: "local-fn" }`; the function itself never leaves the app.
+ */
+export declare function serializeGoals(goals: Goals): Record<string, SerializedGoal>;
+/** True if a stored `$pageview` at `path` would count for some pageview goal. */
+export declare function matchesPageviewGoal(goals: Goals | undefined, path: string): boolean;
+/**
+ * Runs the `value` functions of matching event goals. Returns `{ goalKey: n }`
+ * or null. A function that throws or returns a non-finite number is skipped.
+ */
+export declare function computeGoalValues(goals: Goals | undefined, e: GoalEvent): Record<string, number> | null;
+export {};