@12-apps/notifications 4.1.0 → 4.1.1

package/dist/server/index.d.ts

@@ -0,0 +1,905 @@
+import { N as NotificationGeneratorRegistry } from '../generators-FATT537X.js';
+import { b as NotificationRow, C as ChannelMatrix, a as ChannelRow, L as ListNotificationsResult, c as NotificationWireMessages } from '../wire-SDUtscGu.js';
+import { c as NotificationChannel, D as DeliveryStatus, f as NotificationLogger, i as NotificationTransport, d as NotificationContent, b as NotificationCategory, e as NotificationEvent, N as NotificationGenerator } from '../types-yq_o4N01.js';
+import { a as WebPushSubscriptionSource, D as DriverDeclarationBase, b as WebPushDriverDeclaration, W as WebPushSender } from '../web-push-KLY6UMRT.js';
+export { F as FetchImpl, N as NotificationProviderError, c as WEB_PUSH_DRIVERS, d as WebPushMessage, e as WebPushSubscription, f as absoluteLink, g as formatWebPush, w as webPushTransport } from '../web-push-KLY6UMRT.js';
+
+/**
+ * The database seam (12-15) — the exact, narrow slice of a Prisma-shaped
+ * client this surface reads and writes on the four models the package owns
+ * (`prisma/notifications.prisma`). Structural on purpose, never generated: a
+ * real host passes its Prisma client; the harness passes hand-written SQL, and
+ * the stores cannot tell.
+ *
+ * Every argument type below is CLOSED — the union of the shapes this package's
+ * own stores actually pass — so a non-Prisma implementation has a finite,
+ * documented surface to satisfy instead of "all of Prisma".
+ *
+ * What is NOT here: the `users` table. the origin's router read
+ * `users.email/phone` directly to answer "can this channel reach them", which
+ * is the one thing in the pipeline that belonged to the host all along — a
+ * package cannot know the shape of a host's identity table, and a host with
+ * phone VERIFICATION wants to answer the question differently. It crosses as
+ * {@link NotificationContactDirectory} instead.
+ */
+
+interface NotificationCreateData {
+    userId: string;
+    clientId: string | null;
+    type: string;
+    category: string;
+    title: string;
+    body: string;
+    link: string | null;
+    data: Record<string, unknown>;
+}
+/**
+ * One page boundary, as an explicit KEYSET rather than Prisma's positional
+ * cursor.
+ *
+ * `cursor` + `skip: 1` was the obvious translation and it is wrong in exactly
+ * one case, which the inbox reaches routinely: `skip` is an OFFSET applied
+ * AFTER the `where`, so once the anchor row stops matching — the user deleted
+ * the bottom visible row, which is the one carrying the delete button — the
+ * offset consumes the first SURVIVING row instead of the anchor and that row
+ * never appears in the list. Stated as a keyset comparison on the same order
+ * key, the anchor's own membership is irrelevant, so nothing can be skipped or
+ * repeated. It also gives the two non-Prisma implementations of this seam
+ * something they can satisfy exactly instead of approximately.
+ */
+interface NotificationPageAfter {
+    createdAt: Date;
+    id: string;
+}
+/** The inbox read filter. `deletedAt: null` is on every read, always. */
+interface NotificationWhere {
+    userId?: string;
+    id?: string | {
+        in: string[];
+    };
+    deletedAt: null;
+    readAt?: null;
+    /** The keyset half of `(createdAt, id) < (anchor.createdAt, anchor.id)`. */
+    OR?: [{
+        createdAt: {
+            lt: Date;
+        };
+    }, {
+        createdAt: Date;
+        id: {
+            lt: string;
+        };
+    }];
+}
+interface NotificationDelegate {
+    create(args: {
+        data: NotificationCreateData;
+    }): Promise<NotificationRow>;
+    /** Deliberately NOT `deletedAt`-filtered: the pager anchors on a row the
+     *  user may have just soft-deleted, and its position is still valid. */
+    findUnique(args: {
+        where: {
+            id: string;
+        };
+    }): Promise<NotificationRow | null>;
+    findMany(args: {
+        where: NotificationWhere;
+        orderBy: [{
+            createdAt: 'desc';
+        }, {
+            id: 'desc';
+        }];
+        take: number;
+    }): Promise<NotificationRow[]>;
+    count(args: {
+        where: NotificationWhere;
+    }): Promise<number>;
+    updateMany(args: {
+        where: NotificationWhere;
+        data: {
+            readAt: Date;
+        } | {
+            deletedAt: Date;
+        };
+    }): Promise<{
+        count: number;
+    }>;
+}
+interface NotificationDeliveryRow {
+    id: string;
+    notificationId: string;
+    channel: string;
+    status: string;
+    error: string | null;
+    sentAt: Date | null;
+    /** How many times a dispatcher has CLAIMED this row (the retry ceiling). */
+    attempts: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * The delivery filter, and it is deliberately small: four shapes, all of which
+ * are either a claim's precondition or the sweep's selection.
+ *
+ * `updatedAt` and never `createdAt`. The sweep's job is "this row has not moved
+ * in a while", and `created_at` cannot express that — a row the sweep re-queued
+ * one second ago still carries a `created_at` from days back, so it reads as
+ * stale again immediately and the sweep re-dispatches its own work on every
+ * tick. Every write here advances `updatedAt`, which is what makes the cutoff
+ * mean what it says.
+ */
+interface NotificationDeliveryWhere {
+    id?: string;
+    notificationId?: string;
+    status?: DeliveryStatus | {
+        in: DeliveryStatus[];
+    };
+    updatedAt?: {
+        lt: Date;
+    };
+}
+interface NotificationDeliveryDelegate {
+    createMany(args: {
+        data: {
+            notificationId: string;
+            channel: NotificationChannel;
+        }[];
+        skipDuplicates: true;
+    }): Promise<{
+        count: number;
+    }>;
+    findMany(args: {
+        where: NotificationDeliveryWhere;
+        /** Oldest-stalest first, so a bounded sweep drains a backlog in order. */
+        orderBy?: {
+            updatedAt: 'asc';
+        };
+        take?: number;
+    }): Promise<NotificationDeliveryRow[]>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: {
+            status: DeliveryStatus;
+            sentAt?: Date | null;
+            error?: string | null;
+        };
+    }): Promise<NotificationDeliveryRow>;
+    /**
+     * THE CLAIM, and the only reason this is `updateMany` rather than `update`:
+     * `where` carries the precondition ("this row is still QUEUED"), so the
+     * returned `count` answers "did I win it" — one statement, atomic in the
+     * database, and never a read the caller then validates in application code.
+     */
+    updateMany(args: {
+        where: NotificationDeliveryWhere;
+        data: {
+            status: DeliveryStatus;
+            attempts?: {
+                increment: number;
+            };
+        };
+    }): Promise<{
+        count: number;
+    }>;
+}
+interface NotificationPreferenceRow {
+    id: string;
+    userId: string;
+    category: string;
+    channels: unknown;
+}
+interface NotificationPreferenceDelegate {
+    findMany(args: {
+        where: {
+            userId: string;
+        };
+    }): Promise<NotificationPreferenceRow[]>;
+    findUnique(args: {
+        where: {
+            userId_category: {
+                userId: string;
+                category: string;
+            };
+        };
+    }): Promise<NotificationPreferenceRow | null>;
+    upsert(args: {
+        where: {
+            userId_category: {
+                userId: string;
+                category: string;
+            };
+        };
+        create: {
+            userId: string;
+            category: string;
+            channels: Record<string, boolean>;
+        };
+        update: {
+            channels: Record<string, boolean>;
+        };
+    }): Promise<NotificationPreferenceRow>;
+}
+interface PushSubscriptionRow {
+    id: string;
+    userId: string;
+    endpoint: string;
+    p256dh: string;
+    auth: string;
+    userAgent: string | null;
+}
+interface PushSubscriptionDelegate {
+    count(args: {
+        where: {
+            userId: string;
+        };
+    }): Promise<number>;
+    /**
+     * The row holding one endpoint, whoever owns it. Read BEFORE an upsert so a
+     * re-own (the same browser profile, a different signed-in user) is a logged
+     * event rather than a silent transfer, and so the settings screen can be told
+     * whether THIS browser's subscription is still the caller's.
+     */
+    findUnique(args: {
+        where: {
+            endpoint: string;
+        };
+    }): Promise<PushSubscriptionRow | null>;
+    findMany(args: {
+        where: {
+            userId: string;
+        };
+    }): Promise<PushSubscriptionRow[]>;
+    upsert(args: {
+        where: {
+            endpoint: string;
+        };
+        create: {
+            userId: string;
+            endpoint: string;
+            p256dh: string;
+            auth: string;
+            userAgent: string | null;
+        };
+        update: {
+            userId: string;
+            p256dh: string;
+            auth: string;
+            userAgent: string | null;
+        };
+    }): Promise<PushSubscriptionRow>;
+    delete(args: {
+        where: {
+            id: string;
+        };
+    }): Promise<PushSubscriptionRow>;
+    deleteMany(args: {
+        where: {
+            userId: string;
+            endpoint: string;
+        };
+    }): Promise<{
+        count: number;
+    }>;
+}
+/** The model delegates — what both a live client and a transaction expose. */
+interface NotificationsDbClient {
+    notification: NotificationDelegate;
+    notificationDelivery: NotificationDeliveryDelegate;
+    notificationPreference: NotificationPreferenceDelegate;
+    pushSubscription: PushSubscriptionDelegate;
+}
+/**
+ * The full seam: delegates plus interactive transactions. The inbox record and
+ * its delivery rows commit together, so a crash can never leave a notification
+ * a user can see with no record of what was meant to carry it. Prisma's own
+ * `$transaction(fn)` satisfies this structurally.
+ */
+interface NotificationsDb extends NotificationsDbClient {
+    $transaction<T>(fn: (tx: NotificationsDbClient) => Promise<T>): Promise<T>;
+}
+/** Deferred so hosts with an async client bootstrap can pass it directly. */
+type NotificationsDbProvider = () => Promise<NotificationsDb>;
+/**
+ * How a transport reaches a person: the destinations the HOST owns.
+ *
+ * Returning `null` for a user id means "no such recipient", which `notify`
+ * treats as a caller bug and throws on — a notification addressed to nobody is
+ * never silently dropped.
+ */
+interface NotificationContactDirectory {
+    getContact(userId: string): Promise<{
+        email: string | null;
+        phone: string | null;
+    } | null>;
+}
+
+/**
+ * Browser push subscription registry — the write side of the Web Push
+ * destination. The client obtains a `PushSubscription` from
+ * `PushManager.subscribe()` (using the VAPID public key) and posts it here;
+ * unsubscribe removes it by endpoint. All owner-scoped.
+ */
+/** What `PushSubscription.toJSON()` yields in the browser. */
+interface PushSubscriptionInput {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+    /** Optional browser/device hint for a device list. */
+    userAgent?: string;
+}
+interface PushSubscriptionStore extends WebPushSubscriptionSource {
+    /**
+     * Register (or refresh) one browser's subscription. Upserts on the globally
+     * unique endpoint, so re-subscribing the same browser never duplicates — and
+     * an endpoint recycled to a different signed-in user is re-owned by them.
+     *
+     * Re-owning is the right call and the alternative is worse: `PushManager`
+     * returns the SAME endpoint for the same browser profile, so one row per
+     * `(userId, endpoint)` would push user A's notifications to a browser now used
+     * by B with B's own keys — which decrypt. Re-owning costs A their channel;
+     * keeping both rows costs A their privacy. What re-owning must NOT do is
+     * happen unrecorded, hence the warning.
+     */
+    save(userId: string, input: PushSubscriptionInput): Promise<void>;
+    /** Remove one browser's subscription (owner-scoped; unknown = no-op). */
+    remove(userId: string, endpoint: string): Promise<void>;
+    /** How many devices the user has registered (settings UI hint). */
+    count(userId: string): Promise<number>;
+    /**
+     * Whether THIS endpoint is currently registered to THIS user.
+     *
+     * The settings screen needs it because a browser's own subscription object is
+     * not evidence that the server still has the row: a re-own or a 404/410 prune
+     * removes the row while the browser keeps the subscription, and a screen that
+     * reads only the browser then tells a user they are receiving alerts they will
+     * never get again. `false` covers both "no such row" and "somebody else's
+     * row", so an endpoint the caller does not own reveals nothing about who does.
+     */
+    isRegisteredTo(userId: string, endpoint: string): Promise<boolean>;
+}
+
+/**
+ * EMAIL transport: formatter + sender behind the driver port.
+ *
+ *   - `driver: 'resend'` — Resend's HTTP API (plain JSON POST, no SDK):
+ *     `apiKey` + `from`.
+ *   - `driver: 'log'` — dev/e2e driver: logs the message instead of sending
+ *     (explicit opt-in, never a silent default).
+ *   - no EMAIL declaration at all — `supports() === false`, router skips it.
+ *
+ * A different vendor (SES, an SMTP relay…) is one more entry in
+ * {@link EMAIL_DRIVERS} — this transport, the router and the registry stay
+ * untouched.
+ */
+/** The channel message an email formatter produces. */
+interface EmailMessage {
+    subject: string;
+    text: string;
+    html: string;
+}
+/** The vendor seam: deliver one already-formatted email. Throws on failure. */
+interface EmailDriver {
+    send(to: string, message: EmailMessage): Promise<void>;
+}
+interface EmailDriverDeclaration extends DriverDeclarationBase {
+    channel: 'EMAIL';
+    /** Resend: the API key. */
+    apiKey?: string;
+    /** Resend: the verified `From` address. */
+    from?: string;
+    /** Where the CTA link points; without it a link is dropped. */
+    appUrl?: string;
+    /** CTA label. pt-BR product copy by default. */
+    linkLabel?: string;
+    logger?: NotificationLogger;
+}
+/** The built-in email vendors. A host adds one by extending this table. */
+declare const EMAIL_DRIVERS: Record<string, (declaration: EmailDriverDeclaration) => EmailDriver>;
+/**
+ * Agnostic content → subject/text/html. The link becomes a trailing CTA, only
+ * when an app base URL is configured.
+ */
+declare function formatEmail(content: NotificationContent, declaration: EmailDriverDeclaration): EmailMessage;
+declare function emailTransport(declaration: EmailDriverDeclaration, extraDrivers?: Record<string, (d: EmailDriverDeclaration) => EmailDriver>): NotificationTransport<EmailMessage>;
+
+/**
+ * SMS transport — Twilio behind the same driver port as email.
+ *
+ *   - `driver: 'twilio'` — the Messages API (form-encoded POST with basic
+ *     auth, no SDK): `accountSid`, `authToken`, `from` (an E.164 sender or a
+ *     Messaging Service SID).
+ *   - `driver: 'log'` — dev driver: logs instead of sending.
+ *   - no SMS declaration — channel unavailable, router skips it.
+ *
+ * A recipient without a normalizable phone is unavailable on this channel
+ * regardless of the driver (see `../../phone.ts` for the verification caveat).
+ */
+/** The channel message the SMS formatter produces: one plain text body. */
+interface SmsMessage {
+    body: string;
+}
+interface SmsDriver {
+    send(toE164: string, message: SmsMessage): Promise<void>;
+}
+interface SmsDriverDeclaration extends DriverDeclarationBase {
+    channel: 'SMS';
+    accountSid?: string;
+    authToken?: string;
+    from?: string;
+    appUrl?: string;
+    /**
+     * Country calling code for a bare local number, digits only (`'55'`, `'1'`).
+     * REQUIRED: this package assumes no country, because the one it used to
+     * assume turned a US number into a plausible Brazilian mobile and texted a
+     * stranger the customer's order (see `../../phone.ts`).
+     */
+    defaultCountryCode: string;
+    logger?: NotificationLogger;
+}
+declare const SMS_DRIVERS: Record<string, (declaration: SmsDriverDeclaration) => SmsDriver>;
+/** Agnostic content → one plain SMS: "title: body (link)", length-capped. */
+declare function formatSms(content: NotificationContent, declaration: SmsDriverDeclaration): SmsMessage;
+declare function smsTransport(declaration: SmsDriverDeclaration, extraDrivers?: Record<string, (d: SmsDriverDeclaration) => SmsDriver>): NotificationTransport<SmsMessage>;
+
+/**
+ * WHATSAPP transport — Meta's WhatsApp Cloud API behind the driver port.
+ *
+ *   - `driver: 'meta'` — the Cloud API (JSON POST with a bearer token, no
+ *     SDK): `accessToken` + `phoneNumberId`.
+ *   - `driver: 'log'` — dev driver: logs instead of sending.
+ *   - no WHATSAPP declaration — channel unavailable, router skips it.
+ *
+ * Template/session-window rule: WhatsApp only accepts FREE-FORM text inside a
+ * 24h customer-service window; business-initiated messages outside it require
+ * a pre-approved TEMPLATE. With `templateName` set the transport sends that
+ * template with two body parameters — {{1}} = title, {{2}} = body (language
+ * `templateLanguage`, default `pt_BR`). Without it the transport sends
+ * free-form text, and a send outside the session window FAILS with the
+ * provider's error recorded on the delivery row — the documented fallback
+ * behaviour, visible instead of silent.
+ *
+ * The window cannot be TRACKED from here (only Meta knows when the customer
+ * last wrote), so a host that declares WHATSAPP with no `templateName` and then
+ * emits business-initiated notifications has every send rejected. That is
+ * visible on the delivery rows, but only once they exist — so the mount warns
+ * about the combination the moment the declaration is read, which is the one
+ * moment a misconfiguration is cheap to notice.
+ */
+/** The channel message the WhatsApp formatter produces. */
+interface WhatsAppMessage {
+    /** Free-form text used inside the session window / without a template. */
+    text: string;
+    /** Template body parameters ({{1}} title, {{2}} body) when templated. */
+    templateParameters: [title: string, body: string];
+}
+interface WhatsAppDriver {
+    send(toE164: string, message: WhatsAppMessage): Promise<void>;
+}
+interface WhatsAppDriverDeclaration extends DriverDeclarationBase {
+    channel: 'WHATSAPP';
+    accessToken?: string;
+    phoneNumberId?: string;
+    templateName?: string;
+    /**
+     * The WhatsApp template's language code, e.g. `pt_BR`, `en_US`.
+     *
+     * REQUIRED: a template is registered with Meta under one language, and
+     * sending it with the wrong code is rejected by the Graph API. This defaulted
+     * to `pt_BR` — one market's answer — so a host that forgot it did not get a
+     * sensible fallback, it got somebody else's template language and a delivery
+     * failure it had no reason to expect.
+     */
+    templateLanguage: string;
+    /** Graph API base, so a host can pin a version. */
+    graphApiBase?: string;
+    appUrl?: string;
+    /**
+     * Country calling code for a bare local number, digits only (`'55'`, `'1'`).
+     * REQUIRED for the same reason SMS requires it — see `../../phone.ts`.
+     */
+    defaultCountryCode: string;
+    logger?: NotificationLogger;
+}
+declare const WHATSAPP_DRIVERS: Record<string, (declaration: WhatsAppDriverDeclaration) => WhatsAppDriver>;
+/** Agnostic content → WhatsApp text + template parameters. */
+declare function formatWhatsApp(content: NotificationContent, declaration: WhatsAppDriverDeclaration): WhatsAppMessage;
+declare function whatsAppTransport(declaration: WhatsAppDriverDeclaration, extraDrivers?: Record<string, (d: WhatsAppDriverDeclaration) => WhatsAppDriver>, logger?: NotificationLogger): NotificationTransport<WhatsAppMessage>;
+
+/**
+ * The transport registry: the router dispatches through this, so adding a
+ * channel = registering one adapter and the router, generators and existing
+ * transports are untouched (open/closed).
+ *
+ * A mount declares its channels and gets a registry; nothing is process-wide.
+ * The origin registered its four transports as an IMPORT SIDE EFFECT of the
+ * package's root entry, which made "which channels are on" a property of the
+ * module graph rather than of any configuration — importing the inbox helpers
+ * in a unit test silently armed four transports.
+ */
+/** One channel's declaration. The union is closed; the drivers are not. */
+type TransportDeclaration = EmailDriverDeclaration | SmsDriverDeclaration | WhatsAppDriverDeclaration | WebPushDriverDeclaration;
+/** A host's own vendors, added per channel without touching the package. */
+interface ExtraDrivers {
+    email?: Record<string, (declaration: EmailDriverDeclaration) => EmailDriver>;
+    sms?: Record<string, (declaration: SmsDriverDeclaration) => SmsDriver>;
+    whatsapp?: Record<string, (declaration: WhatsAppDriverDeclaration) => WhatsAppDriver>;
+    webPush?: Record<string, (declaration: WebPushDriverDeclaration) => WebPushSender>;
+}
+interface TransportRegistry {
+    /** The adapter for `channel`, or null when the host declared none. */
+    get(channel: NotificationChannel): NotificationTransport<never> | null;
+    /** Every declared adapter, in declaration order. */
+    list(): NotificationTransport<never>[];
+    /** Register (or replace, last-wins) an adapter built by the host itself. */
+    register<TMessage>(transport: NotificationTransport<TMessage>): void;
+    /** The VAPID public key, when the WEB_PUSH channel declared one. */
+    webPushPublicKey(): string | null;
+}
+declare function createTransportRegistry(declarations: readonly TransportDeclaration[], subscriptions: WebPushSubscriptionSource, extra?: ExtraDrivers, 
+/** The mount's logger, for a declaration that is legal but probably wrong. */
+logger?: NotificationLogger): TransportRegistry;
+
+/**
+ * Per-user channel preferences: which transport channels may carry each
+ * notification category to a user. The inbox is NOT gated here — it is always
+ * on.
+ *
+ * The POLICY (defaults, coercion, merge) lives in `../preferences-core.ts`;
+ * this is the storage over it, and the split is what lets the react half render
+ * the same defaults before the first read lands.
+ */
+interface NotificationPreferenceStore {
+    /** The user's full matrix, defaults merged in. */
+    get(userId: string): Promise<ChannelMatrix>;
+    /** Persist explicit choices for any subset of categories/toggles. */
+    save(userId: string, input: Partial<Record<NotificationCategory, Partial<ChannelRow>>>): Promise<void>;
+    /** The channels enabled for one (user, category) — the router's gate. */
+    enabledChannels(userId: string, category: NotificationCategory): Promise<NotificationChannel[]>;
+}
+
+/**
+ * The channel router + the `notify` emit API — the single front door into the
+ * pipeline. Any server-side caller (route handler, background worker, agent
+ * tool) emits with one typed call and zero knowledge of channels, formatting,
+ * or preferences:
+ *
+ *     await notifications.notify({ type: 'order.paid', recipient: { userId }, payload });
+ *
+ * What one emit does:
+ *   1. Resolves the registered generator for `type` → agnostic content.
+ *   2. ALWAYS writes the inbox record (the always-on channel), atomically
+ *      with…
+ *   3. …one QUEUED delivery per channel that is (a) enabled by the recipient's
+ *      preferences for the generator's category and (b) supported by its
+ *      transport for this recipient.
+ *   4. Hands the deliveries to the transports ASYNCHRONOUSLY (fire-and-forget
+ *      by default) so emit sites never block on provider I/O.
+ *
+ * The TRANSACTION IS THIS PACKAGE'S OWN, and a host cannot enlist in it: step 2
+ * opens `client.$transaction` itself, and a Prisma `TransactionClient` has no
+ * `$transaction` to nest. So `notify` must be called AFTER the caller's own
+ * transaction commits — called from inside one, it commits an inbox row and
+ * dispatches an e-mail for a payment that then rolls back.
+ *
+ * Failure isolation: each delivery is sent in its own try/catch — one channel
+ * failing marks only its row FAILED (error recorded) and never blocks the
+ * inbox record or the other channels. Delivery is at-least-once: the unique
+ * (notification, channel) row makes fan-out idempotent, and every send is
+ * CLAIMED before it happens (`./dispatch.ts`), so the remaining re-send window
+ * is the unavoidable one — a crash between the provider call and the SENT flip.
+ * Transports are required to tolerate that.
+ *
+ * Queueing: in-process async dispatch by default, or a real queue when the
+ * host passes `scheduleDispatch`. The QUEUED status + the drain sweep are what
+ * make either safe — the delivery rows are the durable record, so a queue that
+ * is unavailable (or absent) costs latency, never a notification.
+ */
+/**
+ * Which channels a TENANT may use, decided per emit — the host's plan gate.
+ *
+ * A `null`/absent clientId is a PLATFORM notification (password resets,
+ * operator alerts) and is never policy-filtered. With no policy installed
+ * every channel passes.
+ */
+type NotificationChannelPolicy = (clientId: string, channels: readonly NotificationChannel[]) => Promise<NotificationChannel[]> | NotificationChannel[];
+/** How the host defers dispatch of one already-committed notification. */
+type NotificationDispatchScheduler = (notificationId: string) => Promise<void>;
+/** One committed inbox record, as the commit observer sees it. */
+interface CommittedNotification {
+    notificationId: string;
+    /** The owner — the only field a user-scoped fan-out needs. */
+    userId: string;
+    /** The tenant the row was stamped with, or null for a platform emit. */
+    clientId: string | null;
+}
+/**
+ * Told about each inbox record the moment it commits. Synchronous and
+ * `void`-returning by contract: an observer may not make an emit site wait,
+ * and may not fail one.
+ *
+ * It exists because the inbox record is written HERE, in the package, while the
+ * thing that usually wants to know — a realtime bus — is a dependency this
+ * package does not have and should not gain. Placing it at the funnel rather
+ * than at the emit sites is the point: `notify` is the single front door, so
+ * every sender is covered by construction, including ones written later.
+ */
+type NotificationCommittedListener = (notification: CommittedNotification) => void;
+/** Options for `notify`. */
+interface NotifyOptions {
+    /**
+     * Await transport dispatch instead of fire-and-forget. For tests and
+     * worker/cron contexts where the process may exit right after emitting.
+     */
+    sync?: boolean;
+}
+/** What `notify` resolves with (dispatch may still be in flight). */
+interface NotifyResult {
+    notificationId: string;
+    /** Channels a delivery row was enqueued for (preference ∩ transport gate). */
+    channels: NotificationChannel[];
+}
+interface NotificationRouter {
+    notify<TPayload>(event: NotificationEvent<TPayload>, options?: NotifyOptions): Promise<NotifyResult>;
+    dispatchDeliveries(notificationId: string): Promise<void>;
+    drainPending(olderThanMs?: number, take?: number): Promise<{
+        dispatched: number;
+    }>;
+}
+
+/**
+ * Permission-addressed notifications: "tell whoever can act on this", resolved
+ * against the host's REAL authorization engine.
+ *
+ * Naming an audience by ROLE reads a coarse mirror column, so a tenant who
+ * moved a capability onto a custom role — or granted it additively — gets a
+ * notification list that disagrees with what the app actually authorizes. The
+ * two answers drift silently, and the direction they drift in is "the person
+ * who can fix it never hears about it".
+ *
+ * So this addresses by CAPABILITY: name the permissions the recipient must
+ * hold, and the audience is derived from the same evaluation the guards use.
+ *
+ * ## What the package owns, and what the host answers
+ *
+ * The FOLD is the package's: the AND, the deduplication, the refusal of an
+ * empty permission list, the per-recipient isolation, and the log line that
+ * distinguishes "nobody holds it" from "everybody's dispatch failed". Those are
+ * the parts that are the same in every host and that are easy to get subtly
+ * wrong.
+ *
+ * The two QUERIES are the host's, through {@link NotificationAudienceDirectory}
+ * — because an authorization engine is host machinery. In the extraction origin this
+ * module could not live in a package at all: it needed `notify()` AND the RBAC
+ * engine, and neither package could see the other. Inverting the dependency
+ * (the host answers, the package asks) is what makes it portable.
+ */
+/**
+ * The host's authorization engine, as this fan-out needs it.
+ *
+ * `listCandidates` must be BOUNDED to people who actually hold a role at the
+ * tenant. that host's implementation requires a role grant, which is what
+ * keeps a store's storefront BUYERS — who all carry a default membership — out
+ * of a loop that resolves permissions one user at a time.
+ *
+ * `getPermissions` must be scoped to `tenantId`. Unioning a user's grants
+ * across tenants — the obvious way to "simplify" it — notifies someone about a
+ * store whose money they have no authority over, and no `where` clause upstream
+ * can save it because that user is already a candidate.
+ */
+interface NotificationAudienceDirectory {
+    listCandidates(tenantId: string): Promise<readonly string[]>;
+    getPermissions(userId: string, tenantId: string): Promise<ReadonlySet<string> | readonly string[]>;
+}
+/**
+ * One candidate that did not receive it, and why.
+ *
+ * `audience-error` is deliberately its own reason rather than folded into
+ * `missing-permission`: "this user does not hold the pair" is a configuration
+ * fact, while "we could not find out whether they hold it" is an outage, and
+ * they need opposite responses. Collapsing them would report a database timeout
+ * as a tenant that simply has nobody to tell.
+ */
+interface PermissionNotificationSkip {
+    userId: string;
+    reason: 'missing-permission' | 'dispatch-failed' | 'audience-error';
+}
+/**
+ * What one fan-out actually did. Returned rather than logged-and-forgotten so a
+ * caller (and a test) can assert on the OUTCOME — who was reached and who was
+ * not — without reaching into transport mocks to infer it.
+ */
+interface PermissionNotificationResult {
+    /** User ids whose notification committed, in candidate order. */
+    notified: string[];
+    /** Candidates that did not receive it, with the reason. */
+    skipped: PermissionNotificationSkip[];
+}
+type NotifyByPermission = <TPayload>(clientId: string, permissions: readonly string[], event: Omit<NotificationEvent<TPayload>, 'recipient'>) => Promise<PermissionNotificationResult>;
+
+/**
+ * What every route in this surface shares (12-15): the actor, the request, the
+ * response envelope and the body parsing. Mirrors the entity-lifecycle /
+ * report-builder shape — framework-neutral descriptors a forty-line adapter
+ * mounts.
+ */
+/**
+ * What a host must resolve before a request reaches these handlers: WHO is
+ * calling. That is the whole seam.
+ *
+ * There is no tenant here and no permission list, and both absences are the
+ * design. Every endpoint in this surface is SELF-scoped — a user reads and
+ * writes their own inbox and their own preferences — so the only authorization
+ * question is "who is signed in", and the answer is applied by scoping every
+ * query to `userId` rather than by a guard that could be forgotten. A
+ * permission-gated ADMIN view of someone else's inbox would be a different
+ * surface, and would need a different actor.
+ */
+interface NotificationsActor {
+    userId: string;
+}
+/** One request, already authenticated and routed by the host. */
+interface NotificationsRequest {
+    actor: NotificationsActor;
+    params: Record<string, string | undefined>;
+    query: Record<string, string | undefined>;
+    body?: unknown;
+    /** Headers the surface reads (`user-agent`, for the device hint). */
+    headers?: Record<string, string | undefined>;
+}
+/** What a handler answers with; the adapter maps it onto its response type. */
+interface NotificationsResponse {
+    status: number;
+    /** `undefined` means NO body at all (204) — not the same as `null`. */
+    body: unknown;
+}
+interface NotificationsRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /**
+     * Path relative to the host's account mount, in `:param` form. The SHAPE is
+     * fixed because the packaged client builds these URLs.
+     */
+    path: string;
+    handle(request: NotificationsRequest): Promise<NotificationsResponse>;
+}
+/** A user-safe API error carrying the HTTP status the wire promises. */
+declare class NotificationsApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Success is `{ data }`; a denial is `{ error }`, unwrapped. */
+declare const ok: (data: unknown, status?: number) => NotificationsResponse;
+/** Fold a thrown {@link NotificationsApiError} into a response; rethrow the rest. */
+declare function foldApiError(error: unknown): NotificationsResponse;
+
+/**
+ * Notification-centre inbox reads/writes. Every function is scoped to the
+ * OWNER's `userId` — a caller can only ever see or touch their own rows (the
+ * route layer supplies the authenticated user's id, never a client value).
+ * Soft-deleted rows (`deletedAt` set) are excluded from every read and can
+ * never be resurrected by mark-read.
+ */
+interface ListNotificationsInput {
+    /** `unread` narrows to unread rows; default lists all non-deleted. */
+    filter?: 'all' | 'unread';
+    /**
+     * Cursor = the `id` of the last item of the previous page. Resolved to a
+     * KEYSET position, so a row the user soft-deleted between the two requests —
+     * routinely the bottom one, since that is the row with the delete button —
+     * still anchors the next page instead of costing it a row. Owner-checked: an
+     * id that is not the caller's names no position and answers an empty page.
+     */
+    cursor?: string;
+    /** Page size (server-clamped 1..100, default 20). */
+    limit?: number;
+}
+interface NotificationInboxStore {
+    list(userId: string, input?: ListNotificationsInput): Promise<ListNotificationsResult>;
+    unreadCount(userId: string): Promise<number>;
+    markRead(userId: string, ids: readonly string[]): Promise<number>;
+    markAllRead(userId: string): Promise<number>;
+    softDelete(userId: string, ids: readonly string[]): Promise<number>;
+}
+
+/**
+ * The one thing this package exposes to a BACKEND host (12-15).
+ *
+ * The pipeline used to be a private workspace package plus six hand-written
+ * route files: each one resolving the session, calling a loose helper, and
+ * shaping a response, with the transports reading their own credentials out of
+ * `process.env` and registering themselves as an import side effect. Only "who
+ * is calling, where the rows live, how a channel reaches a person" was ever the
+ * host's business; the rest — the routing, the delivery rows, the retries, the
+ * request contract, the envelope, the pt-BR copy — is this surface's.
+ *
+ * Routes are FRAMEWORK-NEUTRAL descriptors, not a Hono/Express router (the
+ * report-builder doctrine). `@12-apps/notifications/hono` adapts them.
+ *
+ * What stays the HOST's, and is passed in rather than guessed at:
+ *
+ *  - **Authentication** — the adapter's `resolveActor` hands over a user id.
+ *    Every endpoint is self-scoped, so that is the entire authorization seam.
+ *  - **Where the four owned tables live** — the structural `db` seam.
+ *  - **How to reach a person** — `contacts`, because a package cannot know the
+ *    shape of a host's identity table (nor whether its phones are verified).
+ *  - **Which vendors carry which channel** — `transports`, one declaration per
+ *    channel. An undeclared channel is off; a second vendor is a config entry.
+ *  - **Billing** — `channelPolicy`, the plan gate answered per emit.
+ *  - **Its authorization engine** — `audience`, for the permission fan-out.
+ *  - **Its domain events** — `generators`, registered from the outside.
+ */
+interface NotificationsServerConfig {
+    /** Prisma-shaped client for the four owned models, through the seam. */
+    db: NotificationsDbProvider;
+    /** How a transport reaches a person (the host's identity table). */
+    contacts: NotificationContactDirectory;
+    /** One declaration per channel the host wants on. Default: none, all off. */
+    transports?: readonly TransportDeclaration[];
+    /** The host's own vendor drivers, per channel. */
+    drivers?: ExtraDrivers;
+    /** The domain events this mount can emit. */
+    generators?: readonly NotificationGenerator<never>[];
+    /**
+     * Preference categories — the granularity at which a user chooses channels.
+     *
+     * REQUIRED. This defaulted to one product's four (`orders`, `payments`,
+     * `stock`, `system`), which is the host's vocabulary and not this library's:
+     * a host that omitted it rendered four rows it never chose, with its own
+     * categories absent, and nothing failed — `category` is a free string by
+     * design, so there was no layer left to notice.
+     */
+    categories: readonly NotificationCategory[];
+    /** Override which channels a never-touched category defaults to. */
+    channelDefaults?: Partial<ChannelRow>;
+    /** The tenant plan gate, answered per emit. */
+    channelPolicy?: NotificationChannelPolicy;
+    /** Hand dispatch to a real queue instead of the in-process detached send. */
+    scheduleDispatch?: NotificationDispatchScheduler;
+    /**
+     * Claims one delivery gets before the sweep gives up on it and writes DEAD.
+     * Default 5. There is no "unlimited": a permanently invalid destination would
+     * be a billed provider call on every sweep for the life of the row.
+     */
+    maxDeliveryAttempts?: number;
+    /** Told the moment an inbox record commits (a realtime bus, typically). */
+    onCommitted?: NotificationCommittedListener;
+    /** Told when a mark-read/delete actually changed something. */
+    onInboxChanged?: (userId: string) => void;
+    /** The host's authorization engine, for `notifyByPermission`. */
+    audience?: NotificationAudienceDirectory;
+    /** User-facing copy overrides (pt-BR product copy by default). */
+    messages: NotificationWireMessages;
+    /** The host's logger. Defaults to the console. */
+    logger?: NotificationLogger;
+}
+interface ApiNotifications {
+    /** The whole generated surface, in mount order. */
+    routes: NotificationsRoute[];
+    /** The emit front door. */
+    notify: NotificationRouter['notify'];
+    /** Send every still-QUEUED delivery of one notification. */
+    dispatchDeliveries: NotificationRouter['dispatchDeliveries'];
+    /** The retry sweep, for a cron/admin trigger. */
+    drainPending: NotificationRouter['drainPending'];
+    /**
+     * "Tell whoever can act on this." Rejects when the host configured no
+     * `audience` — loudly, because the alternative is a money alert nobody gets.
+     */
+    notifyByPermission: NotifyByPermission;
+    /** The stores, for host surfaces that read the same tables. */
+    inbox: NotificationInboxStore;
+    preferences: NotificationPreferenceStore;
+    pushSubscriptions: PushSubscriptionStore;
+    /** Register a generator after the mount (a lazily-imported domain module). */
+    registerGenerator: NotificationGeneratorRegistry['register'];
+    /** The declared transports, for diagnostics and availability probes. */
+    transports: TransportRegistry;
+    /** The copy in force, so a host's own screens can reuse a sentence. */
+    messages: NotificationWireMessages;
+}
+declare function createApiNotifications(config: NotificationsServerConfig): ApiNotifications;
+
+export { type ApiNotifications, type CommittedNotification, DriverDeclarationBase, EMAIL_DRIVERS, type EmailDriver, type EmailDriverDeclaration, type EmailMessage, type ExtraDrivers, type ListNotificationsInput, type NotificationAudienceDirectory, type NotificationChannelPolicy, type NotificationCommittedListener, type NotificationContactDirectory, type NotificationCreateData, type NotificationDelegate, type NotificationDeliveryDelegate, type NotificationDeliveryRow, type NotificationDeliveryWhere, type NotificationDispatchScheduler, type NotificationInboxStore, type NotificationPageAfter, type NotificationPreferenceDelegate, type NotificationPreferenceRow, type NotificationPreferenceStore, type NotificationRouter, type NotificationWhere, type NotificationsActor, NotificationsApiError, type NotificationsDb, type NotificationsDbClient, type NotificationsDbProvider, type NotificationsRequest, type NotificationsResponse, type NotificationsRoute, type NotificationsServerConfig, type NotifyByPermission, type NotifyOptions, type NotifyResult, type PermissionNotificationResult, type PermissionNotificationSkip, type PushSubscriptionDelegate, type PushSubscriptionInput, type PushSubscriptionRow, type PushSubscriptionStore, SMS_DRIVERS, type SmsDriver, type SmsDriverDeclaration, type SmsMessage, type TransportDeclaration, type TransportRegistry, WHATSAPP_DRIVERS, WebPushDriverDeclaration, WebPushSender, WebPushSubscriptionSource, type WhatsAppDriver, type WhatsAppDriverDeclaration, type WhatsAppMessage, createApiNotifications, createTransportRegistry, emailTransport, foldApiError, formatEmail, formatSms, formatWhatsApp, ok, smsTransport, whatsAppTransport };