easy-ping 0.4.0 → 0.6.0

package/README.md

@@ -1,427 +1,548 @@
-# easy-ping
-
-**Own your notifications.** Your database, your users, no per-notification pricing.
-
-A framework-agnostic, type-safe, self-hosted notifications library for TypeScript — in-app inbox, transactional email, and a plugin system for the rest.
-
-> **Status: pre-release (v0.0.0).** The core pipeline, both adapters (Postgres and MongoDB), the React client, and the preferences, digests and push plugins all work and are covered by tests against real databases. Web push is verified end to end against Mozilla's production push service and cross-checked against `http_ece`. Realtime and batching are not built, and the Resend provider has still only been exercised against a stub. APIs may still move.
-
----
-
-## Why
-
-Every app past the weekend-project stage needs a notification bell, transactional email, and user preferences. The options are a platform you deploy (Novu), a SaaS you rent per notification (Knock, Courier), a workflow platform plus your own table (Inngest + Resend), or hand-rolling it badly.
-
-easy-ping runs **inside your app**, stores notifications in **your database**, and never charges per send.
-
-**Scale target:** thousands to low-millions of notifications per month. Not Slack-scale fan-out. Every "no queue required" decision below follows from that.
-
----
-
-## Quickstart
-
-### 1. Install
-
-```bash
-pnpm add easy-ping drizzle-orm postgres zod
-```
-
-### 2. Create the tables
-
-```ts
-// db/schema.ts
-import { createSchema } from "easy-ping/adapters/drizzle";
-
-export const { notification, notificationDelivery, notificationPreference } = createSchema();
-```
-
-Push them with `drizzle-kit`, or generate raw SQL:
-
-```ts
-import { coreSchema, renderPostgresDdl } from "easy-ping/schema";
-
-for (const statement of renderPostgresDdl(coreSchema)) await sql.unsafe(statement);
-```
-
-<details>
-<summary>Without an ORM (plain pg, postgres.js, Kysely…)</summary>
-
-```bash
-pnpm add easy-ping pg zod
-```
-
-```ts
-import { postgresAdapter } from "easy-ping/adapters/postgres";
-import { Pool } from "pg";
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-
-const database = postgresAdapter(
-  async (text, params) => (await pool.query(text, params as unknown[])).rows,
-  {
-    // Optional, but it is what makes createNotifications atomic.
-    transaction: async (fn) => {
-      const client = await pool.connect();
-      try {
-        await client.query("BEGIN");
-        const result = await fn(async (t, p) => (await client.query(t, p as unknown[])).rows);
-        await client.query("COMMIT");
-        return result;
-      } catch (error) {
-        await client.query("ROLLBACK");
-        throw error;
-      } finally {
-        client.release();
-      }
-    },
-  },
-);
-```
-
-One function — run a parameterised statement, return rows — is the entire contract.
-Anything that can do that works: `pg`, `postgres.js`, Kysely, Neon or PlanetScale's
-serverless drivers, or Prisma's `$queryRawUnsafe`.
-
-</details>
-
-<details>
-<summary>On MongoDB instead</summary>
-
-```bash
-pnpm add easy-ping mongodb zod
-```
-
-```ts
-import { createMongoIndexes, mongoAdapter } from "easy-ping/adapters/mongodb";
-
-const client = new MongoClient(process.env.MONGO_URL!);
-await client.connect();
-const db = client.db("app");
-
-// There are no tables to create, only indexes. Run once at startup.
-await createMongoIndexes(db);
-
-// Pass the client too: it is what makes a notification and its deliveries
-// land together, which needs a replica set.
-const database = mongoAdapter(db, { client });
-```
-
-Everything after this point is identical.
-
-</details>
-
-### 3. Configure
-
-```ts
-// notify.ts
-import { defineNotification, easyPing, escapeHtml } from "easy-ping";
-import { drizzleAdapter } from "easy-ping/adapters/drizzle";
-import { resend } from "easy-ping/providers/resend";
-import { after } from "next/server";
-import { inArray } from "drizzle-orm";
-import { z } from "zod";
-import { auth } from "./auth";
-import { db, users } from "./db";
-
-export const notify = easyPing({
-  database: drizzleAdapter(db),
-
-  // Both at least 16 characters; `openssl rand -base64 32` is the easy way.
-  secret: process.env.NOTIFY_SECRET!,
-  cron: { secret: process.env.NOTIFY_CRON_SECRET! },
-
-  // Required. The mounted endpoints serve a user's private inbox.
-  session: {
-    getUserId: async (request) =>
-      (await auth.api.getSession({ headers: request.headers }))?.user.id ?? null,
-  },
-
-  // Batched — one call per send, never one per recipient.
-  getRecipients: async (userIds) =>
-    (await db.select().from(users).where(inArray(users.id, [...userIds]))).map((u) => ({
-      userId: u.id,
-      email: u.email,
-      timezone: u.timezone,
-      locale: u.locale,
-    })),
-
-  channels: {
-    inApp: { enabled: true },
-    email: { provider: resend({ apiKey: process.env.RESEND_API_KEY!, from: "Acme <hi@acme.dev>" }) },
-  },
-
-  delivery: { mode: "deferred", waitUntil: after },
-
-  notifications: {
-    commentReply: defineNotification({
-      schema: z.object({ authorName: z.string(), commentId: z.string() }),
-      channels: ["inApp", "email"],
-      email: {
-        subject: (p) => `${p.authorName} replied to you`,
-        // Anything a user typed goes through escapeHtml, or their markup ships from your domain.
-        template: (p) =>
-          `<p>${escapeHtml(p.authorName)} replied. <a href="/c/${encodeURIComponent(p.commentId)}">View</a></p>`,
-      },
-    }),
-  },
-});
-```
-
-### 4. Mount the endpoints
-
-```ts
-// app/api/notifications/[...notify]/route.ts
-import { notify } from "@/notify";
-
-export const { GET, POST } = notify.handler;
-```
-
-### 5. Send
-
-```ts
-await notify.send("commentReply", {
-  to: threadOwnerId,
-  payload: { authorName: "Dana", commentId: "c_123" }, // typed against the schema
-  dedupeKey: `commentReply:c_123:${threadOwnerId}`,    // optional, makes retries safe
-});
-```
-
-### 6. Render the bell
-
-```tsx
-"use client";
-import { useNotifications } from "easy-ping/react";
-
-export function Bell() {
-  const { notifications, unseenCount, markAsRead, markSeen } = useNotifications();
-
-  return (
-    <button onClick={() => markSeen()}>
-      {unseenCount}
-      {notifications.map((n) => (
-        <div key={n.id} onClick={() => markAsRead(n.id)}>
-          {n.type} {n.readAt ? "" : "•"}
-        </div>
-      ))}
-    </button>
-  );
-}
-```
-
-### 7. Wire the cron
-
-```
-POST /api/notifications/cron
-Authorization: Bearer $NOTIFY_CRON_SECRET
-```
-
-Every 1–5 minutes, from Vercel Cron, GitHub Actions, or anything else. This is the durability floor beneath every delivery mode — **required** for `cron` and `deferred`.
-
----
-
-## How delivery works
-
-`send()` validates, resolves recipients, runs hooks, and writes the notification and delivery rows in one transaction. **Committing those rows is the only thing it has to do** — a 200–800ms provider round trip has no business on a comment POST.
-
-What happens next is `delivery.mode`'s job. In `deferred`, `worker` and `cron`, `send()` returns as soon as the rows are committed and never waits on a provider. `inline` is the exception: it awaits that send's own deliveries before resolving, which is the tradeoff you accept for the simplest possible setup.
-
-Delivery then happens according to `delivery.mode`:
-
-| mode | delivery happens | latency | needs cron |
-| --- | --- | --- | --- |
-| `inline` | before `send()` resolves | in-request | recommended |
-| `deferred` | after the response, via `waitUntil` | ~1s | **yes** |
-| `worker` | in-process poller | ~1s | optional |
-| `cron` | when the sweep runs | up to the interval | **yes** |
-
-Modes are **additive**. `deferred` and `worker` are latency optimisations layered over the cron sweep — the rows are already committed, so a missing platform primitive or a crashed process costs latency, never a notification.
-
-```ts
-const worker = notify.startWorker({ intervalMs: 1000 });
-process.on("SIGTERM", () => worker.stop()); // drains in-flight work, releases leases
-```
-
-**Delivery is at-least-once.** Providers receive an idempotency key derived from the delivery id. Retries use exponential backoff with jitter (30s → 2m → 8m → 32m, five attempts), floored by your cron interval. Non-retryable failures — a revoked API key, an invalid recipient — fail immediately rather than burning all five attempts.
-
-**Not for OTP or 2FA codes.** Use your auth library's own sender. A retry-and-sweep model is wrong for a 60-second TTL.
-
----
-
-## Channels
-
-| channel | state |
-| --- | --- |
-| `inApp` | ✅ built in, on by default, needs no provider |
-| `email` | ✅ Resend provider; the interface is open for others |
-| `push` | ✅ push plugin + `webPush()` — VAPID and aes128gcm on Web Crypto, so it runs on edge too |
-| `sms` | ⬜ not implemented |
-| `slack` | ⬜ not implemented |
-
-A channel is usable when core carries it (`inApp`, `email`) or a plugin declares it and can `deliver` it. That is how push works, and how sms and slack will.
-
-Declaring a channel nothing can carry **warns at startup** and reports `skipped: "channel-unavailable"` — deliberately distinct from `"no-channels"`, so a missing provider never looks like a user opt-out.
-
-## Upgrading
-
-A later version may add a column. How you pick it up depends on how you created the tables:
-
-| you bootstrapped with | to upgrade |
-| --- | --- |
-| `createSchema()` + drizzle-kit | `drizzle-kit` diffs it for you — nothing to do here |
-| `renderPostgresDdl()` | `planPostgresMigration()` — see below |
-| `createMongoIndexes()` | rerun it; `createIndex` is idempotent and additive |
-
-**`renderPostgresDdl` cannot upgrade you.** It emits `CREATE TABLE IF NOT EXISTS`, which is correct exactly once and a silent no-op afterwards. Rerunning it on an existing database does nothing at all.
-
-```ts
-import { INTROSPECT_SQL, planPostgresMigration, coreSchema } from "easy-ping/schema";
-
-const plan = await planPostgresMigration(
-  async () =>
-    (await sql.unsafe(INTROSPECT_SQL)).map((row) => ({
-      table: row.table_name,
-      column: row.column_name,
-      type: row.data_type,
-      nullable: row.is_nullable === "YES",
-    })),
-  coreSchema,
-);
-
-for (const statement of plan.statements) await sql.unsafe(statement);
-if (plan.unsupported.length) console.warn(plan.unsupported);
-```
-
-**Additive only, deliberately.** It adds missing columns and indexes, and creates tables that do not exist. It never drops a column, never changes a type, and never touches a column it did not declare — those land in `unsupported` as a message for a human, because they are destructive and context-dependent.
-
-One behaviour worth knowing: a **required** column with no default is added **nullable**, because `NOT NULL` would abort against existing rows. That is reported in `unsupported`; backfill it and `SET NOT NULL` yourself.
-
-Run the plugins' schemas the same way — `push({...}).schema`, `preferences().schema`.
-
----
-
-## When something fails
-
-Delivery is at-least-once with five attempts and backoff, which means failures are quiet by design. To see them:
-
-```ts
-const failed = await notify.getFailedDeliveries({ since: new Date(Date.now() - 86_400_000) });
-// [{ id, notificationId, channel, attempts, lastError, updatedAt, ... }]
-```
-
-Defaults to the last 24 hours, capped at 1000 rows. Wire it to an admin page or an alert — otherwise the retry machinery is a black box, and a revoked API key looks exactly like nothing happening.
-
-`notify.healthCheck()` reports the delivery mode and warns when a mode needs a cron you have not mounted.
-
----
-
-## Security notes
-
-- **`session.getUserId` is mandatory.** There is no default and no dev bypass — an insecure default ships, a startup crash doesn't. Returning `null` yields 401; *throwing* yields 500, because a broken session store and an absent session are different bugs.
-- **Every query is scoped server-side.** No route accepts a user id from the client. Marking someone else's notification read returns 404, not 403 — a 403 confirms the row exists.
-- **`cron.secret` is required** for modes that rely on the sweep. Unauthenticated, that endpoint is a free flush-everything trigger against your email provider. Compared in constant time. Plugin machine routes (`/push/prune`, `/digests/cron`) accept it too unless you set `machineSecret`, which keeps the scheduler's credential to `/cron` alone. One call drains at most `cron.maxSweeps` sweeps (default 50).
-- **Plugins never see the secret.** They get `ctx.sign()`, which mints tokens only for the purposes their own signed routes declare; keys are derived per purpose with HKDF, so an unsubscribe key signs nothing else. `notify.listRoutes()` shows every mounted route with its auth scope, and a `custom`-scoped route is named in a startup warning with its justification.
-- **Secrets must be at least 16 characters** and not a placeholder; startup throws otherwise. A short HMAC key makes every unsubscribe link forgeable offline.
-- **CSRF.** Every POST must be `application/json` (415 otherwise) and, when the browser sends an `Origin`, it must match the request host or an entry in `trustedOrigins` (403 otherwise). This holds even if your session cookie is `SameSite=None`. Set `trustedOrigins: ["https://app.example.com", "*.example.com"]` when the API lives on a different origin from the page.
-- **Push endpoints are validated at registration.** Public https hosts only, well-formed keys, one owner per endpoint for life (409 if another account registered it), at most `maxDevicesPerUser` rows per user. Pin `allowedEndpointHosts` to the push services you expect if you want the SSRF surface closed entirely.
-- **Email templates are sent as-is.** Run every payload field a user could have typed through `escapeHtml`, or use a templating library that escapes by default. The quickstart shows the pattern.
-- **In-app payloads are served to the browser verbatim.** Never put anything in `payload` the recipient shouldn't read, and never render it with `innerHTML`.
-- **Request bodies are capped at 64 KiB** (`maxBodyBytes`), responses carry `Cache-Control: private, no-store`, and a thrown adapter error is a logged 500 rather than a stack trace or a crashed process.
-- **Rate limiting.** `rateLimit: { max, windowMs }` is an in-process fixed-window limiter keyed by the client address from `cf-connecting-ip` / `x-real-ip` / `x-forwarded-for` (or your own `key`), applied to every route including `/cron` and `/unsubscribe`. It is per process, not global: enough to blunt secret guessing and poll storms, not a quota. `onRequest` runs before it if you have a shared limiter of your own. The inbox is polled by every open tab, so size limits with that in mind.
-- **Unsubscribe tokens** travel in the URL, so they will appear in access logs. They are valid for 30 days by default, capped at 90. A token is refused if the user changed that preference after it was issued, so an old link cannot undo a newer decision; clicking the same link twice is still a 200. `last_error` stores provider messages with email addresses redacted.
-
----
-
-## Status
-
-| | |
-| --- | --- |
-| ✅ Core `send()` pipeline, hooks, dedupe | |
-| ✅ Postgres through any driver — no ORM needed | `pg`, `postgres.js`, Kysely, Neon… |
-| ✅ Postgres via Drizzle, for those already on it | same conformance suite |
-| ✅ MongoDB | same conformance suite |
-| ✅ Delivery runner, all four modes, retry + backoff | |
-| ✅ Resend provider | |
-| ✅ Route handler, session scoping, cron | |
-| ✅ React client, polling, optimistic updates | |
-| ✅ preferences plugin + headless `usePreferences` | the wedge |
-| ✅ digests plugin, timezone-aware | |
-| ✅ push plugin + web-push provider | VAPID + RFC 8291, no node:crypto |
-| ✅ push verified against a live push service | Mozilla autopush, plus a cross-check against `http_ece` |
-| ✅ scoped plugin storage, so plugins own their tables | |
-| ✅ additive schema migrations for the raw-SQL path | `planPostgresMigration()` |
-| ✅ failed deliveries reachable from the instance | `notify.getFailedDeliveries()` |
-| ⬜ realtime, batching | |
-| ⬜ Prisma / Kysely adapters, Vue / Svelte bindings | |
-
----
-
-## Writing an adapter
-
-The one operation with no equivalent in other libraries is atomic claiming — without it, two concurrent sweeps send the same email twice. Verify yours:
-
-```ts
-import { adapterConformanceCases } from "easy-ping/testing";
-
-for (const testCase of adapterConformanceCases) {
-  it(testCase.name, () => testCase.run({ adapter, reset, setAttempts, lockRow }));
-}
-```
-
-Thirteen cases. The one that matters asserts a row locked by another transaction is *skipped*, not waited on; it is tagged `requires: "rowLock"`, and a store whose claim is a single atomic update filters it out rather than faking it.
-
-Declare your dialect on the adapter so the plugin store writes what your driver expects:
-
-```ts
-naming: "snake_case" | "preserve"   // columns, or the declared field names
-serializesJson: boolean             // json as a string, or natively
-```
-
----
-
-## Development
-
-```bash
-pnpm install
-docker compose up -d     # Postgres on :54329, MongoDB on :27019
-pnpm test
-```
-
-Mongo runs as a single-node replica set, because that is the only way it offers transactions.
-
-Database tests skip locally when a database is unreachable, and **fail** in CI — a green build that ran none of them is worse than a red one.
-
-The push crypto is checked two ways. `web-push-reference.test.ts` decrypts our output with `http_ece` — the library `web-push` npm uses — because a decryptor written from the same RFC would share any misreading and agree with itself. `web-push-live.test.ts` then sends through Mozilla's production push service for real; it is opt-in so CI never goes red because someone else's service is having a bad afternoon:
-
-```bash
-EASY_PING_LIVE_PUSH=1 pnpm --filter easy-ping test web-push-live
-```
-
-The Resend provider is checked against Resend's real API too: the rejection paths need no credentials — a bogus key coming back as a structured 401 rather than a 400 is what proves the request shape is right. The delivery leg needs your own key:
-
-```bash
-RESEND_API_KEY=re_... RESEND_FROM="Acme <hi@acme.dev>"   pnpm --filter easy-ping test resend-live
-```
-
-## Releasing
-
-Nothing is on npm yet. The name `easy-ping` is unclaimed.
-
-The Release workflow only maintains the version PR; it does **not** publish. npm trusted publishing (OIDC) cannot create a package that does not exist — a trusted publisher is configured against an existing package, so the first `PUT` is rejected as `E404`, which reads like "name taken" and is not.
-
-The first release is manual:
-
-```bash
-# 1. bump off 0.0.0
-pnpm changeset            # choose minor -> 0.1.0
-pnpm changeset version
-
-# 2. publish once, by hand
-npm login
-pnpm --filter easy-ping publish --access public
-```
-
-Then enable trusted publishing on npmjs.com for this repo and this workflow, and re-add `publish: pnpm changeset publish` to `.github/workflows/release.yml`. Every release after that is automatic.
-
-## License
-
-MIT
+<div align="center">
+
+# easy-ping
+
+**Own your notifications.**
+In-app inbox, transactional email and web push — running inside your app, stored in your
+database, with no per-notification bill.
+
+[![npm](https://img.shields.io/npm/v/easy-ping?color=%23e0362a&label=npm)](https://www.npmjs.com/package/easy-ping)
+[![install size](https://packagephobia.com/badge?p=easy-ping)](https://packagephobia.com/result?p=easy-ping)
+[![node](https://img.shields.io/node/v/easy-ping)](https://www.npmjs.com/package/easy-ping)
+[![license](https://img.shields.io/npm/l/easy-ping?color=blue)](./LICENSE)
+
+[Documentation](https://easy-notify-website.vercel.app) · [Quickstart](https://easy-notify-website.vercel.app/docs/quickstart) · [Changelog](https://easy-notify-website.vercel.app/docs/changelog) · [AI context](https://easy-notify-website.vercel.app/docs/ai-assistant)
+
+</div>
+
+---
+
+```ts
+await notify.send("commentReply", {
+  to: threadOwnerId,
+  payload: { authorName: "Dana", commentId: "c_123" },  // typed from your schema
+  dedupeKey: `commentReply:c_123:${threadOwnerId}`,      // optional, makes retries safe
+});
+```
+
+```tsx
+const { notifications, unseenCount, markSeen, markAsRead } = useNotifications();
+```
+
+One config file, one `send()`, one hook. No queue, no worker service, no vendor.
+
+---
+
+## Why
+
+Every app past the weekend-project stage needs a notification bell, transactional email and user
+preferences. The alternatives are a platform you deploy, a SaaS you rent per notification, or
+hand-rolling it badly.
+
+|  | easy-ping | Novu (self-hosted) | Knock · Courier |
+| --- | --- | --- | --- |
+| **What you deploy** | nothing, it is a dependency | four services | nothing, it is their cloud |
+| **Infrastructure it adds** | none | MongoDB, Redis, S3 | none |
+| **Where notifications live** | your Postgres or MongoDB | Novu's MongoDB | theirs |
+| **Cost per notification** | none | none, you pay for servers | metered per send |
+| **License** | MIT, all of it | MIT core, commercial modules | proprietary |
+| **Visual workflow editor** | **no**, a notification is code | yes | yes |
+| **Channels out of the box** | **in-app, email, web push** | dozens | dozens |
+
+The last two rows are the trade. If you need a workflow editor a non-developer can edit, use one
+of the others — they are good tools solving a bigger problem.
+
+**Scale target:** thousands to low-millions of notifications per month. Not Slack-scale fan-out.
+Every "no queue required" decision below follows from that.
+
+> **Status: published, pre-1.0.** The core pipeline, all three adapters, the React client and the
+> preferences, digests and push plugins are covered by tests against real databases. Web push is
+> verified end to end against Mozilla's production push service and cross-checked against
+> `http_ece`. The bell updates over a server-sent event stream with polling as the fallback;
+> batching is not built, and the Resend provider has only been exercised against a stub. Minor
+> versions may still move APIs before 1.0.
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pnpm add easy-ping pg zod
+```
+
+### 2. Create the tables
+
+No ORM required. The whole database contract is one function: run a parameterised statement,
+return rows.
+
+```ts
+import { createPostgresTables, pgTransaction, postgresAdapter } from "easy-ping/adapters/postgres";
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const query = async (text, params) => (await pool.query(text, params)).rows;
+
+// Renders the DDL from the installed version's own schema, so the tables
+// cannot drift from the package. Every statement is IF NOT EXISTS.
+await createPostgresTables(query);
+
+export const database = postgresAdapter(query, { transaction: pgTransaction(pool) });
+```
+
+Anything that can run a statement works: `pg`, `postgres.js`, Kysely, Neon or PlanetScale's
+serverless drivers, or Prisma's `$queryRawUnsafe`.
+
+<details>
+<summary>Already on Drizzle</summary>
+
+```ts
+// db/schema.ts
+import { createSchema } from "easy-ping/adapters/drizzle";
+
+export const { notification, notificationDelivery, notificationPreference } = createSchema();
+```
+
+Push it with `drizzle-kit`, then `drizzleAdapter(db)` in place of `postgresAdapter`.
+
+</details>
+
+<details>
+<summary>On MongoDB instead</summary>
+
+```bash
+pnpm add easy-ping mongodb zod
+```
+
+```ts
+import { createMongoIndexes, mongoAdapter } from "easy-ping/adapters/mongodb";
+
+const client = new MongoClient(process.env.MONGO_URL!);
+await client.connect();
+const db = client.db("app");
+
+// No tables, only indexes. Run once at startup.
+await createMongoIndexes(db);
+
+// Pass the client too: it is what makes a notification and its deliveries
+// land together, which needs a replica set.
+export const database = mongoAdapter(db, { client });
+```
+
+Everything after this point is identical.
+
+</details>
+
+<details>
+<summary>On MySQL instead</summary>
+
+```bash
+pnpm add easy-ping mysql2 zod
+```
+
+```ts
+import { createMysqlTables, mysql2Query, mysqlAdapter, mysqlTransaction } from "easy-ping/adapters/mysql";
+import mysql from "mysql2/promise";
+
+// timezone "Z": the adapter writes DATETIME columns as UTC and must read them back unshifted.
+const pool = mysql.createPool({ uri: process.env.DATABASE_URL, timezone: "Z" });
+const query = mysql2Query(pool);
+
+await createMysqlTables(query);   // CREATE TABLE IF NOT EXISTS, safe on every boot
+
+// With a transaction, a claim uses FOR UPDATE SKIP LOCKED (MySQL 8+). Without
+// one it is a single lock-free UPDATE that still never double-claims a row.
+export const database = mysqlAdapter(query, { transaction: mysqlTransaction(pool) });
+```
+
+MySQL 8 or MariaDB. Any driver works: the contract is `(text, params) => Promise<{ rows, affectedRows }>`.
+
+</details>
+
+<details>
+<summary>On SQLite instead</summary>
+
+```ts
+import { createSqliteTables, sqliteAdapter, sqliteQuery, sqliteTransaction } from "easy-ping/adapters/sqlite";
+import { DatabaseSync } from "node:sqlite";   // Node 22.13+; better-sqlite3 works the same way
+
+const db = new DatabaseSync("./app.db");
+const query = sqliteQuery(db);
+
+await createSqliteTables(query);
+
+export const database = sqliteAdapter(query, { transaction: sqliteTransaction(db) });
+```
+
+SQLite has one writer at a time, so the claim is a plain `UPDATE … WHERE id IN (SELECT … LIMIT ?)`; two sweeps cannot interleave. Dates are ISO text, booleans 0/1, JSON text.
+
+</details>
+
+<details>
+<summary>Adding a plugin's tables</summary>
+
+Plugins own their own tables and export the declaration, so no plugin instance is needed:
+
+```ts
+import { pushSchema } from "easy-ping/plugins/push";
+
+await createPostgresTables(query, { plugins: [pushSchema] });
+```
+
+</details>
+
+### 3. Configure
+
+```ts
+// notify.ts
+import { defineNotification, easyPing, escapeHtml } from "easy-ping";
+import { resend } from "easy-ping/providers/resend";
+import { after } from "next/server";
+import { z } from "zod";
+import { auth } from "./auth";
+import { database, pool } from "./db";   // from step 2
+
+export const notify = easyPing({
+  database,
+
+  // Both at least 16 characters; `openssl rand -base64 32` is the easy way.
+  secret: process.env.NOTIFY_SECRET!,
+  cron: { secret: process.env.NOTIFY_CRON_SECRET! },
+
+  // Required. The mounted endpoints serve a user's private inbox.
+  session: {
+    getUserId: async (request) =>
+      (await auth.api.getSession({ headers: request.headers }))?.user.id ?? null,
+  },
+
+  // Batched: one call per send, never one per recipient.
+  getRecipients: async (userIds) => {
+    const { rows } = await pool.query(
+      "select id, email, timezone, locale from users where id = any($1)",
+      [userIds],
+    );
+    return rows.map((u) => ({
+      userId: u.id,
+      email: u.email,
+      timezone: u.timezone,
+      locale: u.locale,
+    }));
+  },
+
+  channels: {
+    inApp: { enabled: true },
+    email: { provider: resend({ apiKey: process.env.RESEND_API_KEY!, from: "Acme <hi@acme.dev>" }) },
+  },
+
+  delivery: { mode: "deferred", waitUntil: after },
+
+  notifications: {
+    commentReply: defineNotification({
+      schema: z.object({ authorName: z.string(), commentId: z.string() }),
+      channels: ["inApp", "email"],
+      email: {
+        subject: (p) => `${p.authorName} replied to you`,
+        // Anything a user typed goes through escapeHtml, or their markup ships from your domain.
+        template: (p) =>
+          `<p>${escapeHtml(p.authorName)} replied. <a href="/c/${encodeURIComponent(p.commentId)}">View</a></p>`,
+      },
+    }),
+  },
+});
+```
+
+### 4. Mount the endpoints
+
+```ts
+// app/api/notifications/[[...notify]]/route.ts
+// Double brackets: Next's required catch-all would not match the bare
+// /api/notifications path, which is where the feed lives.
+import { notify } from "@/notify";
+
+export const { GET, POST } = notify.handler;
+```
+
+### 5. Send
+
+```ts
+await notify.send("commentReply", {
+  to: threadOwnerId,
+  payload: { authorName: "Dana", commentId: "c_123" }, // typed against the schema
+  dedupeKey: `commentReply:c_123:${threadOwnerId}`,    // optional, makes retries safe
+});
+```
+
+### 6. Render the bell
+
+```tsx
+"use client";
+import { useNotifications } from "easy-ping/react";
+
+export function Bell() {
+  const { notifications, unseenCount, markAsRead, markSeen } = useNotifications();
+
+  return (
+    <button onClick={() => markSeen()}>
+      {unseenCount}
+      {notifications.map((n) => (
+        <div key={n.id} onClick={() => markAsRead(n.id)}>
+          {n.type} {n.readAt ? "" : "•"}
+        </div>
+      ))}
+    </button>
+  );
+}
+```
+
+The hook is headless and keeps itself fresh without a socket server: one tab per browser holds a
+`GET /events` stream and the others mirror it over `BroadcastChannel`, so ten open tabs cost one
+connection and zero idle queries. `send()`, `/read` and `/seen` push a `changed` event, the tab
+refreshes, and where a stream cannot live (a serverless host that cuts it, a hardened proxy) the
+client notices and falls back to polling that slows down while the user is idle. Nothing to
+configure; `transport: "poll"` switches the stream off if you want the old behaviour.
+
+Two optional extras when you want the bell fresh with no dedicated request at all:
+
+```ts
+// Piggyback: any response from your own API can carry the inbox version.
+return Response.json(data, { headers: notify.inboxHeaders(userId) });
+// ...and the client refreshes only when that number moves.
+const fetchWithBell = client.instrument(fetch);
+
+// Push relay: if you already run the push plugin, the service worker wakes the bell too.
+import { handlePush } from "easy-ping/sw";
+self.addEventListener("push", (event) => handlePush(event));
+```
+
+### 7. Wire the cron
+
+```
+POST /api/notifications/cron
+Authorization: Bearer $NOTIFY_CRON_SECRET
+```
+
+Every 1–5 minutes, from Vercel Cron, GitHub Actions, or anything else. This is the durability floor beneath every delivery mode — **required** for `cron` and `deferred`.
+
+---
+
+## How delivery works
+
+`send()` validates, resolves recipients, runs hooks, and writes the notification and delivery rows in one transaction. **Committing those rows is the only thing it has to do** — a 200–800ms provider round trip has no business on a comment POST.
+
+What happens next is `delivery.mode`'s job. In `deferred`, `worker` and `cron`, `send()` returns as soon as the rows are committed and never waits on a provider. `inline` is the exception: it awaits that send's own deliveries before resolving, which is the tradeoff you accept for the simplest possible setup.
+
+Delivery then happens according to `delivery.mode`:
+
+| mode | delivery happens | latency | needs cron |
+| --- | --- | --- | --- |
+| `inline` | before `send()` resolves | in-request | recommended |
+| `deferred` | after the response, via `waitUntil` | ~1s | **yes** |
+| `worker` | in-process loop, woken by `send()` | ~instant in-process, ≤10s across replicas | optional |
+| `cron` | when the sweep runs | up to the interval | **yes** |
+
+Modes are **additive**. `deferred` and `worker` are latency optimisations layered over the cron sweep — the rows are already committed, so a missing platform primitive or a crashed process costs latency, never a notification.
+
+```ts
+const worker = notify.startWorker(); // idles 10s between sweeps; a send() in this process wakes it at once
+process.on("SIGTERM", () => worker.stop()); // drains in-flight work, releases leases
+```
+
+On `cron` and `deferred` hosts that see traffic but no scheduler for minutes at a time,
+`delivery.sweepOnRequest: true` runs a small bounded sweep after any request, at most every 5 s,
+so a free-tier deployment delivers within seconds of the next page load instead of the next cron.
+
+**Across replicas**, wake-ups travel through `signals`: a publish says "something changed, go
+look" and carries no payload, so losing one costs latency, never a notification.
+
+```ts
+import { postgresSignals } from "easy-ping/adapters/postgres"; // LISTEN/NOTIFY, one channel
+import { mongoSignals } from "easy-ping/adapters/mongodb";     // change stream on a capped collection
+
+easyPing({ ..., signals: postgresSignals(sql) });
+```
+
+Without one, each process uses in-memory signals and the event stream falls back to a cheap
+fingerprint probe every 30 s (`events.probeIntervalMs`), which is exactly right on SQLite or a
+single replica.
+
+**Delivery is at-least-once.** Providers receive an idempotency key derived from the delivery id. Retries use exponential backoff with jitter (30s → 2m → 8m → 32m, five attempts), floored by your cron interval. Non-retryable failures — a revoked API key, an invalid recipient — fail immediately rather than burning all five attempts.
+
+**Not for OTP or 2FA codes.** Use your auth library's own sender. A retry-and-sweep model is wrong for a 60-second TTL.
+
+---
+
+## Channels
+
+| channel | state |
+| --- | --- |
+| `inApp` | ✅ built in, on by default, needs no provider |
+| `email` | ✅ Resend provider; the interface is open for others |
+| `push` | ✅ push plugin + `webPush()` — VAPID and aes128gcm on Web Crypto, so it runs on edge too |
+| `sms` | ⬜ not implemented |
+| `slack` | ⬜ not implemented |
+
+A channel is usable when core carries it (`inApp`, `email`) or a plugin declares it and can `deliver` it. That is how push works, and how sms and slack will.
+
+Declaring a channel nothing can carry **warns at startup** and reports `skipped: "channel-unavailable"` — deliberately distinct from `"no-channels"`, so a missing provider never looks like a user opt-out.
+
+## Upgrading
+
+A later version may add a column. How you pick it up depends on how you created the tables:
+
+| you bootstrapped with | to upgrade |
+| --- | --- |
+| `createSchema()` + drizzle-kit | `drizzle-kit` diffs it for you — nothing to do here |
+| `renderPostgresDdl()` | `planPostgresMigration()` — see below |
+| `createMongoIndexes()` | rerun it; `createIndex` is idempotent and additive |
+
+**`renderPostgresDdl` cannot upgrade you.** It emits `CREATE TABLE IF NOT EXISTS`, which is correct exactly once and a silent no-op afterwards. Rerunning it on an existing database does nothing at all.
+
+```ts
+import { INTROSPECT_SQL, planPostgresMigration, coreSchema } from "easy-ping/schema";
+
+const plan = await planPostgresMigration(
+  async () =>
+    (await sql.unsafe(INTROSPECT_SQL)).map((row) => ({
+      table: row.table_name,
+      column: row.column_name,
+      type: row.data_type,
+      nullable: row.is_nullable === "YES",
+    })),
+  coreSchema,
+);
+
+for (const statement of plan.statements) await sql.unsafe(statement);
+if (plan.unsupported.length) console.warn(plan.unsupported);
+```
+
+**Additive only, deliberately.** It adds missing columns and indexes, and creates tables that do not exist. It never drops a column, never changes a type, and never touches a column it did not declare — those land in `unsupported` as a message for a human, because they are destructive and context-dependent.
+
+One behaviour worth knowing: a **required** column with no default is added **nullable**, because `NOT NULL` would abort against existing rows. That is reported in `unsupported`; backfill it and `SET NOT NULL` yourself.
+
+Run the plugins' schemas the same way — `push({...}).schema`, `preferences().schema`.
+
+---
+
+## When something fails
+
+Delivery is at-least-once with five attempts and backoff, which means failures are quiet by design. To see them:
+
+```ts
+const failed = await notify.getFailedDeliveries({ since: new Date(Date.now() - 86_400_000) });
+// [{ id, notificationId, channel, attempts, lastError, updatedAt, ... }]
+```
+
+Defaults to the last 24 hours, capped at 1000 rows. Wire it to an admin page or an alert — otherwise the retry machinery is a black box, and a revoked API key looks exactly like nothing happening.
+
+`notify.healthCheck()` reports the delivery mode and warns when a mode needs a cron you have not mounted.
+
+---
+
+## Security notes
+
+- **`session.getUserId` is mandatory.** There is no default and no dev bypass — an insecure default ships, a startup crash doesn't. Returning `null` yields 401; *throwing* yields 500, because a broken session store and an absent session are different bugs.
+- **Every query is scoped server-side.** No route accepts a user id from the client. Marking someone else's notification read returns 404, not 403 — a 403 confirms the row exists.
+- **`cron.secret` is required** for modes that rely on the sweep. Unauthenticated, that endpoint is a free flush-everything trigger against your email provider. Compared in constant time. Plugin machine routes (`/push/prune`, `/digests/cron`) accept it too unless you set `machineSecret`, which keeps the scheduler's credential to `/cron` alone. One call drains at most `cron.maxSweeps` sweeps (default 50).
+- **Plugins never see the secret.** They get `ctx.sign()`, which mints tokens only for the purposes their own signed routes declare; keys are derived per purpose with HKDF, so an unsubscribe key signs nothing else. `notify.listRoutes()` shows every mounted route with its auth scope, and a `custom`-scoped route is named in a startup warning with its justification.
+- **Secrets must be at least 16 characters** and not a placeholder; startup throws otherwise. A short HMAC key makes every unsubscribe link forgeable offline.
+- **CSRF.** Every POST must be `application/json` (415 otherwise) and, when the browser sends an `Origin`, it must match the request host or an entry in `trustedOrigins` (403 otherwise). This holds even if your session cookie is `SameSite=None`. Set `trustedOrigins: ["https://app.example.com", "*.example.com"]` when the API lives on a different origin from the page.
+- **Push endpoints are validated at registration.** Public https hosts only, well-formed keys, one owner per endpoint for life (409 if another account registered it), at most `maxDevicesPerUser` rows per user. Pin `allowedEndpointHosts` to the push services you expect if you want the SSRF surface closed entirely.
+- **Email templates are sent as-is.** Run every payload field a user could have typed through `escapeHtml`, or use a templating library that escapes by default. The quickstart shows the pattern.
+- **In-app payloads are served to the browser verbatim.** Never put anything in `payload` the recipient shouldn't read, and never render it with `innerHTML`.
+- **Request bodies are capped at 64 KiB** (`maxBodyBytes`), responses carry `Cache-Control: private, no-store`, and a thrown adapter error is a logged 500 rather than a stack trace or a crashed process.
+- **Rate limiting.** `rateLimit: { max, windowMs }` is an in-process fixed-window limiter keyed by the client address from `cf-connecting-ip` / `x-real-ip` / `x-forwarded-for` (or your own `key`), applied to every route including `/cron` and `/unsubscribe`. It is per process, not global: enough to blunt secret guessing and refresh storms, not a quota. `onRequest` runs before it if you have a shared limiter of your own. Each browser holds one `GET /events` stream and refreshes the feed on every `changed`, so size limits with that in mind.
+- **Unsubscribe tokens** travel in the URL, so they will appear in access logs. They are valid for 30 days by default, capped at 90. A token is refused if the user changed that preference after it was issued, so an old link cannot undo a newer decision; clicking the same link twice is still a 200. `last_error` stores provider messages with email addresses redacted.
+
+---
+
+## Status
+
+| | |
+| --- | --- |
+| ✅ Core `send()` pipeline, hooks, dedupe | |
+| ✅ Postgres through any driver — no ORM needed | `pg`, `postgres.js`, Kysely, Neon… |
+| ✅ Postgres via Drizzle, for those already on it | same conformance suite |
+| ✅ MongoDB | same conformance suite |
+| ✅ MySQL 8 / MariaDB | `SKIP LOCKED` with a transaction, lock-free `UPDATE` without |
+| ✅ SQLite | `node:sqlite` or better-sqlite3; one writer, so the claim is one `UPDATE` |
+| ✅ Delivery runner, all four modes, retry + backoff | |
+| ✅ Resend provider | |
+| ✅ Route handler, session scoping, cron | |
+| ✅ React client, optimistic updates, one event stream per browser with polling fallback | `GET /events`, `navigator.locks` leader, `BroadcastChannel` mirror |
+| ✅ wake-ups: worker woken by `send()`, LISTEN/NOTIFY and change-stream signals, request-driven sweep | `signals`, `delivery.sweepOnRequest` |
+| ✅ preferences plugin + headless `usePreferences` | the wedge |
+| ✅ digests plugin, timezone-aware | |
+| ✅ push plugin + web-push provider | VAPID + RFC 8291, no node:crypto |
+| ✅ push verified against a live push service | Mozilla autopush, plus a cross-check against `http_ece` |
+| ✅ scoped plugin storage, so plugins own their tables | |
+| ✅ additive schema migrations for the raw-SQL path | `planPostgresMigration()`; MySQL and SQLite are bootstrap-only for now |
+| ✅ failed deliveries reachable from the instance | `notify.getFailedDeliveries()` |
+| ⬜ batching | |
+| ⬜ Prisma adapter, Vue / Svelte bindings | Kysely already works through `postgresAdapter` |
+
+---
+
+## Writing an adapter
+
+The one operation with no equivalent in other libraries is atomic claiming — without it, two concurrent sweeps send the same email twice. Verify yours:
+
+```ts
+import { adapterConformanceCases } from "easy-ping/testing";
+
+for (const testCase of adapterConformanceCases) {
+  it(testCase.name, () => testCase.run({ adapter, reset, setAttempts, lockRow }));
+}
+```
+
+Fifteen cases, run against six backends in this repo (two Postgres paths, MongoDB, two MySQL paths, SQLite). The one that matters asserts a row locked by another transaction is *skipped*, not waited on; it is tagged `requires: "rowLock"`, and a store whose claim is a single atomic update filters it out rather than faking it.
+
+Declare your dialect on the adapter so the plugin store writes what your driver expects:
+
+```ts
+naming: "snake_case" | "preserve"   // columns, or the declared field names
+serializesJson: boolean             // json as a string, or natively
+```
+
+---
+
+## Development
+
+```bash
+pnpm install
+docker compose up -d     # Postgres on :54329, MongoDB on :27019, MySQL on :33069
+pnpm test
+```
+
+Mongo runs as a single-node replica set, because that is the only way it offers transactions. SQLite needs nothing running: the suite uses Node's own `node:sqlite` in memory.
+
+Database tests skip locally when a database is unreachable, and **fail** in CI — a green build that ran none of them is worse than a red one.
+
+The push crypto is checked two ways. `web-push-reference.test.ts` decrypts our output with `http_ece` — the library `web-push` npm uses — because a decryptor written from the same RFC would share any misreading and agree with itself. `web-push-live.test.ts` then sends through Mozilla's production push service for real; it is opt-in so CI never goes red because someone else's service is having a bad afternoon:
+
+```bash
+EASY_PING_LIVE_PUSH=1 pnpm --filter easy-ping test web-push-live
+```
+
+The Resend provider is checked against Resend's real API too: the rejection paths need no credentials — a bogus key coming back as a structured 401 rather than a 400 is what proves the request shape is right. The delivery leg needs your own key:
+
+```bash
+RESEND_API_KEY=re_... RESEND_FROM="Acme <hi@acme.dev>"   pnpm --filter easy-ping test resend-live
+```
+
+## Releasing
+
+Every release is automatic. Open a PR with a changeset:
+
+```bash
+pnpm changeset          # describe the change, pick patch/minor/major
+```
+
+On merge to `main`, the Release workflow opens a version PR. Merging *that* publishes to npm via
+[trusted publishing](https://docs.npmjs.com/trusted-publishers/), tags the commit and opens a
+GitHub Release from the changelog. No npm token is stored anywhere; the workflow mints a
+short-lived OIDC token instead.
+
+## License
+
+MIT