@12-apps/notifications 1.0.0

package/src/server/push-subscriptions.ts

@@ -0,0 +1,121 @@
+import type { NotificationLogger } from '../types';
+
+import type { NotificationsDbProvider } from './db';
+import type { WebPushSubscriptionSource } from './transports/web-push';
+
+/**
+ * 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. */
+export interface PushSubscriptionInput {
+  endpoint: string;
+  keys: { p256dh: string; auth: string };
+  /** Optional browser/device hint for a device list. */
+  userAgent?: string;
+}
+
+export 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>;
+}
+
+export function createPushSubscriptionStore(
+  db: NotificationsDbProvider,
+  logger?: NotificationLogger,
+): PushSubscriptionStore {
+  return {
+    async save(userId, input) {
+      const client = await db();
+      const existing = await client.pushSubscription.findUnique({
+        where: { endpoint: input.endpoint },
+      });
+      if (existing && existing.userId !== userId) {
+        // No endpoint in the message: a push endpoint is a bearer capability for
+        // that browser and must not reach logs. The two user ids are what makes
+        // "user X stopped getting web push on a shared machine" answerable.
+        logger?.error(
+          `[notifications] push endpoint re-owned: user ${existing.userId} lost this ` +
+            `browser's subscription to user ${userId}`,
+        );
+      }
+      await client.pushSubscription.upsert({
+        where: { endpoint: input.endpoint },
+        create: {
+          userId,
+          endpoint: input.endpoint,
+          p256dh: input.keys.p256dh,
+          auth: input.keys.auth,
+          userAgent: input.userAgent ?? null,
+        },
+        update: {
+          userId,
+          p256dh: input.keys.p256dh,
+          auth: input.keys.auth,
+          userAgent: input.userAgent ?? null,
+        },
+      });
+    },
+
+    async remove(userId, endpoint) {
+      const client = await db();
+      await client.pushSubscription.deleteMany({ where: { userId, endpoint } });
+    },
+
+    async count(userId) {
+      const client = await db();
+      return client.pushSubscription.count({ where: { userId } });
+    },
+
+    async isRegisteredTo(userId, endpoint) {
+      const client = await db();
+      const row = await client.pushSubscription.findUnique({ where: { endpoint } });
+      return row?.userId === userId;
+    },
+
+    async list(userId) {
+      const client = await db();
+      const rows = await client.pushSubscription.findMany({ where: { userId } });
+      return rows.map((row) => ({
+        id: row.id,
+        endpoint: row.endpoint,
+        p256dh: row.p256dh,
+        auth: row.auth,
+      }));
+    },
+
+    async prune(id) {
+      const client = await db();
+      await client.pushSubscription.delete({ where: { id } });
+    },
+  };
+}

package/src/server/router.ts

@@ -0,0 +1,275 @@
+import { UnknownNotificationRecipientError } from '../errors';
+import type { NotificationGeneratorRegistry } from '../generators';
+import { DEFAULT_CHANNEL_ROW, enabledChannelsOf } from '../preferences-core';
+import type { NotificationChannel, NotificationEvent, TransportRecipient } from '../types';
+
+import {
+  dispatchOne,
+  drainPending,
+  loadRecipient,
+  DEFAULT_SWEEP_CUTOFF_MS,
+  DEFAULT_SWEEP_TAKE,
+  type NotificationDispatchDeps,
+} from './dispatch';
+import type { NotificationPreferenceStore } from './preferences';
+
+/**
+ * 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.
+ */
+export type NotificationChannelPolicy = (
+  clientId: string,
+  channels: readonly NotificationChannel[],
+) => Promise<NotificationChannel[]> | NotificationChannel[];
+
+/** How the host defers dispatch of one already-committed notification. */
+export type NotificationDispatchScheduler = (notificationId: string) => Promise<void>;
+
+/** One committed inbox record, as the commit observer sees it. */
+export 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.
+ */
+export type NotificationCommittedListener = (notification: CommittedNotification) => void;
+
+/** Options for `notify`. */
+export 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). */
+export interface NotifyResult {
+  notificationId: string;
+  /** Channels a delivery row was enqueued for (preference ∩ transport gate). */
+  channels: NotificationChannel[];
+}
+
+interface NotificationRouterDeps extends NotificationDispatchDeps {
+  generators: NotificationGeneratorRegistry;
+  preferences: NotificationPreferenceStore;
+  channelPolicy?: NotificationChannelPolicy;
+  scheduleDispatch?: NotificationDispatchScheduler;
+  onCommitted?: NotificationCommittedListener;
+}
+
+export interface NotificationRouter {
+  notify<TPayload>(
+    event: NotificationEvent<TPayload>,
+    options?: NotifyOptions,
+  ): Promise<NotifyResult>;
+  dispatchDeliveries(notificationId: string): Promise<void>;
+  drainPending(olderThanMs?: number, take?: number): Promise<{ dispatched: number }>;
+}
+
+/**
+ * The channels that survive a plan gate this package could not consult.
+ *
+ * A policy error degrades to the FREE defaults (`DEFAULT_CHANNEL_ROW`, i.e.
+ * e-mail + web push) intersected with what the other gates allowed — not to
+ * everything. Failing fully open was the original reading, and the rationale
+ * given for it only ever argued for the free channels: the dunning e-mail this
+ * system carries is how payment gets collected, so a transient entitlements
+ * error must not silence it. That argument says nothing about SMS and WhatsApp,
+ * which are billed per message and are exactly what the host's own gate was
+ * about to refuse. So the free channels stay (an extra notification beats none)
+ * and the paid ones do not (the host is not billed for a channel it did not
+ * authorize).
+ */
+function policyFallback(channels: NotificationChannel[]): NotificationChannel[] {
+  const free = new Set(enabledChannelsOf(DEFAULT_CHANNEL_ROW));
+  return channels.filter((channel) => free.has(channel));
+}
+
+/** Apply the host's policy, degrading to the free channels on an error. */
+async function applyPolicy(
+  deps: NotificationRouterDeps,
+  clientId: string | null | undefined,
+  channels: NotificationChannel[],
+): Promise<NotificationChannel[]> {
+  if (!deps.channelPolicy || clientId === null || clientId === undefined) return channels;
+  try {
+    return await deps.channelPolicy(clientId, channels);
+  } catch (error) {
+    deps.logger.error(
+      `[notifications] channelPolicy failed for client ${clientId}; ` +
+        'degrading to the free channels:',
+      error,
+    );
+    return policyFallback(channels);
+  }
+}
+
+/** Run the commit observer without ever letting it reach the caller. */
+function announce(deps: NotificationRouterDeps, notification: CommittedNotification): void {
+  if (!deps.onCommitted) return;
+  try {
+    deps.onCommitted(notification);
+  } catch (error) {
+    // An observer is an accelerator, never a step. The row is committed; a
+    // listener that throws must not turn a delivered notification into a 500.
+    deps.logger.error(
+      `[notifications] commit listener failed for ${notification.notificationId}:`,
+      error,
+    );
+  }
+}
+
+/** The channels one emit will actually enqueue: preference ∩ transport ∩ plan. */
+async function resolveChannels(
+  deps: NotificationRouterDeps,
+  event: NotificationEvent<unknown>,
+  category: string,
+  recipient: TransportRecipient,
+): Promise<NotificationChannel[]> {
+  const enabled = await deps.preferences.enabledChannels(event.recipient.userId, category);
+  const supported = enabled.filter((channel) => {
+    const transport = deps.transports.get(channel);
+    return transport !== null && transport.supports(recipient);
+  });
+  // The host's plan gate: a tenant-scoped emit keeps only the channels the
+  // tenant's plan covers, so a revoked transport DEGRADES to the remaining ones
+  // rather than dropping the notification silently.
+  return applyPolicy(deps, event.recipient.clientId, supported);
+}
+
+/** Commit the inbox record and its delivery rows together, in one transaction. */
+async function commit(
+  deps: NotificationRouterDeps,
+  event: NotificationEvent<unknown>,
+  category: string,
+  content: { title: string; body: string; link?: string; data?: Record<string, unknown> },
+  channels: NotificationChannel[],
+): Promise<{ id: string; userId: string; clientId: string | null }> {
+  const client = await deps.db();
+  return client.$transaction(async (tx) => {
+    const created = await tx.notification.create({
+      data: {
+        userId: event.recipient.userId,
+        clientId: event.recipient.clientId ?? null,
+        type: event.type,
+        category,
+        title: content.title,
+        body: content.body,
+        link: content.link ?? null,
+        data: content.data ?? {},
+      },
+    });
+    if (channels.length > 0) {
+      await tx.notificationDelivery.createMany({
+        data: channels.map((channel) => ({ notificationId: created.id, channel })),
+        // Idempotence backstop: the unique (notification, channel) key.
+        skipDuplicates: true,
+      });
+    }
+    return created;
+  });
+}
+
+export function createNotificationRouter(deps: NotificationRouterDeps): NotificationRouter {
+  return {
+    dispatchDeliveries: async (notificationId) => {
+      await dispatchOne(deps, notificationId);
+    },
+    drainPending: (olderThanMs = DEFAULT_SWEEP_CUTOFF_MS, take = DEFAULT_SWEEP_TAKE) =>
+      drainPending(deps, olderThanMs, take),
+
+    async notify(event, options = {}) {
+      const generator = deps.generators.resolve(event.type);
+      const content = generator.generate(event.payload as never);
+
+      const recipient = await loadRecipient(deps, event.recipient.userId);
+      if (!recipient) throw new UnknownNotificationRecipientError(event.recipient.userId);
+
+      const channels = await resolveChannels(deps, event, generator.category, recipient);
+      const notification = await commit(deps, event, generator.category, content, channels);
+
+      // AFTER the transaction, never inside it: a subscriber woken by an event
+      // published mid-transaction would re-read and not find the row it was told
+      // about — the classic read-your-own-hint race.
+      announce(deps, {
+        notificationId: notification.id,
+        userId: notification.userId,
+        clientId: notification.clientId,
+      });
+
+      // `sync` always means "send it here, now" — a test or a worker about to
+      // exit must not have its send handed to a queue it will never drain.
+      if (options.sync) {
+        await dispatchOne(deps, notification.id);
+        return { notificationId: notification.id, channels };
+      }
+
+      void (
+        deps.scheduleDispatch
+          ? deps.scheduleDispatch(notification.id)
+          : dispatchOne(deps, notification.id)
+      ).catch((error: unknown) => {
+        // Detached-path backstop only: per-delivery failures are already
+        // recorded on their rows; this catches infrastructure errors.
+        deps.logger.error(`[notifications] dispatch failed for ${notification.id}:`, error);
+      });
+
+      return { notificationId: notification.id, channels };
+    },
+  };
+}

package/src/server/routes.ts

@@ -0,0 +1,218 @@
+import type { NotificationMessages } from '../messages';
+import { NOTIFICATION_CHANNELS, type NotificationChannel } from '../types';
+
+import {
+  guarded,
+  ok,
+  parseDeleteBody,
+  parseListQuery,
+  parseMarkReadBody,
+  parsePreferencesBody,
+  parsePushEndpointBody,
+  parsePushEndpointQuery,
+  parsePushSubscriptionBody,
+  type NotificationsRoute,
+} from './context';
+import type { NotificationContactDirectory } from './db';
+import type { NotificationInboxStore } from './inbox';
+import type { NotificationPreferenceStore } from './preferences';
+import type { PushSubscriptionStore } from './push-subscriptions';
+import type { TransportRegistry } from './transports/registry';
+
+/**
+ * The endpoints, as framework-neutral descriptors (12-15).
+ *
+ * Nine routes, and the paths are the PACKAGE's: the shipped react client
+ * builds these URLs, so a host that renamed one would be a host whose own bell
+ * stopped working. The host names only where the whole block is mounted
+ * (future-pay: `/api/account`).
+ *
+ * Route ORDER is preserved by every adapter. Nothing here is shaped `/:id`, so
+ * no sibling can capture a literal — but the order is still the contract,
+ * because that is what a host mounting an `/:id` route of its own under the
+ * same prefix has to reason about.
+ */
+
+interface NotificationRoutesDeps {
+  inbox: NotificationInboxStore;
+  preferences: NotificationPreferenceStore;
+  pushSubscriptions: PushSubscriptionStore;
+  transports: TransportRegistry;
+  contacts: NotificationContactDirectory;
+  categories: readonly string[];
+  messages: NotificationMessages;
+  /** Told when a write actually changed something (for a realtime hint). */
+  onInboxChanged?: (userId: string) => void;
+}
+
+/**
+ * Whether each channel CAN reach this user right now — destination on file and
+ * the channel declared — so the settings UI can disable dead toggles with a
+ * hint (no phone → SMS/WhatsApp off).
+ *
+ * Web push is probed with a HYPOTHETICAL subscription: for the SETTINGS screen
+ * the channel is "available" when the platform can send at all, because the
+ * browser subscribe step happens right from that toggle. Requiring an existing
+ * subscription here would deadlock the UX.
+ */
+async function channelAvailability(
+  deps: NotificationRoutesDeps,
+  userId: string,
+): Promise<Record<NotificationChannel, boolean>> {
+  const contact = await deps.contacts.getContact(userId);
+  const recipient = {
+    userId,
+    email: contact?.email ?? null,
+    phone: contact?.phone ?? null,
+    pushSubscriptionCount: 1,
+  };
+  return Object.fromEntries(
+    NOTIFICATION_CHANNELS.map((channel) => [
+      channel,
+      deps.transports.get(channel)?.supports(recipient) ?? false,
+    ]),
+  ) as Record<NotificationChannel, boolean>;
+}
+
+/** The `{ preferences, availability, categories }` payload both prefs routes answer. */
+async function preferencesPayload(
+  deps: NotificationRoutesDeps,
+  userId: string,
+): Promise<{
+  preferences: Record<string, Record<string, boolean>>;
+  availability: Record<NotificationChannel, boolean>;
+  categories: string[];
+}> {
+  const [preferences, availability] = await Promise.all([
+    deps.preferences.get(userId),
+    channelAvailability(deps, userId),
+  ]);
+  // `categories` travels with the matrix so the settings screen renders the
+  // HOST's taxonomy without being told it twice (once in the api config, once
+  // in the web config) — the two could then disagree.
+  return { preferences, availability, categories: [...deps.categories] };
+}
+
+function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
+  return [
+    {
+      method: 'GET',
+      path: '/notifications',
+      handle: guarded(async ({ actor, query }) =>
+        ok(await deps.inbox.list(actor.userId, parseListQuery(query, deps.messages))),
+      ),
+    },
+    {
+      method: 'GET',
+      path: '/notifications/unread-count',
+      handle: guarded(async ({ actor }) =>
+        // Polled by the SPAs, so it stays a single indexed COUNT.
+        ok({ count: await deps.inbox.unreadCount(actor.userId) }),
+      ),
+    },
+    {
+      method: 'POST',
+      path: '/notifications/mark-read',
+      handle: guarded(async ({ actor, body }) => {
+        const target = parseMarkReadBody(body, deps.messages);
+        const updated =
+          'all' in target
+            ? await deps.inbox.markAllRead(actor.userId)
+            : await deps.inbox.markRead(actor.userId, target.ids);
+        // Only when something actually flipped. This endpoint is idempotent, so
+        // a re-send of an already-read id reports `updated: 0` and has changed
+        // nothing — hinting on that would wake every one of this user's devices
+        // to re-read a badge that did not move.
+        if (updated > 0) deps.onInboxChanged?.(actor.userId);
+        return ok({ updated });
+      }),
+    },
+    {
+      method: 'POST',
+      // POST, not DELETE, because the ids travel in a JSON body.
+      path: '/notifications/delete',
+      handle: guarded(async ({ actor, body }) => {
+        const deleted = await deps.inbox.softDelete(
+          actor.userId,
+          parseDeleteBody(body, deps.messages),
+        );
+        // Same rule as mark-read. A delete can move the badge too — an UNREAD
+        // row that is removed takes its place in the count with it.
+        if (deleted > 0) deps.onInboxChanged?.(actor.userId);
+        return ok({ deleted });
+      }),
+    },
+  ];
+}
+
+function preferenceRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
+  return [
+    {
+      method: 'GET',
+      path: '/notification-preferences',
+      handle: guarded(async ({ actor }) => ok(await preferencesPayload(deps, actor.userId))),
+    },
+    {
+      method: 'PUT',
+      path: '/notification-preferences',
+      handle: guarded(async ({ actor, body }) => {
+        // The dispatch pipeline reads these on every emit, so a save takes
+        // effect immediately — no cache to invalidate.
+        await deps.preferences.save(actor.userId, parsePreferencesBody(body, deps.messages));
+        return ok(await preferencesPayload(deps, actor.userId));
+      }),
+    },
+  ];
+}
+
+function pushRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
+  return [
+    {
+      method: 'GET',
+      path: '/push-subscriptions',
+      handle: guarded(async ({ actor, query }) => {
+        const endpoint = parsePushEndpointQuery(query, deps.messages);
+        return ok({
+          // null = web push is not configured on this deployment.
+          vapidPublicKey: deps.transports.webPushPublicKey(),
+          count: await deps.pushSubscriptions.count(actor.userId),
+          // Only when asked. `registered` is what lets the settings screen stop
+          // trusting the browser alone: a re-owned or pruned row answers false,
+          // so the screen offers *Ativar* again instead of claiming all is well.
+          ...(endpoint !== undefined
+            ? { registered: await deps.pushSubscriptions.isRegisteredTo(actor.userId, endpoint) }
+            : {}),
+        });
+      }),
+    },
+    {
+      method: 'POST',
+      path: '/push-subscriptions',
+      handle: guarded(async ({ actor, body, headers }) => {
+        const input = parsePushSubscriptionBody(body, deps.messages);
+        const userAgent = headers?.['user-agent'];
+        await deps.pushSubscriptions.save(actor.userId, {
+          ...input,
+          ...(userAgent ? { userAgent } : {}),
+        });
+        return ok({ count: await deps.pushSubscriptions.count(actor.userId) });
+      }),
+    },
+    {
+      method: 'DELETE',
+      // The endpoint is a long opaque URL, unusable as a path param.
+      path: '/push-subscriptions',
+      handle: guarded(async ({ actor, body }) => {
+        await deps.pushSubscriptions.remove(
+          actor.userId,
+          parsePushEndpointBody(body, deps.messages),
+        );
+        return ok({ count: await deps.pushSubscriptions.count(actor.userId) });
+      }),
+    },
+  ];
+}
+
+export function notificationRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
+  return [...inboxRoutes(deps), ...preferenceRoutes(deps), ...pushRoutes(deps)];
+}