@devmonks/notify 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dev Monks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @devmonks/notify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generic notifications for any fetch + WebCrypto runtime (Node 20+, Bun, Workers, Deno). Two steps: **plan** (pure, decides who gets what on which channel) then **send** (one delivery through a channel adapter, one attempt). The app decides when `send` runs (inline, `waitUntil`, a queue) and whether to retry. The core has no database, no queue, no env vars and no dependencies.
+
+| Entry | What | Needs |
+| --- | --- | --- |
+| `@devmonks/notify` | notifier, FCM push, in-app, quiet hours | nothing |
+| `@devmonks/notify/email` | Resend adapter, React Email layout and templates | `react`, `react-dom`, `@react-email/components`, `@react-email/render` |
+| `@devmonks/notify/drizzle` | Postgres tables and a store | `drizzle-orm` |
+
+The extra entries are optional peer dependencies: install them only if you import that entry. `/email` contains `.tsx`, so it needs `"jsx": "react-jsx"` in your tsconfig.
+
+## Use it in a new project (push only)
+
+1. `bun add @devmonks/notify` (or npm/pnpm). It ships compiled ESM with types and needs Node 20+ (or Bun, Workers, Deno).
+2. In Firebase console: Project settings, Service accounts, Generate new private key. Pass `project_id`, `client_email` and `private_key` from that JSON to `fcmPush` (from your own config; the package reads no env vars).
+3. Send and classify:
+
+```ts
+import { createNotifier, defineNotification, fcmPush } from '@devmonks/notify';
+
+const priceAlert = defineNotification<{ symbol: string; price: string; alertId: string }>({
+  type: 'alert.price',
+  category: 'alerts', // the preference key; use the type name for per-type switches
+  channels: ['push'],
+  // transactional: true -> always send: ignores preferences and quiet hours
+  render: (d) => ({
+    title: `${d.symbol} hit ${d.price}`,
+    body: 'Tap to open the alert.',
+    url: `/alerts/${d.alertId}`, // sent as data.url for tap navigation
+    data: { alertId: d.alertId },
+    push: { badge: 1, collapseKey: `alert-${d.alertId}` },
+  }),
+});
+
+const notifier = createNotifier({
+  channels: [fcmPush({ projectId, clientEmail, privateKey, defaults: { channelId: 'alerts' } })],
+  types: [priceAlert],
+});
+
+// recipient comes from your own tables
+const recipient = { id: user.id, locale: 'en', timeZone: 'UTC', devices: [{ id: device.id, token: device.fcmToken }], prefs: {} };
+const deliveries = notifier.plan('alert.price', recipient, data, { dedupeKey: alertEventId });
+
+for (const d of deliveries) {
+  // d.idempotencyKey is stable for the same event + recipient + channel + token: use it as your queue job id
+  const r = await notifier.send(d); // never throws
+  if (r.ok) continue;
+  if (r.deadAddress) await deleteDevice(d.deviceId); // token is gone for good
+  else if (r.retryable) throw new Error(r.error);    // let your queue retry (429, 5xx, network)
+  // else: permanent failure (bad payload, wrong credentials): log r.error, do not retry
+}
+```
+
+`Delivery` is plain JSON, so you can enqueue it and call `notifier.send(d)` in the worker.
+
+## Plan rules
+
+- `prefs[category][channel] === false` switches a channel off; anything else is on.
+- Preferences are per category. Give each type its own category for per-type switches.
+- `transactional` types ignore prefs and quiet hours.
+- Quiet hours (`{ from: 'HH:MM', to: 'HH:MM' }`, recipient time zone, may cross midnight) drop push and sms; in-app and email stay.
+- Push fans out one delivery per `recipient.devices[]` entry (`delivery.deviceId` is set, `delivery.to` is the token).
+- Channels with no address (no email, no devices) or no registered adapter are skipped.
+- `idempotencyKey = hash(type, recipient.id, channel, to, dedupeKey)`. Pass an event id as `dedupeKey` for anything repeatable; omitting it means "once ever".
+
+## Adapters
+
+| Channel | Adapters |
+| --- | --- |
+| push | `fcmPush({ projectId, clientEmail, privateKey, defaults?, fetch? })` FCM HTTP v1 (iOS through FCM's apns block), RS256 JWT via WebCrypto, access token cached. `logPush(logger)` |
+| inApp | `inApp(write)` where `write(recipientId, content, ctx)` is yours |
+| sms | `logSms(logger)` only (implement `Channel` for a provider) |
+| email (`/email`) | `resendEmail({ apiKey, from, brand?, linkBase?, fetch? })`, `logEmail(logger)` |
+
+A channel is `{ name, send(to, content, ctx) }`; write your own for any other provider.
+
+### Push options
+
+`PushOptions` go in `fcmPush({ defaults })` for every message and in `content.push` per message (per field, the message wins).
+
+| Option | Android | iOS (apns) |
+| --- | --- | --- |
+| `channelId` | `notification.channel_id` (create the channel in the app; high importance = heads-up banner) | |
+| `priority` `'high'` (default) / `'normal'` | `priority` HIGH / NORMAL | `apns-priority` 10 / 5 |
+| `badge` | `notification.notification_count` | `aps.badge` |
+| `sound` | `notification.sound` (below Android 8) | `aps.sound`, "default" when unset |
+| `threadId` | `notification.tag` | `aps.thread-id` |
+| `ttlSeconds` | `ttl` | `apns-expiration` (web: `TTL` header) |
+| `collapseKey` | `collapse_key` | `apns-collapse-id` |
+| `dataOnly` | no `notification`; `title` and `body` are added to `data` | background push (`content-available`) |
+| `raw: { android, apns, webpush }` | deep-merged over the generated message, for any other FCM field | |
+
+`content.data` is sent as FCM `data` (strings only) with `content.url` added as `data.url`.
+
+Results: `{ ok: true, providerId? }` or `{ ok: false, retryable, error, deadAddress? }`. `deadAddress` is set for UNREGISTERED and for INVALID_ARGUMENT that names the token. 401 (except THIRD_PARTY_AUTH_ERROR), 429, 5xx, network errors and UNAVAILABLE / INTERNAL / QUOTA_EXCEEDED are `retryable`. Everything else is permanent. Resend: 429, 5xx and network errors are `retryable`.
+
+## Email (optional, `@devmonks/notify/email`)
+
+Uses React Email. With no `content.email.template`, `simpleEmail({ heading, body, code?, button? })` is built from `title`, `body` and `url`. Custom templates are `(props) => ReactElement`; the adapter passes `brand` in with your `props`. Wrap them in `BaseLayout` (brand slot: `name`, `accent`, `logoUrl`, `footer`, `supportEmail`). `renderEmail(el)` returns `{ html, text }`.
+
+## Using with Drizzle (optional, `@devmonks/notify/drizzle`)
+
+The core never imports this. It ships the tables and a store so each app does not rewrite them. Table names are fixed (`notification`, `notify_device`, `notification_pref`, `notification_settings`, `notification_delivery`). The user id columns take the type of your `users.id` (`uuid` or `text`), so the foreign keys line up. If your schema needs something else, skip this entry and write your own store; `store.ts` shows what the notifier needs (a `Recipient` to plan with, a unique idempotency key, device cleanup from the send result).
+
+```ts
+// schema.ts
+import { notifyTables } from '@devmonks/notify/drizzle';
+export const { notifications, devices, notificationPrefs, notificationSettings, notificationDeliveries } =
+  notifyTables({ users }); // your users table, for the foreign keys
+// then run your own `drizzle-kit generate`
+
+// runtime
+import { drizzleStore } from '@devmonks/notify/drizzle';
+const store = drizzleStore(db, { notifications, devices, notificationPrefs, notificationSettings, notificationDeliveries }, {
+  getUser: async (id) => ({ email, locale, timeZone }),       // email etc. live in your tables
+  defaultPrefs: { reads: { email: false } },                  // optional
+  devices: { pruneInactiveAfterDays: null },                  // default null = never prune
+});
+```
+
+Store methods: `loadRecipient`, `writeInbox` (the inApp write), `recordDelivery` (false if the idempotency key exists: do not send), `finishDelivery`, `touchDevice` (upsert by device id; a token seen under another device id moves), `handleDeviceResult` (device cleanup from a send result) and `pruneDevices`.
+
+Devices: one row per install (`id` is stable, the token may rotate). A dead address (`deadAddress`) deletes the device at once; any other permanent failure adds a strike and the device is deleted at 3; a success resets the count; retryable failures change nothing. `pruneDevices()` removes devices unseen for `pruneInactiveAfterDays` and does nothing while that is null.
+
+## Tests
+
+`bun run test` covers the plan rules, the FCM message mapping, the Resend/FCM error mapping with mocked fetch, and that the core entry imports no package.
+
+## Release
+
+1. Bump `version` in `package.json` and commit.
+2. `git tag v<version> && git push origin main --tags`.
+
+The `Release` workflow runs typecheck, tests and the build (`prepublishOnly`), then publishes to npm through trusted publishing, with provenance. No npm token or 2FA code is needed.
+
+## Licence
+
+MIT

package/dist/adapters/push.d.ts

@@ -0,0 +1,19 @@
+import type { Channel, Logger, PushOptions } from '../types.js';
+export interface FcmOptions {
+    projectId: string;
+    clientEmail: string;
+    /** PKCS#8 PEM from the service-account JSON. Literal "\n" sequences (env vars) are accepted. */
+    privateKey: string;
+    /** Options for every message, e.g. `{ channelId: 'alerts' }`. `content.push` overrides them per message. */
+    defaults?: PushOptions;
+    /** Injected for tests; defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Push through FCM HTTP v1 (iOS goes through FCM's apns block). One attempt per call: the result says
+ * whether a retry may work (`retryable`) or the token is dead (`deadAddress`); retrying is the caller's job.
+ * The access token is cached until shortly before it expires. Needs only fetch and WebCrypto.
+ */
+export declare function fcmPush({ projectId, clientEmail, privateKey, defaults, fetch: f }: FcmOptions): Channel;
+/** Dev: prints the push instead of sending. */
+export declare function logPush(logger: Logger): Channel;

package/dist/adapters/push.js

@@ -0,0 +1,168 @@
+import { errorMessage, retryableStatus, tryJson } from '../util.js';
+const SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const b64url = (data) => {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+async function importKey(pem) {
+    const body = pem
+        .replace(/\\n/g, '\n')
+        .replace(/-----(BEGIN|END) PRIVATE KEY-----/g, '')
+        .replace(/\s+/g, '');
+    const der = Uint8Array.from(atob(body), (c) => c.charCodeAt(0));
+    return crypto.subtle.importKey('pkcs8', der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+}
+/** Signed service-account JWT (RS256) for the OAuth2 jwt-bearer grant. */
+async function signServiceAccountJwt(clientEmail, privateKey) {
+    const iat = Math.floor(Date.now() / 1000);
+    const header = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+    const claims = b64url(JSON.stringify({ iss: clientEmail, scope: SCOPE, aud: TOKEN_URL, iat, exp: iat + 3600 }));
+    const key = await importKey(privateKey);
+    const sig = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, new TextEncoder().encode(`${header}.${claims}`));
+    return `${header}.${claims}.${b64url(sig)}`;
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Drops undefined values and the objects they leave empty, so optional fields can be written plainly. */
+function prune(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        const kept = isObject(v) ? prune(v) : v;
+        if (kept !== undefined)
+            out[k] = kept;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function deepMerge(base, over) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over)) {
+        const b = out[k];
+        out[k] = isObject(b) && isObject(v) ? deepMerge(b, v) : v;
+    }
+    return out;
+}
+/** The FCM v1 `Message` for one token. */
+function fcmMessage(token, content, o) {
+    const { dataOnly = false, ttlSeconds: ttl } = o;
+    const high = o.priority !== 'normal';
+    const message = prune({
+        token,
+        notification: dataOnly ? undefined : { title: content.title, body: content.body },
+        data: { ...(dataOnly ? { title: content.title, body: content.body } : {}), ...content.data, ...(content.url ? { url: content.url } : {}) },
+        android: {
+            priority: high ? 'HIGH' : 'NORMAL',
+            ttl: ttl === undefined ? undefined : `${ttl}s`,
+            collapse_key: o.collapseKey,
+            notification: dataOnly ? undefined : { channel_id: o.channelId, sound: o.sound, tag: o.threadId, notification_count: o.badge },
+        },
+        apns: {
+            headers: {
+                'apns-push-type': dataOnly ? 'background' : undefined,
+                // Background pushes must be 5; 10 is the APNs default for alerts.
+                'apns-priority': dataOnly || !high ? '5' : undefined,
+                'apns-expiration': ttl === undefined ? undefined : String(ttl === 0 ? 0 : Math.floor(Date.now() / 1000) + ttl),
+                'apns-collapse-id': o.collapseKey,
+            },
+            payload: {
+                aps: dataOnly
+                    ? { 'content-available': 1, badge: o.badge }
+                    : { badge: o.badge, sound: o.sound ?? 'default', 'thread-id': o.threadId },
+            },
+        },
+        webpush: { headers: { TTL: ttl === undefined ? undefined : String(ttl) } },
+    });
+    return o.raw ? deepMerge(message, o.raw) : message;
+}
+/**
+ * Push through FCM HTTP v1 (iOS goes through FCM's apns block). One attempt per call: the result says
+ * whether a retry may work (`retryable`) or the token is dead (`deadAddress`); retrying is the caller's job.
+ * The access token is cached until shortly before it expires. Needs only fetch and WebCrypto.
+ */
+export function fcmPush({ projectId, clientEmail, privateKey, defaults, fetch: f = fetch }) {
+    let cached = null;
+    let refreshing = null;
+    /** Concurrent sends share one refresh. */
+    function accessToken() {
+        if (cached && cached.expiresAt - 60_000 > Date.now())
+            return Promise.resolve(cached.token);
+        return (refreshing ??= fetchAccessToken().finally(() => (refreshing = null)));
+    }
+    async function fetchAccessToken() {
+        const assertion = await signServiceAccountJwt(clientEmail, privateKey);
+        const res = await f(TOKEN_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion }).toString(),
+        });
+        if (!res.ok)
+            throw Object.assign(new Error(`oauth ${res.status}: ${(await res.text()).slice(0, 200)}`), { status: res.status });
+        const j = (await res.json());
+        cached = { token: j.access_token, expiresAt: Date.now() + (j.expires_in ?? 3600) * 1000 };
+        return j.access_token;
+    }
+    return {
+        name: 'push',
+        async send(token, content) {
+            let bearer;
+            try {
+                bearer = await accessToken();
+            }
+            catch (e) {
+                const status = e.status;
+                // A rejected service account is a config problem, not worth hammering; network/5xx is.
+                return { ok: false, retryable: status === undefined || retryableStatus(status), error: errorMessage(e) };
+            }
+            let res;
+            try {
+                res = await f(`https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${bearer}`, 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ message: fcmMessage(token, content, { ...defaults, ...content.push }) }),
+                });
+            }
+            catch (e) {
+                return { ok: false, retryable: true, error: `network: ${errorMessage(e)}` };
+            }
+            if (res.ok) {
+                const j = (await res.json().catch(() => ({})));
+                return j.name ? { ok: true, providerId: j.name } : { ok: true };
+            }
+            // The access token was rejected: fetch a new one on the retry (unless another send already did).
+            if (res.status === 401 && cached?.token === bearer)
+                cached = null;
+            return fcmFailure(res.status, await res.text().catch(() => ''));
+        },
+    };
+}
+/**
+ * Dead token: UNREGISTERED, or INVALID_ARGUMENT that names the token. FCM also answers INVALID_ARGUMENT
+ * for a bad payload (TTL, data key, size); that is permanent but must not delete the device.
+ * Retryable: 401 (expired access token; not THIRD_PARTY_AUTH_ERROR, a missing APNs key), 429, 5xx and
+ * UNAVAILABLE / INTERNAL / QUOTA_EXCEEDED.
+ */
+function fcmFailure(status, raw) {
+    const err = tryJson(raw)?.error;
+    const details = err?.details ?? [];
+    const code = details.find((d) => d.errorCode)?.errorCode ?? err?.status ?? '';
+    const message = err?.message ?? raw.slice(0, 300);
+    const badToken = details.some((d) => d.fieldViolations?.some((v) => v.field === 'message.token'));
+    const error = `fcm ${status} ${code}: ${message}`.trim();
+    if (code === 'UNREGISTERED' || (code === 'INVALID_ARGUMENT' && (badToken || /registration token/i.test(message)))) {
+        return { ok: false, retryable: false, error, deadAddress: true };
+    }
+    const retryable = (status === 401 && code !== 'THIRD_PARTY_AUTH_ERROR') || retryableStatus(status) || ['UNAVAILABLE', 'INTERNAL', 'QUOTA_EXCEEDED'].includes(code);
+    return { ok: false, retryable, error };
+}
+/** Dev: prints the push instead of sending. */
+export function logPush(logger) {
+    return {
+        name: 'push',
+        async send(token, content) {
+            logger.info(`[push] token=${token.slice(0, 12)}… ${JSON.stringify({ title: content.title, body: content.body, url: content.url, data: content.data })}`);
+            return { ok: true };
+        },
+    };
+}

package/dist/adapters/sms-inapp.d.ts

@@ -0,0 +1,5 @@
+import type { Channel, Content, Logger, SendContext } from '../types.js';
+/** Dev only: SMS has no provider yet. Implement `Channel` to add one. */
+export declare function logSms(logger: Logger): Channel;
+/** In-app inbox: the app supplies the write (usually a DB insert). The address is the recipient id. */
+export declare function inApp(write: (recipientId: string, content: Content, ctx: SendContext) => Promise<void>): Channel;

package/dist/adapters/sms-inapp.js

@@ -0,0 +1,26 @@
+import { errorMessage } from '../util.js';
+/** Dev only: SMS has no provider yet. Implement `Channel` to add one. */
+export function logSms(logger) {
+    return {
+        name: 'sms',
+        async send(to, content) {
+            logger.info(`[sms] to=${to} ${content.sms?.text ?? `${content.title}: ${content.body}`}`);
+            return { ok: true };
+        },
+    };
+}
+/** In-app inbox: the app supplies the write (usually a DB insert). The address is the recipient id. */
+export function inApp(write) {
+    return {
+        name: 'inApp',
+        async send(recipientId, content, ctx) {
+            try {
+                await write(recipientId, content, ctx ?? {});
+                return { ok: true };
+            }
+            catch (e) {
+                return { ok: false, retryable: true, error: errorMessage(e) };
+            }
+        },
+    };
+}

package/dist/drizzle/index.d.ts

@@ -0,0 +1,2 @@
+export { notifyTables, type NotifyTables } from './tables';
+export { drizzleStore, MAX_DEVICE_FAILURES, type DrizzleStore, type DrizzleStoreOptions, type UserInfo } from './store';

package/dist/drizzle/index.js

@@ -0,0 +1,2 @@
+export { notifyTables } from './tables';
+export { drizzleStore, MAX_DEVICE_FAILURES } from './store';

package/dist/drizzle/store.d.ts

@@ -0,0 +1,75 @@
+import type { PgDatabase } from 'drizzle-orm/pg-core';
+import type { Content, Delivery, Recipient, SendResult } from '../types';
+import type { NotifyTables } from './tables';
+/** Devices are deleted after this many consecutive permanent failures. */
+export declare const MAX_DEVICE_FAILURES = 3;
+export interface UserInfo {
+    email?: string | null;
+    locale?: string | null;
+    timeZone?: string | null;
+}
+export interface DrizzleStoreOptions {
+    /** The app's user lookup: email, locale and time zone live in the app's own tables. */
+    getUser(id: string): Promise<UserInfo | null>;
+    /** Optional batch form of `getUser` for `loadRecipients`; without it, `getUser` runs per id. */
+    getUsers?(ids: readonly string[]): Promise<ReadonlyMap<string, UserInfo>>;
+    /** Preference defaults when a user has no row, e.g. `{ reads: { email: false } }`. */
+    defaultPrefs?: Record<string, Partial<Record<string, boolean>>>;
+    devices?: {
+        /** Delete devices not seen for this many days when `pruneDevices()` runs. null/undefined = never prune (default). */
+        pruneInactiveAfterDays?: number | null;
+    };
+}
+type AnyPgDb = PgDatabase<any, any, any>;
+export declare function drizzleStore(db: AnyPgDb, tables: NotifyTables, opts: DrizzleStoreOptions): {
+    /** Loads everything `notifier.plan` needs. Null when the app does not know the user. */
+    loadRecipient(userId: string): Promise<Recipient | null>;
+    /**
+     * `loadRecipient` for many users in four queries (one with `getUsers`), for fan-out batches.
+     * Users the app does not know are left out of the map.
+     */
+    loadRecipients(userIds: readonly string[]): Promise<Map<string, Recipient>>;
+    /**
+     * The inApp channel's write. With a `sourceId`, a second write for the same type, source and user
+     * is ignored. Returns whether a row was inserted.
+     */
+    writeInbox(recipientId: string, content: Content, meta?: {
+        type?: string;
+        sourceId?: string;
+        actorId?: string;
+    }): Promise<boolean>;
+    /** Inserts a pending delivery row. False when the idempotency key already exists (do not send again). */
+    recordDelivery(d: Delivery): Promise<boolean>;
+    finishDelivery(d: Delivery, status: "sent" | "failed" | "skipped", attempts: number, error?: string): Promise<void>;
+    /**
+     * Upserts a device by its install id. A device row that belongs to another user is only taken over
+     * when the caller also holds its current push token (same phone, new account); otherwise nothing
+     * changes and this returns false, so nobody can hijack a device id they merely know.
+     */
+    touchDevice(userId: string, deviceId: string, info: {
+        platform: string;
+        token: string;
+        appVersion?: string;
+    }): Promise<boolean>;
+    /**
+     * The device bookkeeping for one finished push delivery:
+     * success resets failures; a dead address (UNREGISTERED etc.) deletes the device;
+     * any other permanent failure counts a strike and deletes it at MAX_DEVICE_FAILURES;
+     * retryable failures change nothing. Deletes and strikes apply only while the device
+     * still holds the token that was sent to (it may have refreshed since).
+     */
+    handleDeviceResult(d: Delivery, result: SendResult): Promise<void>;
+    /**
+     * Removes devices whose `lastSeenAt` is older than [olderThanDays] (default: the
+     * `devices.pruneInactiveAfterDays` option). Null, undefined or non-positive means never prune.
+     * Returns how many were removed.
+     */
+    pruneDevices(olderThanDays?: number | null | undefined): Promise<number>;
+    /** Deletes inbox and delivery rows older than [olderThanDays]. Returns how many of each were removed. */
+    pruneHistory(olderThanDays: number): Promise<{
+        notifications: number;
+        deliveries: number;
+    }>;
+};
+export type DrizzleStore = ReturnType<typeof drizzleStore>;
+export {};

package/dist/drizzle/store.js

@@ -0,0 +1,166 @@
+import { and, eq, inArray, lt, ne, or, sql } from 'drizzle-orm';
+/** Devices are deleted after this many consecutive permanent failures. */
+export const MAX_DEVICE_FAILURES = 3;
+export function drizzleStore(db, tables, opts) {
+    const { notifications, devices, notificationPrefs, notificationSettings, notificationDeliveries } = tables;
+    return {
+        /** Loads everything `notifier.plan` needs. Null when the app does not know the user. */
+        async loadRecipient(userId) {
+            return (await this.loadRecipients([userId])).get(userId) ?? null;
+        },
+        /**
+         * `loadRecipient` for many users in four queries (one with `getUsers`), for fan-out batches.
+         * Users the app does not know are left out of the map.
+         */
+        async loadRecipients(userIds) {
+            const ids = [...new Set(userIds)];
+            const recipients = new Map();
+            if (ids.length === 0)
+                return recipients;
+            const users = opts.getUsers
+                ? await opts.getUsers(ids)
+                : new Map((await Promise.all(ids.map(async (id) => [id, await opts.getUser(id)]))).filter((e) => e[1] !== null));
+            const known = ids.filter((id) => users.has(id));
+            if (known.length === 0)
+                return recipients;
+            const [deviceRows, prefRows, settingRows] = await Promise.all([
+                db.select({ userId: devices.userId, id: devices.id, token: devices.token, platform: devices.platform }).from(devices).where(inArray(devices.userId, known)),
+                db.select().from(notificationPrefs).where(inArray(notificationPrefs.userId, known)),
+                db.select().from(notificationSettings).where(inArray(notificationSettings.userId, known)),
+            ]);
+            for (const id of known) {
+                const user = users.get(id);
+                // Null-prototype maps: category and channel are stored strings, so "__proto__" must stay a plain key.
+                const prefs = Object.create(null);
+                for (const [cat, chans] of Object.entries(opts.defaultPrefs ?? {}))
+                    prefs[cat] = Object.assign(Object.create(null), chans);
+                for (const p of prefRows)
+                    if (p.userId === id)
+                        (prefs[p.category] ??= Object.create(null))[p.channel] = p.enabled;
+                const settings = settingRows.find((row) => row.userId === id);
+                recipients.set(id, {
+                    id,
+                    locale: user.locale || 'en',
+                    timeZone: user.timeZone || 'UTC',
+                    ...(user.email ? { email: user.email } : {}),
+                    devices: deviceRows.filter((d) => d.userId === id).map(({ id: deviceId, token, platform }) => ({ id: deviceId, token, platform })),
+                    prefs,
+                    ...(settings?.quietFrom && settings.quietTo ? { quietHours: { from: settings.quietFrom, to: settings.quietTo } } : {}),
+                });
+            }
+            return recipients;
+        },
+        /**
+         * The inApp channel's write. With a `sourceId`, a second write for the same type, source and user
+         * is ignored. Returns whether a row was inserted.
+         */
+        async writeInbox(recipientId, content, meta = {}) {
+            const rows = await db
+                .insert(notifications)
+                .values({
+                id: crypto.randomUUID(),
+                userId: recipientId,
+                type: meta.type ?? 'unknown',
+                title: content.title,
+                body: content.body,
+                url: content.url ?? null,
+                data: content.data ?? {},
+                sourceId: meta.sourceId ?? null,
+                actorId: meta.actorId ?? null,
+            })
+                .onConflictDoNothing()
+                .returning({ id: notifications.id });
+            return rows.length > 0;
+        },
+        /** Inserts a pending delivery row. False when the idempotency key already exists (do not send again). */
+        async recordDelivery(d) {
+            const rows = await db
+                .insert(notificationDeliveries)
+                .values({
+                id: d.id,
+                idempotencyKey: d.idempotencyKey,
+                type: d.type,
+                userId: d.recipientId,
+                channel: d.channel,
+                deviceId: d.deviceId ?? null,
+            })
+                .onConflictDoNothing({ target: notificationDeliveries.idempotencyKey })
+                .returning({ id: notificationDeliveries.id });
+            return rows.length > 0;
+        },
+        async finishDelivery(d, status, attempts, error) {
+            await db
+                .update(notificationDeliveries)
+                .set({ status, attempts, error: error ?? null })
+                .where(eq(notificationDeliveries.id, d.id));
+        },
+        /**
+         * Upserts a device by its install id. A device row that belongs to another user is only taken over
+         * when the caller also holds its current push token (same phone, new account); otherwise nothing
+         * changes and this returns false, so nobody can hijack a device id they merely know.
+         */
+        async touchDevice(userId, deviceId, info) {
+            // A push token lives on one install: drop it from any other device row first (the app was
+            // reinstalled). Holding the token is proof enough, and the token column is unique.
+            await db.delete(devices).where(and(eq(devices.token, info.token), ne(devices.id, deviceId)));
+            const rows = await db
+                .insert(devices)
+                .values({ id: deviceId, userId, platform: info.platform, token: info.token, appVersion: info.appVersion ?? '' })
+                .onConflictDoUpdate({
+                target: devices.id,
+                set: { userId, platform: info.platform, token: info.token, appVersion: info.appVersion ?? '', lastSeenAt: new Date(), failureCount: 0 },
+                setWhere: or(eq(devices.userId, userId), eq(devices.token, info.token)),
+            })
+                .returning({ id: devices.id });
+            return rows.length > 0;
+        },
+        /**
+         * The device bookkeeping for one finished push delivery:
+         * success resets failures; a dead address (UNREGISTERED etc.) deletes the device;
+         * any other permanent failure counts a strike and deletes it at MAX_DEVICE_FAILURES;
+         * retryable failures change nothing. Deletes and strikes apply only while the device
+         * still holds the token that was sent to (it may have refreshed since).
+         */
+        async handleDeviceResult(d, result) {
+            if (!d.deviceId)
+                return;
+            const sameToken = and(eq(devices.id, d.deviceId), eq(devices.token, d.to));
+            if (result.ok) {
+                await db.update(devices).set({ failureCount: 0 }).where(and(eq(devices.id, d.deviceId), ne(devices.failureCount, 0)));
+            }
+            else if (result.deadAddress) {
+                await db.delete(devices).where(sameToken);
+            }
+            else if (!result.retryable) {
+                const [row] = await db
+                    .update(devices)
+                    .set({ failureCount: sql `${devices.failureCount} + 1` })
+                    .where(sameToken)
+                    .returning({ n: devices.failureCount });
+                if (row && row.n >= MAX_DEVICE_FAILURES)
+                    await db.delete(devices).where(eq(devices.id, d.deviceId));
+            }
+        },
+        /**
+         * Removes devices whose `lastSeenAt` is older than [olderThanDays] (default: the
+         * `devices.pruneInactiveAfterDays` option). Null, undefined or non-positive means never prune.
+         * Returns how many were removed.
+         */
+        async pruneDevices(olderThanDays = opts.devices?.pruneInactiveAfterDays) {
+            if (!olderThanDays || olderThanDays <= 0)
+                return 0;
+            const cutoff = new Date(Date.now() - olderThanDays * 86_400_000);
+            const rows = await db.delete(devices).where(lt(devices.lastSeenAt, cutoff)).returning({ id: devices.id });
+            return rows.length;
+        },
+        /** Deletes inbox and delivery rows older than [olderThanDays]. Returns how many of each were removed. */
+        async pruneHistory(olderThanDays) {
+            const cutoff = new Date(Date.now() - olderThanDays * 86_400_000);
+            const [inbox, sent] = await Promise.all([
+                db.delete(notifications).where(lt(notifications.createdAt, cutoff)).returning({ id: notifications.id }),
+                db.delete(notificationDeliveries).where(lt(notificationDeliveries.createdAt, cutoff)).returning({ id: notificationDeliveries.id }),
+            ]);
+            return { notifications: inbox.length, deliveries: sent.length };
+        },
+    };
+}