next-evolve 0.3.3 → 0.3.5

package/docs/stripe.md

@@ -0,0 +1,91 @@
+# Stripe recipe: count paid subscriptions as a goal
+
+Goal: "did the visitor who saw this variant start paying within 30 days, and how much?" Evolve doesn't connect to Stripe. You record the payment as an event from your own Stripe webhook handler, and link the Stripe customer to the visitor with `identify`.
+
+## 1. Link the visitor to your user
+
+When the visitor signs up (or signs in), link their browser to your user id. In a server action or route handler:
+
+```ts
+import { evolve } from "next-evolve/server";
+
+await evolve.identify(user.id);
+```
+
+## 2. Put your user id on the Stripe objects
+
+When you create the Checkout Session, carry your user id through to the subscription and its invoices:
+
+```ts
+await stripe.checkout.sessions.create({
+  mode: "subscription",
+  client_reference_id: user.id,
+  subscription_data: { metadata: { userId: user.id } },
+  // line_items, success_url, …
+});
+```
+
+## 3. Record the payment in your webhook handler
+
+After you verify the signature, call `evolve.track` with the user id. Use the Stripe event id as `dedupeKey`: Stripe retries deliveries, and Evolve stores each key once.
+
+```ts
+// app/api/stripe/route.ts
+import Stripe from "stripe";
+import { evolve } from "next-evolve/server";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export async function POST(req: Request) {
+  const event = stripe.webhooks.constructEvent(
+    await req.text(),
+    req.headers.get("stripe-signature")!,
+    process.env.STRIPE_WEBHOOK_SECRET!,
+  );
+
+  if (event.type === "invoice.paid") {
+    const invoice = event.data.object;
+    const userId = invoice.parent?.subscription_details?.metadata?.userId;
+    if (userId && invoice.billing_reason === "subscription_create") {
+      await evolve.track("subscription_started", {
+        userId,
+        source: "stripe",
+        props: { amount: invoice.amount_paid / 100, currency: invoice.currency },
+        dedupeKey: event.id,
+      });
+    }
+  }
+  return new Response(null, { status: 200 });
+}
+```
+
+Where the metadata sits on the invoice depends on your Stripe API version; check one `invoice.paid` payload in the Stripe dashboard. `billing_reason === "subscription_create"` counts the first payment only; drop it to count renewals too.
+
+The webhook request has no Evolve cookie, so `userId` is what connects the payment to the visitor (through step 1).
+
+## 4. Define the goal
+
+```ts
+// evolve.goals.ts
+import { defineGoals } from "next-evolve/config";
+
+export default defineGoals({
+  paid: {
+    event: "subscription_started",
+    source: "stripe",
+    window: "30d",
+    value: "amount", // revenue per visitor; omit for conversion rate
+  },
+});
+```
+
+`value` can also be a function, e.g. to convert currencies: `value: (e) => toUsd(e.props.amount as number, e.props.currency as string)`. It runs in your app when the event is written.
+
+Restart the app (or run `npx next-evolve push`) so the cloud sees the new goal, then pick `paid` as the primary or a secondary goal when you create an experiment.
+
+## Notes
+
+- Use `unit: "user"` if people often sign up on one device and pay on another.
+- Payments are attributed to the variant the visitor first saw, if they happen within 30 days of that first exposure.
+- Nothing about the payment leaves your server except the aggregate counts and sums per variant.
+- Using Segment or another service instead? Send the same event to `POST /api/evolve/track` ([API](api.md#http-routes)).

package/docs/troubleshooting.md

@@ -0,0 +1,90 @@
+# Troubleshooting
+
+Start with `npx next-evolve doctor`. It checks the env, key, database, bundle, proxy matcher, pages, `<EvolveScript />` and whether the cloud can reach your app, and says what to fix. The dashboard's **Connect** page shows the cloud's side.
+
+## Setup
+
+**`init`: "A secret key is needed" / "the secret key was rejected".** Pass `--key evk_live_…` (or set `EVOLVE_SECRET_KEY`). The key is shown once when you create the site; if you lost it, issue a new one on the Connect page.
+
+**`init` printed "Add `<EvolveScript />` … to your root layout".** It couldn't find a place to insert it. Add `import { EvolveScript } from "next-evolve/client"` and put `<EvolveScript />` inside `<body>`.
+
+**`init` printed instructions for your proxy.** You already have a `proxy.ts`/`middleware.ts`. Call `applyEvolve` first in it and add the routes plus `/(ev_.*)` to `config.matcher` ([API](api.md#next-evolveproxy)).
+
+**A route stayed in dynamic mode.** `init` says why (top-level `[slug]`, route group, `force-dynamic`, `"use client"` page…). Dynamic mode works the same; the page just isn't cached per variant.
+
+**`cacheComponents` errors.**
+- `Route segment config "revalidate" is not compatible with nextConfig.cacheComponents`: the page was set up in static mode. Re-run `npx next-evolve init` with `next-evolve` 0.3.4 or newer (it uses dynamic mode with `cacheComponents`), or by hand: move the page back out of `app/[evolve]/`, remove the `withEvolve`/`evolveStaticParams`/`evolveMetadata` lines and set the route's mode to `"dynamic"`.
+- `uncached or runtime data … accessed outside of <Suspense>` in `next build`: wrap `<Optimizable>` in `<Suspense>`.
+- `encountered the unstable value Date.now()` in the dev overlay, pointing at `<Optimizable>`: upgrade to `next-evolve` 0.3.5 or newer.
+
+**`doctor`: "Database: not migrated".** Run `npx next-evolve migrate`.
+
+**`doctor`: "Proxy matcher … misses".** Every route in `evolve.config.ts` must be in `config.matcher`, plus `/(ev_.*)`.
+
+## Nothing is being tested
+
+**Every visitor sees control.** In order:
+1. Is the experiment **running** (not draft or paused) and on this exact path? Paths match exactly (a trailing slash is ignored): an experiment on `/pricing` doesn't run on `/pricing/teams`.
+2. Is the route in `evolve.config.ts` and the proxy matcher?
+3. Does the app have a bundle? The log says `no bundle yet` or `bundle fetch failed (401)` (bad key) / `(network)` (cloud unreachable). `doctor` checks it.
+4. Are you a "bot"? Headless browsers, `curl` without a browser user agent, and Lighthouse always get control.
+5. Did `consent` return `false`?
+6. Are you outside the traffic share? Those visitors see control and aren't counted.
+7. Static mode: is the page under `app/[evolve]/` and wrapped with `withEvolve()`? In development, `<Optimizable>` warns "rendered without Evolve context" when it isn't.
+
+**I keep seeing the same variant.** That's intended: a visitor keeps their assignment. Use a private window (each one is a new visitor), delete the `evolve_id` and `evolve_a` cookies, or use a **Preview** link from the experiment page.
+
+**A change in the dashboard doesn't show up.** The app picks up a new bundle when the sync webhook reaches it (seconds), or by polling: within one poll interval (60 s ± 10% in production, 5 s in development) of an instance's last check, on its next request. The request that triggers the check is still served the old bundle. In local development the webhook can't reach `localhost`, so it's polling only. If production is slow, check the Connect page's "Sync webhook" status. On Vercel without Global Config, only the instance that gets the webhook updates at once.
+
+**A variant renders control and isn't counted.** Its props failed the component's schema (the log says `variant … failed its schema`), usually because the schema changed in code after the variant was made. Add a new variant.
+
+## Nothing is being measured
+
+**No rows in `evolve.exposures`.**
+- Is `<EvolveScript />` in the root layout? Check the browser's network tab for `POST /api/evolve/collect` (it batches every 2 s and on page hide).
+- Is `EVOLVE_DATABASE_URL` set where the app runs? `GET /api/evolve/health` returns `"db": true` when it is.
+- Was the visitor counted? Bots, preview sessions, visitors outside the traffic share and visitors without an `evolve_id` cookie aren't.
+- Is the database up? On serverless hosts, events are dropped while it's down (one retry). On a Node server they're buffered (up to 10,000 rows) and written when it's back.
+
+**Goal events don't count.**
+- The event name must match the goal's `event` exactly, and `source`/`where` must match if set.
+- Only events after the visitor's first exposure and within the goal's window count.
+- Server events from webhooks or other devices need `evolve.identify(userId)` to have linked the visitor, and the event must carry that `userId`.
+- New or changed goals reach the cloud when the app restarts (or `npx next-evolve push`).
+
+## Results
+
+**Results show nothing, or not the visit I just made.** Aggregates only count data older than **2 minutes**. Wait and click **Recompute** again (at most once a minute; a second click within a minute does nothing).
+
+**Local development: results never update.** The cloud can't reach `localhost`. Run `npx next-evolve aggregate --upload` (2 minutes after the visits).
+
+**Connect page: "Aggregate route ok · last error: …".** The last aggregate request failed and retries are still pending; the status turns `unhealthy` only after the retries run out. Results keep their last values (and bandit weights stay where they were) until a run succeeds. `HTTP 503 {"error":"database_error"}` means your app couldn't reach its database.
+
+**Connection test fails.**
+- `401` / `bad_signature`: `EVOLVE_WEBHOOK_SECRET` in your app doesn't match the site's. Issue a new one on the Connect page or fix the env var, then redeploy.
+- `403`, `429` or an HTML challenge page: a firewall or bot protection in front of your app blocked the cloud. Let `/api/evolve/*` through ([production.md](production.md#checklist)); the routes check signatures themselves.
+- `404`: the app URL is wrong, or the deploy doesn't have the `app/api/evolve/[...evolve]/route.ts` file.
+- `503 not_configured`: `EVOLVE_SECRET_KEY` or `EVOLVE_WEBHOOK_SECRET` isn't set in the deployed app.
+- Timeout or "no app URL": register it with `npx next-evolve connect --app-url https://…`. It must be a public https URL.
+
+**"Window not elapsed for X% of visitors".** Those visitors' goal windows are still open, so their conversions may still arrive. Not an error.
+
+## The site serves control after working for a while
+
+- **The bundle expired.** If the app couldn't reach the cloud for 14 days, or the key was revoked or the site deleted, the last bundle expires and every visitor gets control. New visitors aren't recorded; returning visitors' events and server events still are. Fix the connection (check `EVOLVE_SECRET_KEY` and outbound access to `api.evolveab.com`); the next poll restores serving.
+- `doctor` fails the bundle check when the current bundle is less than 7 days from expiry.
+
+## Logs
+
+The SDK logs with an `[evolve]` prefix, at most once a minute per message:
+
+| Message                                                      | Meaning                                                                                          |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `no bundle yet (no experiment has started): serving control` | Normal for a new site                                                                            |
+| `bundle fetch failed (401)`                                  | The key is wrong or revoked                                                                      |
+| `bundle fetch failed (network)`                              | The cloud is unreachable; the last bundle keeps serving                                          |
+| `bundle rejected: …`                                         | A bundle failed verification (wrong site, bad signature, older version) and was ignored          |
+| `manifest push failed (…)`                                   | Startup couldn't send routes and goals; retried on the next start, or run `npx next-evolve push` |
+| `customer DB write failed; will retry`                       | The database is unreachable (Node keeps buffering)                                               |
+| `customer DB write failed; batch dropped`                    | The database is unreachable (serverless: the retry failed, those events are lost)                |
+| `customer DB unavailable; dropping N buffered rows`          | The Node buffer is full (10,000 rows)                                                            |

package/docs/what-leaves-your-server.md

@@ -0,0 +1,38 @@
+# What leaves your server
+
+Raw events (exposures, goal events, identities, page views) are written to **your** Postgres and stay there. Evolve Cloud never connects to your database. This page lists every network call the SDK makes and every call it accepts.
+
+## Browser → your app
+
+`<EvolveScript />` sends page views, exposures, goal events and `identify` calls to `/api/evolve/collect` **on your own origin**. Nothing goes to Evolve or any third party from the browser.
+
+## Your app → Evolve Cloud
+
+All calls go to `EVOLVE_CLOUD_URL` (default `https://api.evolveab.com`) with your secret key as a bearer token.
+
+| Call                                                                                                               | When                                                                       | What it carries                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GET /v1/bundle`                                                                                                   | Every 60 s per instance (5 s in dev), and when the sync webhook arrives    | Nothing beyond the key and an `If-None-Match` version. Gets back the signed bundle                                                                                                                                                                                                               |
+| `POST /v1/manifest`                                                                                                | Once per process at startup (`registerEvolve`), `next-evolve push`, `init` | `routes` and their modes from `evolve.config.ts`; goal definitions from `evolve.goals.ts` (value functions become `{ kind: "local-fn" }`); `next-evolve` and Next.js versions; the protocol versions the SDK speaks; your public app URL if known (`EVOLVE_APP_URL`, or Vercel's production URL) |
+| `POST /v1/regions`                                                                                                 | The first time a page renders a region, once per process                   | The region id, the JSON Schema of its editable props, the control props (schema fields only, as written in your code) and the page path                                                                                                                                                          |
+| Aggregate responses                                                                                                | Answering the cloud's aggregate request (below)                            | Signed counts and sums                                                                                                                                                                                                                                                                           |
+| `GET /v1/site`, `PUT /v1/site/app-url`, `POST /v1/site/test`, `POST /v1/aggregates/request`, `POST /v1/aggregates` | Only from the CLI (`init`, `connect`, `doctor`, `aggregate`)               | Your app URL; the same aggregate counts as below                                                                                                                                                                                                                                                 |
+
+## Evolve Cloud → your app
+
+Both routes check an HMAC signature made with `EVOLVE_WEBHOOK_SECRET` (shared only between your app and the cloud), a 5-minute clock window and a replay check.
+
+| Call                         | What it carries                                                                                                                 | What your app sends back                                                                                                                                                                                                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /api/evolve/sync`      | "The bundle changed" (site, version, time), or a ping. No configuration: a forged call can at most cause one extra bundle fetch | `202`                                                                                                                                                                                                                                                                                               |
+| `POST /api/evolve/aggregate` | Which experiments, variants and goal definitions to count, from which day, up to which time                                     | Per experiment × variant × goal × day of first exposure: units, conversions, value sum and sum of squares (and the same for "mature" units whose window has passed). Tested page views per day. Per-goal error messages if a query failed. Duration and SDK version. Signed with the webhook secret |
+
+**Never sent:** visitor ids (`evolve_id`), your user ids, IP addresses, user agents, event props, page-view paths, individual events or timestamps. The cloud's database has no column for them, and a test fails if one is added.
+
+## Your app → Vercel (optional)
+
+With Vercel Global Config configured (`EVOLVE_GLOBAL_CONFIG*`), the sync route writes the signed bundle to your own Global Config store through `api.vercel.com`. It's the same bundle the app downloaded.
+
+## What the cloud stores about your site
+
+Your account and sites, keys (hashed) and the webhook secret (encrypted), the manifest and regions above, experiments and variants, the signed bundles, the aggregate counts per day, computed results, and a log of its calls to your app (status, timing, and the first 200 bytes of an error response).

package/docs/without-an-account.md

@@ -0,0 +1,28 @@
+# What the SDK does without an account
+
+`next-evolve` is MIT-licensed, but on its own it doesn't run experiments: the configuration (the signed bundle), the statistics and the dashboard come from Evolve Cloud. Without a working connection, your site keeps working as if Evolve weren't there.
+
+## No account, no key, or no bundle yet
+
+If `EVOLVE_SECRET_KEY` isn't set, the key is invalid, or the site has never started an experiment:
+
+- Every page renders **control**: the props in your code.
+- **No cookies** are set.
+- **Nothing is recorded** (no assignments means no exposures; the collect route drops visitors without an `evolve_id` cookie).
+- There's no network call on the request path. In the background the SDK tries to fetch a bundle (every 60 s) and logs `no bundle yet (no experiment has started): serving control` or `bundle fetch failed (…)`, at most once a minute.
+- `npx next-evolve pull` writes an empty build bundle and never fails the build.
+
+Removing Evolve is the same as never having added it: delete the `<Optimizable>` wrappers (render the component directly) or leave them; they render control.
+
+## The cloud becomes unreachable
+
+- **Up to 14 days:** the app serves the last bundle it verified. Experiments keep running with their last weights, events keep being written to your database, and the next aggregate after the outage counts them.
+- **After 14 days** (the bundle's expiry): control for everyone, no new cookies. Events from visitors who already have an `evolve_id` cookie, and server events (`evolve.track`, `/api/evolve/track`), are still written; new visitors aren't recorded.
+
+## The key is revoked or the site deleted
+
+The cloud answers `401`, which the SDK treats like an outage: the last bundle serves until it expires (at most 14 days), then control. There's no instant kill switch; to stop an experiment at once, pause it in the dashboard.
+
+## Your database is missing or down
+
+Serving never touches the database, so variants keep serving. Measurement stops: on serverless hosts events are dropped (one retry); on long-running Node up to 10,000 rows are buffered and written when the database is back (oldest dropped first beyond that). The aggregate route answers `503 database_error`.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "next-evolve",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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"
+    "migrations",
+    "docs"
   ],
   "exports": {
     ".": {