next-evolve 0.0.0-stage → 0.1.0

package/dist/store/fetch.d.ts

@@ -0,0 +1,22 @@
+export type FetchBundleResult = {
+  status: "ok";
+  token: string;
+  etag: string | null;
+} | {
+  status: "not_modified";
+} | {
+  status: "error";
+  code: number | "network";
+  message?: string;
+};
+/**
+ * `GET {cloud}/v1/bundle` with the secret key and `If-None-Match` (spec §7.5).
+ * Never throws. Verification is the caller's job.
+ */
+export declare function fetchBundle(opts: {
+  cloudUrl: string;
+  secretKey: string;
+  etag?: string | null;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}): Promise<FetchBundleResult>;

package/dist/store/fetch.js

@@ -0,0 +1,39 @@
+// src/store/fetch.ts
+/**
+* `GET {cloud}/v1/bundle` with the secret key and `If-None-Match` (spec §7.5).
+* Never throws. Verification is the caller's job.
+*/
+async function fetchBundle(opts) {
+	const f = opts.fetch ?? fetch;
+	try {
+		const res = await f(new URL("/v1/bundle", opts.cloudUrl), {
+			headers: {
+				authorization: `Bearer ${opts.secretKey}`,
+				...opts.etag ? { "if-none-match": opts.etag } : {}
+			},
+			cache: "no-store",
+			signal: AbortSignal.timeout(opts.timeoutMs ?? 5e3)
+		});
+		if (res.status === 304) return { status: "not_modified" };
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			return {
+				status: "error",
+				code: res.status,
+				message: body.slice(0, 200)
+			};
+		}
+		return {
+			status: "ok",
+			token: (await res.text()).trim(),
+			etag: res.headers.get("etag")
+		};
+	} catch (e) {
+		return {
+			status: "error",
+			code: "network",
+			message: String(e)
+		};
+	}
+}
+export { fetchBundle };

package/dist/store/memory.d.ts

@@ -0,0 +1,30 @@
+import { FetchBundleResult } from "./fetch.js";
+import { BundlePayload, KeyRing } from "@next-evolve/protocol";
+export type BundleStore = {
+  /**
+   * Synchronous read for the request path: the current verified, unexpired
+   * bundle or null. May start a background refresh, handed to `waitUntil`.
+   */
+  peek(waitUntil?: (p: Promise<unknown>) => void): BundlePayload | null;
+  /** Verifies and installs a token (build bundle, disk, sync route). Returns whether it was accepted. */
+  load(token: string): boolean;
+  /** Fetches now (one in flight). Resolves once done. */
+  refresh(): Promise<void>;
+  /** Raw token of the current bundle (for persistence). */
+  token(): string | null;
+};
+export type MemoryStoreOptions = {
+  site: string;
+  keys: KeyRing;
+  /** Fetches from the cloud. Omit for a static store (build bundle only). */
+  fetcher?: (etag: string | null) => Promise<FetchBundleResult>;
+  pollMs: number;
+  initialToken?: string | null;
+  now?: () => number;
+  random?: () => number;
+};
+/**
+ * In-memory bundle store with stale-while-revalidate polling (spec §7.5):
+ * never blocks a request, one fetch in flight, ±10% jitter.
+ */
+export declare function createMemoryStore(opts: MemoryStoreOptions): BundleStore;

package/dist/store/memory.js

@@ -0,0 +1,68 @@
+import { logRateLimited } from "../core/log.js";
+import { verifyBundle } from "@next-evolve/protocol";
+// src/store/memory.ts
+/**
+* In-memory bundle store with stale-while-revalidate polling (spec §7.5):
+* never blocks a request, one fetch in flight, ±10% jitter.
+*/
+function createMemoryStore(opts) {
+	const now = opts.now ?? Date.now;
+	const random = opts.random ?? Math.random;
+	let current = null;
+	let currentToken = null;
+	let etag = null;
+	let nextCheck = 0;
+	let inflight = null;
+	const schedule = () => {
+		nextCheck = now() + opts.pollMs * (.9 + .2 * random());
+	};
+	function load(token) {
+		const r = verifyBundle(token, {
+			keys: opts.keys,
+			site: opts.site,
+			current: current ? {
+				ver: current.ver,
+				exp: current.exp
+			} : null,
+			now: Math.floor(now() / 1e3)
+		});
+		if (!r.ok) {
+			if (r.reason !== "rollback") logRateLimited(`bundle:${r.reason}`, `bundle rejected: ${r.reason}`);
+			return false;
+		}
+		current = r.payload;
+		currentToken = token;
+		etag = `"${r.payload.ver}.${r.payload.iat}"`;
+		return true;
+	}
+	function refresh() {
+		if (!opts.fetcher) return Promise.resolve();
+		if (inflight) return inflight;
+		schedule();
+		inflight = opts.fetcher(etag).then((res) => {
+			if (res.status === "ok") load(res.token);
+			else if (res.status === "error") logRateLimited(`fetch:${res.code}`, `bundle fetch failed (${res.code})`, res.message);
+		}).catch((e) => logRateLimited("fetch:throw", "bundle fetch failed", e)).finally(() => {
+			inflight = null;
+		});
+		return inflight;
+	}
+	if (opts.initialToken) load(opts.initialToken);
+	return {
+		peek(waitUntil) {
+			if (current && now() >= current.exp * 1e3) {
+				current = null;
+				currentToken = null;
+			}
+			if (opts.fetcher && !inflight && now() >= nextCheck) {
+				const p = refresh();
+				waitUntil?.(p);
+			}
+			return current;
+		},
+		load,
+		refresh,
+		token: () => currentToken
+	};
+}
+export { createMemoryStore };

package/dist/store/runtime.d.ts

@@ -0,0 +1,30 @@
+import { BundleStore } from "./memory.js";
+import { KeyRing } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+export type RuntimeOptions = {
+  /** Signed bundle written at build time by `evolve pull` (cold-start fallback). */
+  buildBundle?: string | null;
+  /** Inject a store (tests). */
+  store?: BundleStore;
+  env?: Env;
+};
+/** Default cloud URL (decision D29). Override with EVOLVE_CLOUD_URL. */
+export declare const DEFAULT_CLOUD_URL: string | undefined;
+/**
+ * The process-wide bundle store for this site, shared by the proxy and the
+ * render path when they run in the same process. Null when the app has no
+ * valid secret key (then everything serves control).
+ */
+export declare function getBundleStore(config: {
+  pollSeconds?: number;
+}, opts?: RuntimeOptions): BundleStore | null;
+/** This app's site id (from EVOLVE_SECRET_KEY) and trusted public keys. Cached; null without a valid key. */
+export declare function getSiteIdentity(opts?: {
+  env?: Env;
+}): {
+  site: string;
+  keys: KeyRing;
+} | null;
+/** Test helper: forget all stores. */
+export declare function resetBundleStores(): void;
+export {};

package/dist/store/runtime.js

@@ -0,0 +1,69 @@
+import { trustedKeys } from "../core/keys.js";
+import { fetchBundle } from "./fetch.js";
+import { createMemoryStore } from "./memory.js";
+import { parseSecretKey } from "@next-evolve/protocol";
+// src/store/runtime.ts
+/** Default cloud URL (decision D29). Override with EVOLVE_CLOUD_URL. */
+const DEFAULT_CLOUD_URL = "https://api.evolveab.com";
+const REGISTRY = Symbol.for("next-evolve.stores");
+const registry = () => {
+	const g = globalThis;
+	g[REGISTRY] ??= /* @__PURE__ */ new Map();
+	return g[REGISTRY];
+};
+/**
+* The process-wide bundle store for this site, shared by the proxy and the
+* render path when they run in the same process. Null when the app has no
+* valid secret key (then everything serves control).
+*/
+function getBundleStore(config, opts = {}) {
+	if (opts.store) return opts.store;
+	const env = opts.env ?? process.env;
+	const secretKey = env.EVOLVE_SECRET_KEY;
+	const site = secretKey ? parseSecretKey(secretKey)?.siteId : void 0;
+	if (!secretKey || !site) return null;
+	const reg = registry();
+	const existing = reg.get(site);
+	if (existing) {
+		if (opts.buildBundle && !existing.token()) existing.load(opts.buildBundle);
+		return existing;
+	}
+	const cloudUrl = env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+	const store = createMemoryStore({
+		site,
+		keys: trustedKeys(env),
+		pollMs: (config.pollSeconds ?? (env.NODE_ENV === "production" ? 60 : 5)) * 1e3,
+		initialToken: opts.buildBundle ?? null,
+		fetcher: cloudUrl ? (etag) => fetchBundle({
+			cloudUrl,
+			secretKey,
+			etag
+		}) : void 0
+	});
+	reg.set(site, store);
+	return store;
+}
+const identities = /* @__PURE__ */ new Map();
+/** This app's site id (from EVOLVE_SECRET_KEY) and trusted public keys. Cached; null without a valid key. */
+function getSiteIdentity(opts = {}) {
+	const env = opts.env ?? process.env;
+	const cacheKey = [
+		env.EVOLVE_SECRET_KEY,
+		env.EVOLVE_UNSAFE_TEST_PUBLIC_KEY,
+		env.EVOLVE_UNSAFE_ALLOW_TEST_KEY,
+		env.NODE_ENV
+	].join("|");
+	if (identities.has(cacheKey)) return identities.get(cacheKey);
+	const site = env.EVOLVE_SECRET_KEY ? parseSecretKey(env.EVOLVE_SECRET_KEY)?.siteId : void 0;
+	const id = site ? {
+		site,
+		keys: trustedKeys(env)
+	} : null;
+	identities.set(cacheKey, id);
+	return id;
+}
+/** Test helper: forget all stores. */
+function resetBundleStores() {
+	registry().clear();
+}
+export { DEFAULT_CLOUD_URL, getBundleStore, getSiteIdentity, resetBundleStores };

package/migrations/0001_init.sql

@@ -0,0 +1,56 @@
+-- next-evolve customer schema (spec §8.3). Raw events stay in this database.
+-- Applied by `npx next-evolve migrate`; the migrator creates `evolve.migrations`.
+
+-- One row per unit per experiment (first exposure).
+create table evolve.exposures (
+  experiment_id text not null,
+  anon_id text not null,
+  variant_id text not null,
+  first_at timestamptz not null default now(),
+  path text not null,
+  segment text, -- null = main; Phase 3: UTM rule id
+  primary key (experiment_id, anon_id)
+);
+create index exposures_exp_first on evolve.exposures (experiment_id, first_at);
+
+create table evolve.events (
+  id bigint generated always as identity primary key,
+  ts timestamptz not null,
+  received_at timestamptz not null default now(),
+  name text not null,
+  anon_id text,
+  user_id text,
+  value double precision,
+  goal_values jsonb,
+  props jsonb,
+  source text not null,
+  path text,
+  dedupe_key text
+);
+create index events_name_ts on evolve.events (name, ts);
+create index events_anon_name on evolve.events (anon_id, name, ts) where anon_id is not null;
+create index events_user_name on evolve.events (user_id, name, ts) where user_id is not null;
+create unique index events_dedupe on evolve.events (dedupe_key) where dedupe_key is not null;
+
+create table evolve.identities (
+  anon_id text primary key,
+  user_id text not null,
+  linked_at timestamptz not null default now()
+);
+create index identities_user on evolve.identities (user_id);
+
+create table evolve.usage_daily (
+  day date primary key,
+  tested_pageviews bigint not null default 0
+);
+
+-- Idempotency cache + audit of what aggregate requests returned (kept 24 h).
+create table evolve.aggregate_runs (
+  request_id text primary key,
+  received_at timestamptz not null,
+  mode text not null,
+  status text not null,
+  duration_ms int,
+  response_hash text,
+  response jsonb
+);

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "next-evolve",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Self-improving Next.js sites: server-side variants with no flicker, measured in your own Postgres.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy/index.d.ts",
+      "import": "./dist/proxy/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./instrumentation": {
+      "types": "./dist/instrumentation/index.d.ts",
+      "import": "./dist/instrumentation/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "isbot": "5.2.2",
+    "postgres": "3.4.9",
+    "server-only": "^0.0.1",
+    "@next-evolve/protocol": "0.1.0"
+  },
+  "peerDependencies": {
+    "next": ">=15.5.0",
+    "react": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "fast-check": "^4.10.2",
+    "next": "16.4.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "zod": "^4.6.7",
+    "@next-evolve/fake-cloud": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "next-evolve": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsdown && node scripts/check-dist.mjs && node scripts/check-proxy-imports.mjs && node scripts/check-size.mjs",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --project unit",
+    "test:int": "vitest run --project integration"
+  }
 }