statswhatshesaid 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,14 @@
 # statswhatshesaid
 
-A super minimal drop-in stats library for **self-hosted Next.js**. One metric, one line of integration, **zero runtime dependencies**.
+A super minimal **one-line** drop-in stats library for Next.js. One metric, one line of integration, **zero runtime dependencies**, in-memory only, runs in **both** the Edge and Node runtimes.
 
 - Tracks **unique visitors per day** — that's it.
 - No tracking pixel, no client JS, no cookies.
-- **Zero dependencies.** No native modules, no SQLite, no Docker volume gymnastics.
-- Single ~22KB JSON file for persistence. Atomic writes. Put it anywhere or nowhere.
+- **Zero dependencies.** No native modules, no filesystem, no SQLite, no Docker volume gymnastics.
+- **Works anywhere.** Edge runtime, Node runtime, Vercel, self-hosted, Docker, scratch images. The library uses only Web APIs (`crypto.subtle`, `crypto.getRandomValues`, `globalThis.fetch`).
 - Read your stats by visiting `myapp.com/stats?t=<your-secret>` — JSON response.
 
-> **Designed for freshly launched apps.** Once traffic gets serious you should graduate to a proper analytics suite (Plausible, Umami, PostHog, ...). This library is the thing you drop in on day one so you can tell whether anyone's visiting yet, with absolutely no setup ceremony.
+> **Designed for freshly launched apps.** Counts and history live in process memory. They survive across requests within a single worker but reset on every deploy / restart. That's the trade-off for "drop in and forget." Once your traffic warrants real analytics, graduate to Plausible / Umami / PostHog.
 
 ## Install
 
@@ -18,21 +18,14 @@ npm install statswhatshesaid
 
 ## Use it
 
-Add **one line** to your `middleware.ts`:
+**One line.** That's it.
 
 ```ts
 // middleware.ts
-import stats from 'statswhatshesaid'
-
-export default stats.middleware()
-
-export const config = {
-  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
-  runtime: 'nodejs', // REQUIRED — see "Edge Runtime" below
-}
+export { default } from 'statswhatshesaid'
 ```
 
-Set your secret in the environment:
+Set your secret:
 
 ```bash
 STATS_TOKEN=pick-a-long-random-string
@@ -57,34 +50,50 @@ You'll get JSON back:
 }
 ```
 
-That's the whole library.
+That's the whole library. No `runtime: 'nodejs'` config, no `matcher`, no `experimental`, no `next.config` flags. Just one re-export line.
 
-## Edge Runtime — read this first
+## Customizing options
 
-Next.js middleware defaults to the **Edge runtime**, which can't run `node:crypto` or `node:fs`. You **must** opt into the Node runtime:
+If you need to change defaults — bot filter, endpoint path, history retention, trustProxy hops — import `createMiddleware` instead:
 
 ```ts
+// middleware.ts
+import { createMiddleware } from 'statswhatshesaid'
+
+export default createMiddleware({
+  endpointPath: '/_internal/stats',
+  filterBots: false,
+  trustProxy: 2,
+})
+```
+
+You can also set a custom `matcher` if you want the middleware to run on a narrower path set than "everything":
+
+```ts
+import { createMiddleware } from 'statswhatshesaid'
+
+export default createMiddleware()
+
 export const config = {
-  matcher: [...],
-  runtime: 'nodejs',
+  matcher: ['/((?!api).*)'],
 }
 ```
 
-This is stable in **Next.js 15.2 and newer**.
-
 ## How a "unique visitor" is counted
 
 Cookieless, Plausible-style:
 
 ```
-visitorHash = SHA-256( ip + ":" + userAgent + ":" + dailySalt )
+visitorHash = SHA-256( length-prefixed( ip ) + length-prefixed( userAgent ) + dailySalt )
 ```
 
-- `dailySalt` is generated in process memory and rotates at every UTC midnight.
+- `dailySalt` is generated in process memory at startup and rotated lazily at every UTC midnight.
 - The hash is fed into a [**HyperLogLog** sketch](https://en.wikipedia.org/wiki/HyperLogLog) with 16384 one-byte registers (16 KB fixed per day, forever).
-- At UTC midnight the day's estimate is written to a historical map and the sketch is reset with a fresh salt.
+- At UTC midnight the day's estimate is moved to an in-memory historical map and the sketch is reset with a fresh salt.
 - Cross-day unlinkability: because the salt is regenerated, hashes from different days can't be correlated back to the same visitor.
+- The hash inputs are length-prefixed so two distinct `(ip, ua)` pairs can never collide via separator ambiguity.
 - Common bot User-Agents are filtered out by default.
+- Common static asset paths (`/_next/static/*`, `/_next/image/*`, `/favicon.ico`, `/robots.txt`, `/sitemap.xml`, `/manifest.json`, etc.) are filtered out before tracking, so you don't need a custom `matcher`.
 
 ### About accuracy
 
@@ -94,122 +103,45 @@ If you need exact counts down to the last human, don't use this library — grad
 
 ## Storage
 
-A single JSON file. Default location: `./.statswhatshesaid.json`.
-
-```jsonc
-{
-  "version": 1,
-  "today": "2026-04-07",
-  "salt": "<base64 32 bytes>",
-  "hllRegisters": "<base64 16 KB>",
-  "history": { "2026-04-06": 388, "2026-04-05": 401 }
-}
-```
+**There is none.** Counts and history live in module-level memory inside whichever Next.js worker is running your middleware.
 
-- **One file.** Not a directory, not a DB, no WAL/SHM sidecars.
-- **~22 KB today + 20 bytes per historical day.** Never grows beyond a few hundred KB, ever.
-- **Atomic writes** via write-to-`.tmp` + `rename`. Crash-safe.
-- **Flushed every hour** (tunable) and on `SIGTERM`/`SIGINT`/`beforeExit`.
-- **Nothing on the hot path touches disk.** Tracking a visit is: one SHA-256, one HLL register update. Sub-millisecond.
+- ✅ State **survives across requests** within a single worker / Edge isolate (which is what makes the counter actually count).
+- ❌ State is **lost on every deploy**, process restart, or worker recycle.
+- ❌ State is **per-instance**: if you're running multiple replicas behind a load balancer, each replica has its own counter and they don't sync. Run a single instance, or use a real analytics tool.
 
-### Docker / containers
-
-Because it's one small file, you have options:
-
-```dockerfile
-# Option A: persist it on a volume
-VOLUME /data
-ENV STATS_SNAPSHOT_PATH=/data/stats.json
-```
-
-```dockerfile
-# Option B: bind-mount a single file from the host
-# docker run -v $(pwd)/stats.json:/app/stats.json \
-#            -e STATS_SNAPSHOT_PATH=/app/stats.json ...
-```
-
-```dockerfile
-# Option C: accept ephemerality. Losing "today" on a redeploy is often fine
-# for a small app. The snapshot is flushed on SIGTERM when Node is PID 1,
-# so graceful stops keep the latest data.
-ENV STATS_SNAPSHOT_PATH=/tmp/statswhatshesaid.json
-```
-
-Works fine on `node:20-alpine`, `node:20-slim`, distroless — there are no native modules to compile.
-
-### Bring your own backend
-
-If you want to stash the snapshot in Redis, Vercel KV, S3, or anything else, pass a `persist` adapter:
-
-```ts
-import stats from 'statswhatshesaid'
-import type { PersistAdapter, SnapshotV1 } from 'statswhatshesaid'
-
-const redisPersist: PersistAdapter = {
-  load: () => {
-    const raw = redisClient.get('statswhatshesaid:snap') // your sync/blocking client
-    return raw ? (JSON.parse(raw) as SnapshotV1) : null
-  },
-  save: (snap) => {
-    redisClient.set('statswhatshesaid:snap', JSON.stringify(snap))
-  },
-}
-
-export default stats.middleware({ persist: redisPersist })
-```
-
-The adapter interface is synchronous on purpose so the shutdown handler can flush deterministically.
+This is intentional. The library exists to give freshly launched apps an "is anybody home?" signal in 30 seconds with zero infrastructure. Persistence and replication are a different problem class — graduate when you need them.
 
 ## Configuration
 
-Configure via env vars (preferred) or by passing options to `stats.middleware({...})`. Options override env.
+Configure via env vars (preferred for `STATS_TOKEN`) or by passing options to `createMiddleware({...})`. Options override env.
 
 | Option | Env var | Default |
 | --- | --- | --- |
 | `token` | `STATS_TOKEN` | **required** |
-| `snapshotPath` | `STATS_SNAPSHOT_PATH` | `./.statswhatshesaid.json` |
-| `persist` | — | file adapter at `snapshotPath` |
-| `flushIntervalMs` | `STATS_FLUSH_INTERVAL_MS` | `3600000` (1 hour) |
 | `endpointPath` | `STATS_ENDPOINT_PATH` | `/stats` |
 | `historyDays` | — | `90` (returned from `/stats`) |
-| `maxHistoryDays` | — | `365` (kept in snapshot) |
+| `maxHistoryDays` | — | `365` (kept in memory) |
 | `filterBots` | — | `true` |
 | `trustProxy` | `STATS_TRUST_PROXY` | `1` (see [Security](#security) below) |
 
-```ts
-export default stats.middleware({
-  endpointPath: '/_internal/stats',
-  flushIntervalMs: 5 * 60 * 1000,
-  historyDays: 30,
-  trustProxy: 1,
-})
-```
-
 ## Security
 
-This is a minimal library, but it runs inside your app's request path and writes to your filesystem, so its defaults matter. Read this section before deploying.
+This is a minimal library, but it runs inside your app's request path, so its defaults matter. Read this section before deploying.
 
 ### Threat model
 
 - **In scope:** preventing trivial forging of visitor counts, protecting the `/stats` endpoint from unauthorized reads, keeping the process alive under abuse, making visitor hashes cross-day unlinkable.
-- **Out of scope:** preventing a determined attacker with unlimited resources from skewing the numbers. statswhatshesaid is for day-one visibility on small, self-hosted apps. Once your traffic is big enough that someone would bother flooding your stats, you should be on Plausible / Umami / PostHog anyway.
+- **Out of scope:** preventing a determined attacker with unlimited resources from skewing the numbers. statswhatshesaid is for day-one visibility on small apps. Once your traffic is big enough that someone would bother flooding your stats, you should be on Plausible / Umami / PostHog anyway.
 
 ### 1. `trustProxy` — who decides the client IP?
 
 Unique-visitor dedup hashes the client IP alongside the User-Agent. If the attacker controls the IP you hash with, they control the count.
 
-**The problem:** `X-Forwarded-For` is a list of IPs separated by commas. Each reverse proxy in the chain **appends** the IP of *its own peer* (the thing that spoke TCP to it). The *leftmost* entry is whatever the original client claimed — i.e. attacker-controlled. The *rightmost N entries* are what trusted proxies added, so they're authentic.
-
-To pick the real client IP safely you must **walk the chain from the right, skipping one entry per trusted proxy**.
-
-**Configuration:**
-
-- `trustProxy: 0` — Never read forwarding headers. Every request hashes to a single constant peer. `uniqueVisitors` will under-count dramatically (ideally it collapses to 1), but **nothing an attacker sends can forge it**. Use this only if (a) your process is directly exposed to untrusted clients, or (b) you're OK with a "did anybody visit today?" binary signal.
-
-- `trustProxy: 1` **(default)** — One trusted reverse proxy sits in front of this Node process. The library takes the **rightmost** entry of `X-Forwarded-For`. This is correct for the single most common self-hosted shape: `client → nginx → next`, or `client → Caddy → next`, or `client → Traefik → next`.
-
-- `trustProxy: 2` — Two trusted hops. The library takes the **second-from-right** entry of `X-Forwarded-For`. Use this for setups like `client → Cloudflare → nginx → next` where Cloudflare is ALSO adding to XFF.
+`X-Forwarded-For` is a list of IPs separated by commas. Each reverse proxy in the chain **appends** the IP of *its own peer*. The *leftmost* entry is whatever the original client claimed — i.e. attacker-controlled. The *rightmost N entries* are what trusted proxies added, so they're authentic. To pick the real client IP safely you must **walk the chain from the right, skipping one entry per trusted proxy**.
 
+- `trustProxy: 0` — Never read forwarding headers. Every request hashes to a single constant peer. `uniqueVisitors` will under-count, but **nothing an attacker sends can forge it**.
+- `trustProxy: 1` **(default)** — One trusted reverse proxy in front of this process (`client → nginx → next`). Library takes the **rightmost** entry of `X-Forwarded-For`.
+- `trustProxy: 2` — Two trusted hops (`client → Cloudflare → nginx → next`). Library takes the **second-from-right** entry.
 - `trustProxy: N` — Generalizes to N trusted hops.
 
 **nginx recipe (trustProxy = 1):**
@@ -222,93 +154,64 @@ location / {
 }
 ```
 
-`$proxy_add_x_forwarded_for` appends the client's socket IP to whatever XFF the client sent. With `trustProxy: 1`, statswhatshesaid ignores whatever the client sent and takes the rightmost entry (which is what nginx appended). The client's spoofed values sit uselessly to the left.
-
-**Caddy recipe (trustProxy = 1):**
-
-```caddyfile
-example.com {
-  reverse_proxy 127.0.0.1:3000
-}
-```
-
-Caddy automatically appends the client IP to `X-Forwarded-For` by default.
-
-**Cloudflare + nginx recipe (trustProxy = 2):**
-
-```nginx
-# nginx behind Cloudflare
-location / {
-  proxy_pass http://127.0.0.1:3000;
-  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-}
-```
-
-With `trustProxy: 2`, the second-from-right entry is the real client: `attacker-spoof, real-client, cloudflare-edge`.
+`$proxy_add_x_forwarded_for` appends the client's socket IP to whatever XFF the client sent. With `trustProxy: 1`, statswhatshesaid takes the rightmost entry (nginx's appended value), and the client's spoofed values sit uselessly to the left.
 
-**Direct-exposed (no proxy) warning:** If you're running `next start` straight on `0.0.0.0:3000` with no proxy, **any header you see is attacker-controlled**. Set `trustProxy: 0` and accept that visitor dedup won't work, OR put any reverse proxy in front.
+**Direct-exposed (no proxy) warning:** If you're running Next.js straight on `0.0.0.0:3000` with no proxy in front, **any header you see is attacker-controlled**. Set `trustProxy: 0` and accept that visitor dedup won't work, OR put any reverse proxy in front.
 
 ### 2. Token strength and rate limiting
 
-`/stats` is protected by a single static token. A short token is brute-forceable if an attacker hammers the endpoint.
+`/stats` is protected by a single static token. A short token is brute-forceable.
 
-- statswhatshesaid **warns** at startup if your token is shorter than 32 characters. It does not reject — you might deliberately pick a memorable token for ad-hoc browser access from anywhere.
+- statswhatshesaid **warns** at startup if your token is shorter than 32 characters. It does not reject — you might pick a memorable token for ad-hoc browser access.
 - A safer choice: `openssl rand -hex 32` → a 64-char hex string.
-- The library does **not** rate-limit `/stats`. That's your CDN / reverse-proxy / application middleware's job. For nginx: [`limit_req`](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html). For Cloudflare: [rate limiting rules](https://developers.cloudflare.com/waf/rate-limiting-rules/). For Next.js middleware chains: [`@upstash/ratelimit`](https://github.com/upstash/ratelimit-js).
+- The library does **not** rate-limit `/stats`. That's your CDN / reverse-proxy / application middleware's job ([nginx `limit_req`](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html), [Cloudflare rate limiting](https://developers.cloudflare.com/waf/rate-limiting-rules/), [`@upstash/ratelimit`](https://github.com/upstash/ratelimit-js)).
 
 ### 3. Passing the token: `Authorization` header vs query string
 
-You can pass the token two ways:
+Two ways to pass the token:
 
 | Method | Use when |
 | --- | --- |
 | `Authorization: Bearer <token>` header | **Production** — doesn't leak to access logs, browser history, or Referer |
-| `?t=<token>` query string | Ad-hoc browser checks where typing a header is annoying |
+| `?t=<token>` query string | Ad-hoc browser checks |
 
-Both are accepted. If both are present, the `Authorization` header wins. Example production check:
+Both are accepted. If both are present, the `Authorization` header wins.
 
 ```bash
 curl -H "Authorization: Bearer $STATS_TOKEN" https://myapp.com/stats
 ```
 
-The query string is convenient but ends up in **nginx/CDN access logs, browser history, and Referer headers**. Don't link to `/stats?t=...` from any page.
-
 ### 4. Count inflation by flooding
 
-An attacker who can send arbitrary (IP, User-Agent) pairs — even behind a correctly configured `trustProxy` — can insert arbitrarily many distinct "visitors" into the HLL sketch. Memory doesn't blow up (HLL is fixed 16 KB/day), but the reported `uniqueVisitors` becomes meaningless during the attack. The library cannot prevent this at the middleware layer. **Defense:** rate-limit tracked routes at the same layer that protects the rest of your app. Don't treat the number as authoritative during a suspected abuse event.
+An attacker who can send arbitrary `(IP, User-Agent)` pairs can insert arbitrarily many distinct "visitors" into the HLL sketch. Memory doesn't blow up (HLL is fixed 16 KB/day), but the reported count becomes meaningless during the attack. The library can't prevent this at the middleware layer — rate-limit at your CDN / reverse proxy.
 
-### 5. Snapshot file permissions and contents
+### 5. Privacy properties
 
-- The snapshot file is written with mode `0o600` (owner read/write only). It contains the current day's salt, which would make visitor hashes linkable back to their `(ip, ua)` tuples if disclosed alongside an independent request log.
-- Write is atomic via `.tmp` + `rename`. A crash mid-write leaves the previous snapshot intact.
-- The snapshot file contains **no personal data** — just the HLL registers, the salt, and per-day visitor counts. No IPs or User-Agents are stored.
+- **Cookieless.** The library never sets or reads cookies.
+- **No personal data persisted.** Hashes go into the HLL (which discards them) and are never written anywhere. No filesystem, no remote calls.
+- **Cross-day unlinkability.** The salt rotates at every UTC midnight. Yesterday's hash of `(ip, ua)` is unrelated to today's hash of the same tuple.
+- **No telemetry.** The library makes zero outbound network requests.
 
 ### 6. User-Agent length cap
 
-Incoming User-Agent headers are truncated to **512 bytes** before hashing and bot-filter checks. Node already caps total header size at ~16 KB, but this bounds per-request CPU regardless.
-
-### 7. Privacy properties
-
-- **Cookieless.** The library never sets or reads cookies.
-- **No personal data persisted.** Hashes go into the HLL (which discards them) and are never written to disk.
-- **Cross-day unlinkability.** The salt rotates at every UTC midnight. Yesterday's hash of `(ip, ua)` is unrelated to today's hash of the same tuple.
-- **Mid-day restart caveat.** If the process restarts within the same UTC day, the restored salt (from the snapshot file) is the same, so the same visitor returning after the restart doesn't get double-counted. This means the salt IS on disk for the current day. Rotate `STATS_TOKEN` and delete the snapshot file if you think the file was exposed.
+Incoming User-Agent headers are truncated to **512 bytes** before hashing and bot-filter checks. Bounds per-request CPU regardless of upstream limits.
 
 ## Where it works
 
-- ✅ **Self-hosted Next.js** — `next start` on a VPS, Docker, Fly.io, Railway, etc. Single long-running Node process.
-- ❌ **Vercel / Netlify / serverless by default** — ephemeral filesystem and per-request lambdas mean the in-memory HLL doesn't survive. You *could* make this work with a custom `persist` adapter pointing at Vercel KV or Upstash Redis, but at that point you're probably better off with a hosted analytics service.
+- ✅ **Self-hosted Next.js** (`next start` on a VPS, Docker, Fly.io, Railway, etc.) — single instance.
+- ✅ **Vercel** and other serverless platforms — works in Edge middleware. Counts persist for the lifetime of each isolate; expect them to reset more often than on a long-running self-hosted process.
+- ❌ **Multi-instance deployments** — each replica has its own in-memory counter and they don't sync. The library is single-process by design.
 
 ## Escape hatch (non-middleware integration)
 
-If you can't use `runtime: 'nodejs'` in middleware, call the tracker manually from a route handler or `instrumentation.ts`:
+If you need to call from a route handler or `instrumentation.ts`:
 
 ```ts
-import stats from 'statswhatshesaid'
+import { trackRequest } from 'statswhatshesaid'
 import type { NextRequest } from 'next/server'
 
-export function GET(req: NextRequest) {
-  stats.track(req)
+export async function GET(req: NextRequest) {
+  await trackRequest(req)
   return new Response('ok')
 }
 ```
@@ -328,7 +231,7 @@ The example app under `examples/basic` is the simplest way to smoke-test changes
 
 ## Releasing
 
-Versioning and publishing are managed with [Changesets](https://github.com/changesets/changesets) and automated via GitHub Actions.
+Versioning and publishing are managed with [Changesets](https://github.com/changesets/changesets) and automated via the GitHub Actions Release workflow using **npm trusted publishing** (OIDC). No long-lived npm tokens live in the repo.
 
 **Day-to-day flow:**
 
@@ -337,26 +240,8 @@ Versioning and publishing are managed with [Changesets](https://github.com/chang
    ```bash
    npx changeset
    ```
-   Pick the bump type (patch / minor / major) and write a short summary. Commit the generated `.changeset/*.md` file.
-3. Merge the PR into `main`. The `Release` workflow will open (or update) a **"chore(release): version packages"** PR that bumps `package.json` and updates `CHANGELOG.md`.
-4. When you merge the release PR, the workflow publishes the new version to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) attached.
-
-**One-time setup:**
-
-- The unscoped package name `statswhatshesaid` must be available on npm (`npm view statswhatshesaid` — a 404 means it's yours for the taking on first publish).
-- Add an automation token to the GitHub repo as the `NPM_TOKEN` secret (`Settings → Secrets and variables → Actions`). Use a **granular** token scoped to publish the `statswhatshesaid` package.
-- In `Settings → Actions → General`, under *Workflow permissions*, allow GitHub Actions to **create and approve pull requests** so the release bot can open the version PR.
-
-**Manual publishing (escape hatch):**
-
-If you ever need to cut a release locally:
-
-```bash
-npx changeset version   # bumps package.json + updates CHANGELOG
-git commit -am "chore(release): version packages"
-git push
-npm run release         # verify + changeset publish
-```
+3. Merge the PR into `main`. The Release workflow opens (or updates) a "chore(release): version packages" PR that bumps `package.json` and updates `CHANGELOG.md`.
+4. When you merge the release PR, the workflow publishes the new version to npm with provenance attached.
 
 ## License