@12-apps/notifications 1.0.0

package/src/server/transports/drivers.ts

@@ -0,0 +1,148 @@
+/**
+ * The DRIVER port — the reason a host adds a vendor with a config entry and no
+ * code (12-15).
+ *
+ * future-pay's transports each read `process.env` directly:
+ * `NOTIFICATIONS_EMAIL_PROVIDER=resend` plus `RESEND_API_KEY`, and a second
+ * vendor meant editing the package. That is exactly backwards for a published
+ * package — it cannot know a host's variable names, and it must not be the
+ * thing that decides whether a channel is on. So a channel is configured by
+ * DECLARATION:
+ *
+ *     transports: [
+ *       { channel: 'EMAIL', driver: 'resend', apiKey, from },
+ *       { channel: 'SMS',   driver: 'log' },
+ *     ]
+ *
+ * A channel with no declaration reports `supports() === false` and the router
+ * skips it: no delivery row, nothing fake-sent. A second vendor is one more
+ * entry in the built-in driver table (or `drivers` on the config, for a host's
+ * own), and the router, the registry and the other transports are untouched.
+ */
+
+import { normalizePhoneE164 } from '../../phone';
+import type {
+  NotificationContent,
+  NotificationTransport,
+  TransportRecipient,
+} from '../../types';
+
+/** Every HTTP call a built-in driver makes goes through this, so a test can. */
+export type FetchImpl = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/** Shared by every declaration: which channel, which vendor. */
+export interface DriverDeclarationBase {
+  /** Vendor key: `resend` / `twilio` / `meta` / `log`, or a host's own. */
+  driver: string;
+  /**
+   * The HTTP client the vendor call uses. Defaults to the global `fetch`.
+   * Supplied by tests and by hosts that need a proxy or a retry policy.
+   */
+  fetchImpl?: FetchImpl;
+}
+
+/** A vendor rejection, carrying what the provider actually said. */
+export class NotificationProviderError extends Error {
+  readonly status: number;
+  constructor(vendor: string, status: number, detail: string) {
+    super(`${vendor} rejected the message (${status} ${detail}).`);
+    this.name = 'NotificationProviderError';
+    this.status = status;
+    Object.setPrototypeOf(this, NotificationProviderError.prototype);
+  }
+}
+
+/** `fetch` and throw {@link NotificationProviderError} on a non-2xx. */
+export async function postOrThrow(
+  vendor: string,
+  fetchImpl: FetchImpl | undefined,
+  url: string,
+  init: { headers: Record<string, string>; body: string },
+): Promise<void> {
+  const call = fetchImpl ?? (globalThis.fetch as unknown as FetchImpl);
+  const response = await call(url, { method: 'POST', ...init });
+  if (!response.ok) {
+    throw new NotificationProviderError(vendor, response.status, await response.text());
+  }
+}
+
+/**
+ * Resolve one declaration against a driver table.
+ *
+ * Returning `null` — an unknown driver name — is a CONFIGURATION error, not a
+ * runtime one, so the caller (the transport factory) throws with the names it
+ * does know. A typo'd vendor that silently disabled a channel is the failure
+ * mode this whole seam exists to remove.
+ */
+export function resolveDriver<TDeclaration extends DriverDeclarationBase, TDriver>(
+  channel: string,
+  declaration: TDeclaration,
+  table: Record<string, (declaration: TDeclaration) => TDriver>,
+): TDriver {
+  const factory = table[declaration.driver];
+  if (!factory) {
+    throw new Error(
+      `@12-apps/notifications: unknown ${channel} driver "${declaration.driver}". ` +
+        `Known drivers: ${Object.keys(table).sort().join(', ')}.`,
+    );
+  }
+  return factory(declaration);
+}
+
+/**
+ * Absolutize an in-app link for a channel that leaves the app.
+ *
+ * A relative path is useless in an inbox and a fabricated localhost link is
+ * worse than none, so with no `appUrl` configured the link is simply dropped —
+ * future-pay's rule, kept.
+ */
+export function absoluteLink(link: string | undefined, appUrl: string | undefined): string | null {
+  if (!link || !appUrl) return null;
+  try {
+    return new URL(link, appUrl).toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The two PHONE channels' shared skeleton.
+ *
+ * SMS and WhatsApp differ in their vendor, their message shape and their
+ * formatter — and in nothing else: both are unavailable for a recipient whose
+ * number will not normalize, both normalize before the vendor ever sees the
+ * destination, and both refuse rather than send when it cannot be. Stating that
+ * rule twice is how the two drift, which is exactly what happened to the
+ * transports' `supports()` gates before they funnelled through one helper.
+ */
+export function phoneChannel<TMessage>(
+  channel: 'SMS' | 'WHATSAPP',
+  options: {
+    /** Country calling code for a bare local number. Required — see `phone.ts`. */
+    defaultCountryCode: string;
+    format: (content: NotificationContent) => TMessage;
+    send: (toE164: string, message: TMessage) => Promise<void>;
+  },
+): NotificationTransport<TMessage> {
+  const toE164 = (recipient: TransportRecipient): string | null =>
+    normalizePhoneE164(recipient.phone, {
+      defaultCountryCode: options.defaultCountryCode,
+    });
+  return {
+    channel,
+    supports: (recipient) => toE164(recipient) !== null,
+    format: options.format,
+    async send(message, recipient) {
+      const to = toE164(recipient);
+      if (!to) throw new Error('Recipient has no usable phone number.');
+      await options.send(to, message);
+    },
+  };
+}

package/src/server/transports/email.ts

@@ -0,0 +1,141 @@
+import type {
+  NotificationContent,
+  NotificationLogger,
+  NotificationTransport,
+  TransportRecipient,
+} from '../../types';
+
+import {
+  absoluteLink,
+  postOrThrow,
+  resolveDriver,
+  type DriverDeclarationBase,
+} from './drivers';
+
+/**
+ * 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. */
+export interface EmailMessage {
+  subject: string;
+  text: string;
+  html: string;
+}
+
+/** The vendor seam: deliver one already-formatted email. Throws on failure. */
+export interface EmailDriver {
+  send(to: string, message: EmailMessage): Promise<void>;
+}
+
+export 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;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+const resendDriver = (declaration: EmailDriverDeclaration): EmailDriver => ({
+  async send(to, message) {
+    if (!declaration.apiKey || !declaration.from) {
+      throw new Error('The resend email driver needs both `apiKey` and `from`.');
+    }
+    await postOrThrow('Resend', declaration.fetchImpl, 'https://api.resend.com/emails', {
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${declaration.apiKey}`,
+      },
+      body: JSON.stringify({
+        from: declaration.from,
+        to: [to],
+        subject: message.subject,
+        text: message.text,
+        html: message.html,
+      }),
+    });
+  },
+});
+
+const logEmailDriver = (declaration: EmailDriverDeclaration): EmailDriver => ({
+  // Deliberately logs NO destination address — a recipient e-mail is PII and
+  // must never reach logs; the subject alone is enough for local debugging.
+  send(_to, message) {
+    declaration.logger?.info(
+      `[notifications:email] log driver suppressed a real send (subject="${message.subject}")`,
+    );
+    return Promise.resolve();
+  },
+});
+
+/** The built-in email vendors. A host adds one by extending this table. */
+export const EMAIL_DRIVERS: Record<
+  string,
+  (declaration: EmailDriverDeclaration) => EmailDriver
+> = {
+  resend: resendDriver,
+  log: logEmailDriver,
+};
+
+/**
+ * Agnostic content → subject/text/html. The link becomes a trailing CTA, only
+ * when an app base URL is configured.
+ */
+export function formatEmail(
+  content: NotificationContent,
+  declaration: EmailDriverDeclaration,
+): EmailMessage {
+  const href = absoluteLink(content.link, declaration.appUrl);
+  const label = declaration.linkLabel ?? 'Ver detalhes';
+  return {
+    subject: content.title,
+    text: href ? `${content.body}\n\n${href}` : content.body,
+    html: [
+      `<p><strong>${escapeHtml(content.title)}</strong></p>`,
+      `<p>${escapeHtml(content.body)}</p>`,
+      ...(href ? [`<p><a href="${escapeHtml(href)}">${escapeHtml(label)}</a></p>`] : []),
+    ].join('\n'),
+  };
+}
+
+export function emailTransport(
+  declaration: EmailDriverDeclaration,
+  extraDrivers: Record<string, (d: EmailDriverDeclaration) => EmailDriver> = {},
+): NotificationTransport<EmailMessage> {
+  const driver = resolveDriver('EMAIL', declaration, { ...EMAIL_DRIVERS, ...extraDrivers });
+  return {
+    channel: 'EMAIL',
+    // Truthiness, not `!== null`: an EMPTY STRING is a very ordinary DB value
+    // for a nullable column, and it used to pass this gate, earn a delivery row
+    // and then fail forever against `send`'s own `!recipient.email` check.
+    supports: (recipient: TransportRecipient) => Boolean(recipient.email),
+    format: (content) => formatEmail(content, declaration),
+    async send(message, recipient) {
+      if (!recipient.email) throw new Error('Recipient has no email address.');
+      await driver.send(recipient.email, message);
+    },
+  };
+}

package/src/server/transports/registry.ts

@@ -0,0 +1,106 @@
+import type {
+  NotificationChannel,
+  NotificationLogger,
+  NotificationTransport,
+} from '../../types';
+
+import type { EmailDriver, EmailDriverDeclaration } from './email';
+import { emailTransport } from './email';
+import type { SmsDriver, SmsDriverDeclaration } from './sms';
+import { smsTransport } from './sms';
+import type { WebPushDriverDeclaration, WebPushSender, WebPushSubscriptionSource } from './web-push';
+import { webPushTransport } from './web-push';
+import type { WhatsAppDriver, WhatsAppDriverDeclaration } from './whatsapp';
+import { whatsAppTransport } from './whatsapp';
+
+/**
+ * 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.
+ * future-pay 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. */
+export type TransportDeclaration =
+  | EmailDriverDeclaration
+  | SmsDriverDeclaration
+  | WhatsAppDriverDeclaration
+  | WebPushDriverDeclaration;
+
+/** A host's own vendors, added per channel without touching the package. */
+export 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>;
+}
+
+export 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;
+}
+
+function build(
+  declaration: TransportDeclaration,
+  subscriptions: WebPushSubscriptionSource,
+  extra: ExtraDrivers,
+  logger?: NotificationLogger,
+): NotificationTransport<never> {
+  switch (declaration.channel) {
+    case 'EMAIL':
+      return emailTransport(declaration, extra.email ?? {}) as NotificationTransport<never>;
+    case 'SMS':
+      return smsTransport(declaration, extra.sms ?? {}) as NotificationTransport<never>;
+    case 'WHATSAPP':
+      return whatsAppTransport(
+        declaration,
+        extra.whatsapp ?? {},
+        logger,
+      ) as NotificationTransport<never>;
+    case 'WEB_PUSH':
+      return webPushTransport(
+        declaration,
+        subscriptions,
+        extra.webPush ?? {},
+      ) as NotificationTransport<never>;
+  }
+}
+
+export 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 {
+  const transports = new Map<NotificationChannel, NotificationTransport<never>>();
+  let publicKey: string | null = null;
+  for (const declaration of declarations) {
+    if (transports.has(declaration.channel)) {
+      throw new Error(
+        `@12-apps/notifications: the ${declaration.channel} channel is declared twice.`,
+      );
+    }
+    if (declaration.channel === 'WEB_PUSH') publicKey = declaration.publicKey ?? null;
+    transports.set(declaration.channel, build(declaration, subscriptions, extra, logger));
+  }
+  return {
+    get: (channel) => transports.get(channel) ?? null,
+    list: () => [...transports.values()],
+    register(transport) {
+      transports.set(transport.channel, transport as NotificationTransport<never>);
+    },
+    webPushPublicKey: () => publicKey,
+  };
+}

package/src/server/transports/sms.ts

@@ -0,0 +1,120 @@
+import type {
+  NotificationContent,
+  NotificationLogger,
+  NotificationTransport,
+} from '../../types';
+
+import {
+  absoluteLink,
+  phoneChannel,
+  postOrThrow,
+  resolveDriver,
+  type DriverDeclarationBase,
+} from './drivers';
+
+/**
+ * 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. */
+export interface SmsMessage {
+  body: string;
+}
+
+export interface SmsDriver {
+  send(toE164: string, message: SmsMessage): Promise<void>;
+}
+
+export 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;
+}
+
+/** SMS bodies are billed per 160-char segment — keep one message ≤ 3 segments. */
+const MAX_SMS_CHARS = 480;
+
+const twilioDriver = (declaration: SmsDriverDeclaration): SmsDriver => ({
+  async send(toE164, message) {
+    const sid = declaration.accountSid;
+    if (!sid || !declaration.authToken || !declaration.from) {
+      throw new Error('The twilio sms driver needs `accountSid`, `authToken` and `from`.');
+    }
+    const auth = Buffer.from(`${sid}:${declaration.authToken}`).toString('base64');
+    await postOrThrow(
+      'Twilio',
+      declaration.fetchImpl,
+      `https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(sid)}/Messages.json`,
+      {
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Authorization: `Basic ${auth}`,
+        },
+        body: new URLSearchParams({
+          To: toE164,
+          From: declaration.from,
+          Body: message.body,
+        }).toString(),
+      },
+    );
+  },
+});
+
+const logSmsDriver = (declaration: SmsDriverDeclaration): SmsDriver => ({
+  // Deliberately logs NO destination — a phone number is PII and must never
+  // reach logs; the message body alone is enough for local debugging.
+  send(_toE164, message) {
+    declaration.logger?.info(
+      `[notifications:sms] log driver suppressed a real send (body="${message.body}")`,
+    );
+    return Promise.resolve();
+  },
+});
+
+export const SMS_DRIVERS: Record<string, (declaration: SmsDriverDeclaration) => SmsDriver> = {
+  twilio: twilioDriver,
+  log: logSmsDriver,
+};
+
+/** Agnostic content → one plain SMS: "title: body (link)", length-capped. */
+export function formatSms(
+  content: NotificationContent,
+  declaration: SmsDriverDeclaration,
+): SmsMessage {
+  const parts = [`${content.title}: ${content.body}`];
+  const href = absoluteLink(content.link, declaration.appUrl);
+  if (href) parts.push(href);
+  const body = parts.join(' ');
+  return { body: body.length > MAX_SMS_CHARS ? `${body.slice(0, MAX_SMS_CHARS - 1)}…` : body };
+}
+
+export function smsTransport(
+  declaration: SmsDriverDeclaration,
+  extraDrivers: Record<string, (d: SmsDriverDeclaration) => SmsDriver> = {},
+): NotificationTransport<SmsMessage> {
+  const driver = resolveDriver('SMS', declaration, { ...SMS_DRIVERS, ...extraDrivers });
+  return phoneChannel<SmsMessage>('SMS', {
+    defaultCountryCode: declaration.defaultCountryCode,
+    format: (content) => formatSms(content, declaration),
+    send: (toE164, message) => driver.send(toE164, message),
+  });
+}

package/src/server/transports/web-push.ts

@@ -0,0 +1,168 @@
+import type {
+  NotificationContent,
+  NotificationLogger,
+  NotificationTransport,
+  TransportRecipient,
+} from '../../types';
+
+import { resolveDriver, type DriverDeclarationBase } from './drivers';
+
+/**
+ * WEB_PUSH transport — browser alerts over the Web Push protocol.
+ *
+ * What is the PACKAGE's, and stays here: the payload the service worker
+ * renders, the fan-out to every one of the user's browsers, the 404/410 PRUNE
+ * that makes `push_subscriptions` self-heal, and the rule that a send succeeds
+ * when at least one subscription accepted it and fails only when all errored.
+ *
+ * What is the VENDOR's, and crosses as a port: VAPID signing and RFC 8291
+ * payload encryption. Those need the `web-push` package, a node-only
+ * dependency this package must not force on a host that never enables the
+ * channel — so `@12-apps/notifications/web-push` exports the sender behind its
+ * own subpath and an optional peer, exactly as `./hono` does for the adapter.
+ *
+ *   - `driver: 'vapid'` — `sender: vapidPushSender({ subject, publicKey,
+ *     privateKey })` from that subpath (or any other signer).
+ *   - `driver: 'log'` — dev driver: logs instead of sending.
+ *   - no WEB_PUSH declaration — channel unavailable, router skips it.
+ */
+
+/** One browser subscription, as `PushManager.subscribe()` yields it. */
+export interface WebPushSubscription {
+  endpoint: string;
+  keys: { p256dh: string; auth: string };
+}
+
+/**
+ * The vendor seam: sign + encrypt + POST one payload to one push service.
+ *
+ * MUST reject with an error carrying a numeric `statusCode` when the push
+ * service answers one — that is how a gone subscription (404/410) is told
+ * apart from a transient failure, and therefore what makes the prune correct
+ * rather than destructive.
+ */
+export type WebPushSender = (
+  subscription: WebPushSubscription,
+  payload: string,
+) => Promise<void>;
+
+/** The channel message the Web Push formatter produces (the SW's payload). */
+export interface WebPushMessage {
+  title: string;
+  body: string;
+  link: string | null;
+  data: Record<string, unknown>;
+}
+
+export interface WebPushDriverDeclaration extends DriverDeclarationBase {
+  channel: 'WEB_PUSH';
+  /** Required by the `vapid` driver: the signer. */
+  sender?: WebPushSender;
+  /**
+   * The VAPID PUBLIC key, served to the browser by
+   * `GET <mount>/push-subscriptions` so the client can subscribe. Public by
+   * definition — the private key never crosses into this declaration.
+   */
+  publicKey?: string;
+  logger?: NotificationLogger;
+}
+
+/** The subscriptions the transport reads and prunes (db-backed by the mount). */
+export interface WebPushSubscriptionSource {
+  list(userId: string): Promise<{ id: string; endpoint: string; p256dh: string; auth: string }[]>;
+  prune(id: string): Promise<void>;
+}
+
+const vapidDriver = (declaration: WebPushDriverDeclaration): WebPushSender => {
+  const sender = declaration.sender;
+  if (!sender) {
+    throw new Error(
+      'The vapid web-push driver needs a `sender` — import `vapidPushSender` from ' +
+        '@12-apps/notifications/web-push.',
+    );
+  }
+  return sender;
+};
+
+const logWebPushDriver =
+  (declaration: WebPushDriverDeclaration): WebPushSender =>
+  (_subscription, payload) => {
+    // No endpoint logged: a push endpoint is a bearer capability for that
+    // browser, so it is a secret in exactly the way an e-mail address is PII.
+    declaration.logger?.info(
+      `[notifications:web-push] log driver suppressed a real send (${payload.length} bytes)`,
+    );
+    return Promise.resolve();
+  };
+
+export const WEB_PUSH_DRIVERS: Record<
+  string,
+  (declaration: WebPushDriverDeclaration) => WebPushSender
+> = {
+  vapid: vapidDriver,
+  log: logWebPushDriver,
+};
+
+/** Status codes that mean "this subscription no longer exists — prune it". */
+const GONE_STATUSES = new Set([404, 410]);
+
+function statusCodeOf(error: unknown): number | null {
+  if (error && typeof error === 'object' && 'statusCode' in error) {
+    const code = (error as { statusCode: unknown }).statusCode;
+    return typeof code === 'number' ? code : null;
+  }
+  return null;
+}
+
+export function formatWebPush(content: NotificationContent): WebPushMessage {
+  return {
+    title: content.title,
+    body: content.body,
+    link: content.link ?? null,
+    data: content.data ?? {},
+  };
+}
+
+export function webPushTransport(
+  declaration: WebPushDriverDeclaration,
+  subscriptions: WebPushSubscriptionSource,
+  extraDrivers: Record<string, (d: WebPushDriverDeclaration) => WebPushSender> = {},
+): NotificationTransport<WebPushMessage> {
+  const send = resolveDriver('WEB_PUSH', declaration, {
+    ...WEB_PUSH_DRIVERS,
+    ...extraDrivers,
+  });
+  return {
+    channel: 'WEB_PUSH',
+    supports: (recipient: TransportRecipient) => recipient.pushSubscriptionCount > 0,
+    format: formatWebPush,
+    async send(message, recipient) {
+      const rows = await subscriptions.list(recipient.userId);
+      if (rows.length === 0) throw new Error('Recipient no longer has push subscriptions.');
+      const payload = JSON.stringify(message);
+      let delivered = 0;
+      let lastError: unknown = null;
+      for (const row of rows) {
+        try {
+          await send({ endpoint: row.endpoint, keys: { p256dh: row.p256dh, auth: row.auth } }, payload);
+          delivered += 1;
+        } catch (error) {
+          const status = statusCodeOf(error);
+          if (status !== null && GONE_STATUSES.has(status)) {
+            // Expired/unsubscribed browser — prune so future sends skip it.
+            await subscriptions.prune(row.id).catch(() => {
+              /* already pruned by a concurrent send */
+            });
+          } else {
+            lastError = error;
+          }
+        }
+      }
+      if (delivered === 0) {
+        throw lastError instanceof Error
+          ? lastError
+          : new Error('No push subscription accepted the payload.');
+      }
+    },
+  };
+}