easy-ping 0.3.0 → 0.5.0

package/README.md

@@ -1,20 +1,65 @@
+<div align="center">
+
 # easy-ping
 
-**Own your notifications.** Your database, your users, no per-notification pricing.
+**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)
 
-A framework-agnostic, type-safe, self-hosted notifications library for TypeScript — in-app inbox, transactional email, and a plugin system for the rest.
+[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)
 
-> **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.
+</div>
 
 ---
 
-## Why
+```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.
 
-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.
+---
+
+## Why
 
-easy-ping runs **inside your app**, stores notifications in **your database**, and never charges per send.
+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.
 
-**Scale target:** thousands to low-millions of notifications per month. Not Slack-scale fan-out. Every "no queue required" decision below follows from that.
+|  | 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`. Realtime and batching are not built, and the Resend provider has only been exercised
+> against a stub. Minor versions may still move APIs before 1.0.
 
 ---
 
@@ -23,64 +68,42 @@ easy-ping runs **inside your app**, stores notifications in **your database**, a
 ### 1. Install
 
 ```bash
-pnpm add easy-ping drizzle-orm postgres zod
+pnpm add easy-ping pg zod
 ```
 
 ### 2. Create the tables
 
-```ts
-// db/schema.ts
-import { createSchema } from "easy-ping/adapters/drizzle";
+No ORM required. The whole database contract is one function: run a parameterised statement,
+return rows.
 
-export const { notification, notificationDelivery, notificationPreference } = createSchema();
-```
+```ts
+import { createPostgresTables, pgTransaction, postgresAdapter } from "easy-ping/adapters/postgres";
+import { Pool } from "pg";
 
-Push them with `drizzle-kit`, or generate raw SQL:
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const query = async (text, params) => (await pool.query(text, params)).rows;
 
-```ts
-import { coreSchema, renderPostgresDdl } from "easy-ping/schema";
+// 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);
 
-for (const statement of renderPostgresDdl(coreSchema)) await sql.unsafe(statement);
+export const database = postgresAdapter(query, { transaction: pgTransaction(pool) });
 ```
 
-<details>
-<summary>Without an ORM (plain pg, postgres.js, Kysely…)</summary>
+Anything that can run a statement works: `pg`, `postgres.js`, Kysely, Neon or PlanetScale's
+serverless drivers, or Prisma's `$queryRawUnsafe`.
 
-```bash
-pnpm add easy-ping pg zod
-```
+<details>
+<summary>Already on Drizzle</summary>
 
 ```ts
-import { postgresAdapter } from "easy-ping/adapters/postgres";
-import { Pool } from "pg";
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+// db/schema.ts
+import { createSchema } from "easy-ping/adapters/drizzle";
 
-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();
-      }
-    },
-  },
-);
+export const { notification, notificationDelivery, notificationPreference } = createSchema();
 ```
 
-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`.
+Push it with `drizzle-kit`, then `drizzleAdapter(db)` in place of `postgresAdapter`.
 
 </details>
 
@@ -98,34 +121,91 @@ 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.
+// 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.
-const database = mongoAdapter(db, { client });
+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 } from "easy-ping";
-import { drizzleAdapter } from "easy-ping/adapters/drizzle";
+import { defineNotification, easyPing, escapeHtml } from "easy-ping";
 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";
+import { database, pool } from "./db";   // from step 2
 
 export const notify = easyPing({
-  database: drizzleAdapter(db),
+  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! },
 
@@ -135,14 +215,19 @@ export const notify = easyPing({
       (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) => ({
+  // 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 },
@@ -157,7 +242,9 @@ export const notify = easyPing({
       channels: ["inApp", "email"],
       email: {
         subject: (p) => `${p.authorName} replied to you`,
-        template: (p) => `<p>${p.authorName} replied. <a href="/c/${p.commentId}">View</a></p>`,
+        // 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>`,
       },
     }),
   },
@@ -167,7 +254,9 @@ export const notify = easyPing({
 ### 4. Mount the endpoints
 
 ```ts
-// app/api/notifications/[...notify]/route.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;
@@ -315,8 +404,16 @@ Defaults to the last 24 hours, capped at 1000 rows. Wire it to an admin page or
 
 - **`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.
-- **In-app payloads are served to the browser verbatim.** Never put anything in `payload` the recipient shouldn't read.
+- **`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.
 
 ---
 
@@ -328,6 +425,8 @@ Defaults to the last 24 hours, capped at 1000 rows. Wire it to an admin page or
 | ✅ 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 | |
@@ -337,10 +436,10 @@ Defaults to the last 24 hours, capped at 1000 rows. Wire it to an admin page or
 | ✅ 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()` |
+| ✅ 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()` |
 | ⬜ realtime, batching | |
-| ⬜ Prisma / Kysely adapters, Vue / Svelte bindings | |
+| ⬜ Prisma adapter, Vue / Svelte bindings | Kysely already works through `postgresAdapter` |
 
 ---
 
@@ -356,7 +455,7 @@ for (const testCase of adapterConformanceCases) {
 }
 ```
 
-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.
+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:
 
@@ -371,11 +470,11 @@ serializesJson: boolean             // json as a string, or natively
 
 ```bash
 pnpm install
-docker compose up -d     # Postgres on :54329, MongoDB on :27019
+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.
+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.
 
@@ -393,23 +492,16 @@ RESEND_API_KEY=re_... RESEND_FROM="Acme <hi@acme.dev>"   pnpm --filter easy-ping
 
 ## 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:
+Every release is automatic. Open a PR with a changeset:
 
 ```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
+pnpm changeset          # describe the change, pick patch/minor/major
 ```
 
-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.
+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
 

package/dist/adapter-B7R4rXtJ.d.cts

@@ -0,0 +1,17 @@
+type Row = Record<string, unknown>;
+type SqlResult = {
+    rows: readonly Row[];
+    /** Rows an INSERT/UPDATE/DELETE touched; drivers without RETURNING report through this. */
+    affectedRows: number;
+};
+/** The whole driver contract for the MySQL and SQLite adapters. */
+type SqlExec = (text: string, params: readonly unknown[]) => Promise<SqlResult>;
+
+type SqlAdapterOptions = {
+    /** Table-name prefix. Must match the instance's `tablePrefix`. */
+    prefix?: string;
+    /** Makes createNotifications atomic and, on MySQL, lets a claim use FOR UPDATE SKIP LOCKED. */
+    transaction?: <T>(fn: (exec: SqlExec) => Promise<T>) => Promise<T>;
+};
+
+export type { SqlAdapterOptions as S, SqlExec as a, SqlResult as b };

package/dist/adapter-B7R4rXtJ.d.ts

@@ -0,0 +1,17 @@
+type Row = Record<string, unknown>;
+type SqlResult = {
+    rows: readonly Row[];
+    /** Rows an INSERT/UPDATE/DELETE touched; drivers without RETURNING report through this. */
+    affectedRows: number;
+};
+/** The whole driver contract for the MySQL and SQLite adapters. */
+type SqlExec = (text: string, params: readonly unknown[]) => Promise<SqlResult>;
+
+type SqlAdapterOptions = {
+    /** Table-name prefix. Must match the instance's `tablePrefix`. */
+    prefix?: string;
+    /** Makes createNotifications atomic and, on MySQL, lets a claim use FOR UPDATE SKIP LOCKED. */
+    transaction?: <T>(fn: (exec: SqlExec) => Promise<T>) => Promise<T>;
+};
+
+export type { SqlAdapterOptions as S, SqlExec as a, SqlResult as b };

package/dist/{adapter-BfLe2J0t.d.cts → adapter-D3lTy-4E.d.cts}

@@ -41,11 +41,7 @@ type DeliveryRecord = {
 };
 
 type Scalar = string | number | boolean | Date | null;
-/**
- * One operator per condition. Operators are tagged objects so a bare value is
- * always an equality test; json columns therefore cannot be filtered, since an
- * object value would be ambiguous.
- */
+/** Operators are tagged objects so a bare value is always equality; json columns cannot be filtered. */
 type WhereCondition = Scalar | {
     in: readonly (string | number)[];
 } | {
@@ -70,13 +66,7 @@ type QueryOptions = {
 type UpsertOptions = {
     onConflict: readonly string[];
 };
-/**
- * Table access for plugins, scoped to the tables that plugin declared.
- *
- * Plugins could always declare tables via schema() but had no way to read
- * them, so preferences had to bolt its queries onto the core adapter. That
- * does not generalise to digests or push.
- */
+/** Table access for plugins, scoped to the tables the plugin declared. */
 type PluginStore = {
     find<T = Record<string, unknown>>(table: string, where?: WhereClause, options?: QueryOptions): Promise<T[]>;
     insert(table: string, rows: readonly Record<string, unknown>[]): Promise<number>;
@@ -138,12 +128,7 @@ type DeliveryOutcome = {
     error: string;
     retryable: boolean;
 }
-/**
- * Nothing to do, and nothing wrong. A channel whose preconditions are
- * simply absent — push with no registered device, say — must not land in
- * `getFailedDeliveries`, or the one view meant to surface real breakage
- * fills up with people who never opted in. Terminal: never retried.
- */
+/** Nothing to do and nothing wrong (push with no device, say). Terminal; kept out of getFailedDeliveries. */
  | {
     result: "skipped";
     reason: string;
@@ -167,16 +152,9 @@ type FeedPage = {
 };
 type DatabaseAdapter = {
     readonly name: string;
-    /**
-     * How the adapter names stored fields. SQL adapters use snake_case columns;
-     * document stores keep the declared camelCase. The plugin store translates
-     * accordingly rather than assuming one of them.
-     */
+    /** snake_case columns (SQL) or the declared camelCase (document stores); the store translates. */
     readonly naming?: "snake_case" | "preserve";
-    /**
-     * True when json values must reach the driver as strings. postgres-js cannot
-     * bind a plain object; Mongo stores one natively.
-     */
+    /** True when json must reach the driver as a string. */
     readonly serializesJson?: boolean;
     /** One transaction. A duplicate (userId, dedupeKey) is reported, not thrown. */
     createNotifications(rows: readonly InsertNotification[]): Promise<{
@@ -196,11 +174,7 @@ type DatabaseAdapter = {
         since: Date;
         limit: number;
     }): Promise<readonly DeliveryRecord[]>;
-    /**
-     * Generic table access for plugin-declared tables. Reached only through a
-     * PluginStore, which validates the table and every column against the
-     * plugin's own schema() before anything gets here.
-     */
+    /** Plugin-table access. Reached only through a PluginStore, which validated table and columns. */
     queryTable(table: string, where: WhereClause, options: QueryOptions): Promise<Record<string, unknown>[]>;
     insertRows(table: string, rows: readonly Record<string, unknown>[], onConflict?: readonly string[]): Promise<number>;
     updateRows(table: string, where: WhereClause, set: Record<string, unknown>): Promise<number>;

package/dist/{adapter-BfLe2J0t.d.ts → adapter-D3lTy-4E.d.ts}

@@ -41,11 +41,7 @@ type DeliveryRecord = {
 };
 
 type Scalar = string | number | boolean | Date | null;
-/**
- * One operator per condition. Operators are tagged objects so a bare value is
- * always an equality test; json columns therefore cannot be filtered, since an
- * object value would be ambiguous.
- */
+/** Operators are tagged objects so a bare value is always equality; json columns cannot be filtered. */
 type WhereCondition = Scalar | {
     in: readonly (string | number)[];
 } | {
@@ -70,13 +66,7 @@ type QueryOptions = {
 type UpsertOptions = {
     onConflict: readonly string[];
 };
-/**
- * Table access for plugins, scoped to the tables that plugin declared.
- *
- * Plugins could always declare tables via schema() but had no way to read
- * them, so preferences had to bolt its queries onto the core adapter. That
- * does not generalise to digests or push.
- */
+/** Table access for plugins, scoped to the tables the plugin declared. */
 type PluginStore = {
     find<T = Record<string, unknown>>(table: string, where?: WhereClause, options?: QueryOptions): Promise<T[]>;
     insert(table: string, rows: readonly Record<string, unknown>[]): Promise<number>;
@@ -138,12 +128,7 @@ type DeliveryOutcome = {
     error: string;
     retryable: boolean;
 }
-/**
- * Nothing to do, and nothing wrong. A channel whose preconditions are
- * simply absent — push with no registered device, say — must not land in
- * `getFailedDeliveries`, or the one view meant to surface real breakage
- * fills up with people who never opted in. Terminal: never retried.
- */
+/** Nothing to do and nothing wrong (push with no device, say). Terminal; kept out of getFailedDeliveries. */
  | {
     result: "skipped";
     reason: string;
@@ -167,16 +152,9 @@ type FeedPage = {
 };
 type DatabaseAdapter = {
     readonly name: string;
-    /**
-     * How the adapter names stored fields. SQL adapters use snake_case columns;
-     * document stores keep the declared camelCase. The plugin store translates
-     * accordingly rather than assuming one of them.
-     */
+    /** snake_case columns (SQL) or the declared camelCase (document stores); the store translates. */
     readonly naming?: "snake_case" | "preserve";
-    /**
-     * True when json values must reach the driver as strings. postgres-js cannot
-     * bind a plain object; Mongo stores one natively.
-     */
+    /** True when json must reach the driver as a string. */
     readonly serializesJson?: boolean;
     /** One transaction. A duplicate (userId, dedupeKey) is reported, not thrown. */
     createNotifications(rows: readonly InsertNotification[]): Promise<{
@@ -196,11 +174,7 @@ type DatabaseAdapter = {
         since: Date;
         limit: number;
     }): Promise<readonly DeliveryRecord[]>;
-    /**
-     * Generic table access for plugin-declared tables. Reached only through a
-     * PluginStore, which validates the table and every column against the
-     * plugin's own schema() before anything gets here.
-     */
+    /** Plugin-table access. Reached only through a PluginStore, which validated table and columns. */
     queryTable(table: string, where: WhereClause, options: QueryOptions): Promise<Record<string, unknown>[]>;
     insertRows(table: string, rows: readonly Record<string, unknown>[], onConflict?: readonly string[]): Promise<number>;
     updateRows(table: string, where: WhereClause, set: Record<string, unknown>): Promise<number>;

package/dist/adapters/drizzle.cjs

@@ -30,7 +30,7 @@ var toSnakeCase = (value) => value.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}
 
 // src/core/store.ts
 var OPERATORS = ["in", "lt", "lte", "gt", "gte", "not"];
-var isOperator = (value) => typeof value === "object" && value !== null && !(value instanceof Date) && OPERATORS.some((op) => op in value);
+var isOperator = (value) => typeof value === "object" && value !== null && !(value instanceof Date) && OPERATORS.some((op) => Object.hasOwn(value, op));
 
 // src/adapters/drizzle/adapter.ts
 function toRows(result) {
@@ -397,8 +397,7 @@ function createSchema(prefix = "") {
       pgCore.index(name("notification_feed_idx")).on(table.userId, table.createdAt.desc()),
       pgCore.index(name("notification_unseen_idx")).on(table.userId).where(drizzleOrm.sql`${table.seenAt} is null`),
       pgCore.index(name("notification_group_idx")).on(table.userId, table.groupKey),
-      // Postgres treats NULLs as distinct here, so unlimited rows may carry no
-      // dedupe key while a present one is enforced unique per user.
+      // NULLs are distinct here: unlimited rows without a dedupe key.
       pgCore.uniqueIndex(name("notification_dedupe_idx")).on(table.userId, table.dedupeKey)
     ]
   );
@@ -429,7 +428,8 @@ function createSchema(prefix = "") {
       type: pgCore.text("type").notNull(),
       channel: pgCore.text("channel").$type().notNull(),
       enabled: pgCore.boolean("enabled").notNull().default(true),
-      frequency: pgCore.text("frequency").$type().notNull().default("instant")
+      frequency: pgCore.text("frequency").$type().notNull().default("instant"),
+      updatedAt: pgCore.timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
     },
     (table) => [pgCore.primaryKey({ columns: [table.userId, table.type, table.channel] })]
   );