@12-apps/notifications 1.0.0

package/src/server/create-api-notifications.ts

@@ -0,0 +1,215 @@
+import { createGeneratorRegistry, type NotificationGeneratorRegistry } from '../generators';
+import { messagesOf, type NotificationMessages } from '../messages';
+import type { ChannelRow } from '../preferences-core';
+import {
+  taxonomyOf,
+  type NotificationCategory,
+  type NotificationGenerator,
+  type NotificationLogger,
+} from '../types';
+
+import {
+  createNotifyByPermission,
+  type NotificationAudienceDirectory,
+  type NotifyByPermission,
+} from './by-permission';
+import type { NotificationsRoute } from './context';
+import type { NotificationContactDirectory, NotificationsDbProvider } from './db';
+import { DEFAULT_MAX_DELIVERY_ATTEMPTS } from './dispatch';
+import { createInboxStore, type NotificationInboxStore } from './inbox';
+import { createPreferenceStore, type NotificationPreferenceStore } from './preferences';
+import {
+  createPushSubscriptionStore,
+  type PushSubscriptionStore,
+} from './push-subscriptions';
+import { notificationRoutes } from './routes';
+import {
+  createNotificationRouter,
+  type NotificationChannelPolicy,
+  type NotificationCommittedListener,
+  type NotificationDispatchScheduler,
+  type NotificationRouter,
+} from './router';
+import {
+  createTransportRegistry,
+  type ExtraDrivers,
+  type TransportDeclaration,
+  type TransportRegistry,
+} from './transports/registry';
+
+/**
+ * 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.
+ */
+
+export 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. Default: orders / payments / stock / system. */
+  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?: Partial<NotificationMessages>;
+  /** The host's logger. Defaults to the console. */
+  logger?: NotificationLogger;
+}
+
+export 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: NotificationMessages;
+}
+
+/** Drop the keys the host left unset, so an absent seam stays absent. */
+function present<T extends object>(entries: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(entries).filter(([, value]) => value !== undefined),
+  ) as Partial<T>;
+}
+
+/** Fallback logger — used until the host passes its own. */
+const consoleLogger: NotificationLogger = {
+  info: (message, ...meta) => console.info(message, ...meta),
+  error: (message, ...meta) => console.error(message, ...meta),
+};
+
+export function createApiNotifications(config: NotificationsServerConfig): ApiNotifications {
+  const messages = messagesOf(config);
+  const taxonomy = taxonomyOf(config);
+  const logger = config.logger ?? consoleLogger;
+
+  const generators = createGeneratorRegistry(config.generators ?? []);
+  const inbox = createInboxStore(config.db);
+  const preferences = createPreferenceStore(
+    config.db,
+    taxonomy,
+    config.channelDefaults ?? {},
+  );
+  const pushSubscriptions = createPushSubscriptionStore(config.db, logger);
+  const transports = createTransportRegistry(
+    config.transports ?? [],
+    pushSubscriptions,
+    config.drivers ?? {},
+    logger,
+  );
+
+  const router = createNotificationRouter({
+    db: config.db,
+    generators,
+    transports,
+    preferences,
+    pushSubscriptions,
+    contacts: config.contacts,
+    logger,
+    maxAttempts: config.maxDeliveryAttempts ?? DEFAULT_MAX_DELIVERY_ATTEMPTS,
+    // `exactOptionalPropertyTypes` is on, so an absent host seam must be an
+    // ABSENT key rather than an explicit `undefined`.
+    ...present({
+      channelPolicy: config.channelPolicy,
+      scheduleDispatch: config.scheduleDispatch,
+      onCommitted: config.onCommitted,
+    }),
+  });
+
+  const audience = config.audience;
+  const notifyByPermission: NotifyByPermission = audience
+    ? createNotifyByPermission({ router, directory: audience, logger })
+    : () =>
+        Promise.reject(
+          new Error(
+            'notifyByPermission() needs an `audience` directory — pass the host authorization ' +
+              'engine to createApiNotifications({ audience }).',
+          ),
+        );
+
+  return {
+    routes: notificationRoutes({
+      inbox,
+      preferences,
+      pushSubscriptions,
+      transports,
+      contacts: config.contacts,
+      categories: taxonomy.categories,
+      messages,
+      ...present({ onInboxChanged: config.onInboxChanged }),
+    }),
+    notify: router.notify,
+    dispatchDeliveries: router.dispatchDeliveries,
+    drainPending: router.drainPending,
+    notifyByPermission,
+    inbox,
+    preferences,
+    pushSubscriptions,
+    registerGenerator: generators.register,
+    transports,
+    messages,
+  };
+}

package/src/server/db.ts

@@ -0,0 +1,252 @@
+/**
+ * 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. future-pay'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.
+ */
+
+import type { DeliveryStatus, NotificationChannel } from '../types';
+import type { NotificationRow } from '../wire';
+
+// ---------------------------------------------------------------------------
+// notifications
+// ---------------------------------------------------------------------------
+
+export 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.
+ */
+export interface NotificationPageAfter {
+  createdAt: Date;
+  id: string;
+}
+
+/** The inbox read filter. `deletedAt: null` is on every read, always. */
+export 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 } }];
+}
+
+export 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 }>;
+}
+
+// ---------------------------------------------------------------------------
+// notification_deliveries
+// ---------------------------------------------------------------------------
+
+export 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.
+ */
+export interface NotificationDeliveryWhere {
+  id?: string;
+  notificationId?: string;
+  status?: DeliveryStatus | { in: DeliveryStatus[] };
+  updatedAt?: { lt: Date };
+}
+
+export 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 }>;
+}
+
+// ---------------------------------------------------------------------------
+// notification_preferences
+// ---------------------------------------------------------------------------
+
+export interface NotificationPreferenceRow {
+  id: string;
+  userId: string;
+  category: string;
+  channels: unknown;
+}
+
+export 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>;
+}
+
+// ---------------------------------------------------------------------------
+// push_subscriptions
+// ---------------------------------------------------------------------------
+
+export interface PushSubscriptionRow {
+  id: string;
+  userId: string;
+  endpoint: string;
+  p256dh: string;
+  auth: string;
+  userAgent: string | null;
+}
+
+export 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 client
+// ---------------------------------------------------------------------------
+
+/** The model delegates — what both a live client and a transaction expose. */
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export interface NotificationContactDirectory {
+  getContact(userId: string): Promise<{ email: string | null; phone: string | null } | null>;
+}