@12-apps/notifications 1.0.0

package/src/server/transports/whatsapp.ts

@@ -0,0 +1,183 @@
+import type {
+  NotificationContent,
+  NotificationLogger,
+  NotificationTransport,
+} from '../../types';
+
+import {
+  absoluteLink,
+  phoneChannel,
+  postOrThrow,
+  resolveDriver,
+  type DriverDeclarationBase,
+} from './drivers';
+
+/**
+ * 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. */
+export 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];
+}
+
+export interface WhatsAppDriver {
+  send(toE164: string, message: WhatsAppMessage): Promise<void>;
+}
+
+export interface WhatsAppDriverDeclaration extends DriverDeclarationBase {
+  channel: 'WHATSAPP';
+  accessToken?: string;
+  phoneNumberId?: string;
+  templateName?: string;
+  /** Default `pt_BR`. */
+  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;
+}
+
+const DEFAULT_GRAPH_API_BASE = 'https://graph.facebook.com/v20.0';
+
+function templatePayload(
+  toDigits: string,
+  message: WhatsAppMessage,
+  declaration: WhatsAppDriverDeclaration,
+): object {
+  return {
+    messaging_product: 'whatsapp',
+    to: toDigits,
+    type: 'template',
+    template: {
+      name: declaration.templateName,
+      language: { code: declaration.templateLanguage ?? 'pt_BR' },
+      components: [
+        {
+          type: 'body',
+          parameters: message.templateParameters.map((text) => ({ type: 'text', text })),
+        },
+      ],
+    },
+  };
+}
+
+function textPayload(toDigits: string, message: WhatsAppMessage): object {
+  return {
+    messaging_product: 'whatsapp',
+    to: toDigits,
+    type: 'text',
+    text: { body: message.text },
+  };
+}
+
+const metaDriver = (declaration: WhatsAppDriverDeclaration): WhatsAppDriver => ({
+  async send(toE164, message) {
+    if (!declaration.accessToken || !declaration.phoneNumberId) {
+      throw new Error('The meta whatsapp driver needs `accessToken` and `phoneNumberId`.');
+    }
+    // The Cloud API addresses recipients by bare digits (no `+`).
+    const toDigits = toE164.replace('+', '');
+    const payload = declaration.templateName
+      ? templatePayload(toDigits, message, declaration)
+      : textPayload(toDigits, message);
+    const base = declaration.graphApiBase ?? DEFAULT_GRAPH_API_BASE;
+    await postOrThrow(
+      'WhatsApp Cloud API',
+      declaration.fetchImpl,
+      `${base}/${encodeURIComponent(declaration.phoneNumberId)}/messages`,
+      {
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${declaration.accessToken}`,
+        },
+        body: JSON.stringify(payload),
+      },
+    );
+  },
+});
+
+const logWhatsAppDriver = (declaration: WhatsAppDriverDeclaration): WhatsAppDriver => ({
+  // Deliberately logs NO destination — a phone number is PII and must never
+  // reach logs; the message text alone is enough for local debugging.
+  send(_toE164, message) {
+    declaration.logger?.info(
+      `[notifications:whatsapp] log driver suppressed a real send (text="${message.text}")`,
+    );
+    return Promise.resolve();
+  },
+});
+
+export const WHATSAPP_DRIVERS: Record<
+  string,
+  (declaration: WhatsAppDriverDeclaration) => WhatsAppDriver
+> = {
+  meta: metaDriver,
+  log: logWhatsAppDriver,
+};
+
+/** Agnostic content → WhatsApp text + template parameters. */
+export function formatWhatsApp(
+  content: NotificationContent,
+  declaration: WhatsAppDriverDeclaration,
+): WhatsAppMessage {
+  const lines = [`*${content.title}*`, '', content.body];
+  const href = absoluteLink(content.link, declaration.appUrl);
+  if (href) lines.push('', href);
+  return { text: lines.join('\n'), templateParameters: [content.title, content.body] };
+}
+
+export function whatsAppTransport(
+  declaration: WhatsAppDriverDeclaration,
+  extraDrivers: Record<string, (d: WhatsAppDriverDeclaration) => WhatsAppDriver> = {},
+  logger?: NotificationLogger,
+): NotificationTransport<WhatsAppMessage> {
+  const driver = resolveDriver('WHATSAPP', declaration, {
+    ...WHATSAPP_DRIVERS,
+    ...extraDrivers,
+  });
+  if (!declaration.templateName) {
+    // Not a throw: free-form IS correct for a host that only replies inside the
+    // 24h window. It is a warning because the other reading — business-initiated
+    // alerts with no template — is a channel that never delivers anything.
+    logger?.error(
+      '[notifications] WHATSAPP is declared with no `templateName`: only free-form ' +
+        'replies inside the 24h customer-service window will be accepted, and every ' +
+        'business-initiated send will be rejected by the Graph API.',
+    );
+  }
+  return phoneChannel<WhatsAppMessage>('WHATSAPP', {
+    defaultCountryCode: declaration.defaultCountryCode,
+    format: (content) => formatWhatsApp(content, declaration),
+    send: (toE164, message) => driver.send(toE164, message),
+  });
+}

package/src/types.ts

@@ -0,0 +1,158 @@
+/**
+ * Core types of the channel-agnostic notification system (12-15).
+ *
+ * Three decoupled layers, each open for extension without touching the others:
+ *   - GENERATORS map a typed domain event to agnostic content (title/body/…).
+ *   - The CHANNEL ROUTER always writes the notification-centre inbox record,
+ *     then fans out one delivery per enabled channel.
+ *   - TRANSPORTS format the agnostic content for one channel and send it.
+ *
+ * Nothing here knows about a concrete channel's wire format — that lives
+ * entirely inside each transport adapter — and nothing here knows about a
+ * concrete DOMAIN either: the event `type` set, the preference categories and
+ * the channel list are all host config (see {@link NotificationTaxonomy}).
+ */
+
+/** Transport channels a notification can fan out to (DB CHECK mirrors this). */
+export const NOTIFICATION_CHANNELS = ['EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'] as const;
+export type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];
+
+/**
+ * The DEFAULT preference categories — the granularity at which a user chooses
+ * channels. Every notification `type` belongs to exactly one category via its
+ * generator.
+ *
+ * A host may replace the set entirely (`categories` on the server config): it
+ * is product vocabulary, not machinery. These four are the future-pay set, and
+ * the packaged migration deliberately puts **no CHECK** on
+ * `notifications.category` — a closed set in the schema would be wrong for
+ * every host but the first. Unlike `channel` and `status`, which ARE the
+ * library's own closed sets and do carry one.
+ */
+export const NOTIFICATION_CATEGORIES = ['orders', 'payments', 'stock', 'system'] as const;
+export type NotificationCategory = string;
+
+/**
+ * Per-channel delivery lifecycle (DB CHECK mirrors this).
+ *
+ * `SENDING` is the CLAIM: exactly one dispatcher moves a row out of `QUEUED`,
+ * so two dispatchers can never both send the same delivery. A row left
+ * `SENDING` is a dispatcher that died mid-send, and the sweep reclaims it once
+ * it is older than the cutoff.
+ *
+ * `DEAD` is terminal: the attempt ceiling was reached (or the recipient no
+ * longer exists), and no sweep will pick the row up again. Without it a
+ * permanently invalid destination is a billed provider call on every sweep,
+ * forever, and the sweep's working set only grows.
+ */
+export type DeliveryStatus = 'QUEUED' | 'SENDING' | 'SENT' | 'FAILED' | 'DEAD';
+
+/**
+ * Channel-agnostic content a generator produces. This is what the inbox stores
+ * verbatim and what every transport's formatter receives — no channel may leak
+ * its wire format into it.
+ */
+export interface NotificationContent {
+  title: string;
+  body: string;
+  /** In-app deep link (a same-origin path such as `/orders/123`). */
+  link?: string;
+  /** Structured extras for consumers that want more than text. */
+  data?: Record<string, unknown>;
+}
+
+/** Who receives a notification. `clientId` scopes it to a tenant when set. */
+export interface NotificationRecipient {
+  userId: string;
+  clientId?: string;
+}
+
+/**
+ * A typed domain event handed to `notify`. `type` selects the registered
+ * generator; `payload` is that generator's typed input. Callers never touch
+ * channels, formatting, or preferences.
+ */
+export interface NotificationEvent<TPayload = unknown> {
+  type: string;
+  recipient: NotificationRecipient;
+  payload: TPayload;
+}
+
+/**
+ * Maps one domain event type to agnostic content. Registered through the
+ * server config (or `registerGenerator` for a late arrival); adding a
+ * generator never touches existing generators, the router, or any transport
+ * (open/closed).
+ */
+export interface NotificationGenerator<TPayload = unknown> {
+  /** The event key, dot-namespaced ("order.paid"). One generator per type. */
+  type: string;
+  /** The preference category the router gates this type's fan-out on. */
+  category: NotificationCategory;
+  generate: (payload: TPayload) => NotificationContent;
+}
+
+/**
+ * The recipient as a transport sees them: resolved destinations only. Built by
+ * the router from the host's contact directory + the push subscriptions this
+ * package owns; transports use it to answer
+ * {@link NotificationTransport.supports}.
+ */
+export interface TransportRecipient {
+  userId: string;
+  email: string | null;
+  /** Phone as the host stores it (transports normalize per provider rules). */
+  phone: string | null;
+  /** How many active browser push subscriptions the user holds. */
+  pushSubscriptionCount: number;
+}
+
+/**
+ * One pluggable channel adapter: a FORMATTER (agnostic content → channel
+ * message) plus a SENDER. Adding a channel = registering one of these; the
+ * router dispatches through the registry and needs no change.
+ *
+ * `send` resolves on success and THROWS on failure — the router records the
+ * error on the delivery row and isolates it from other channels. Sends must be
+ * retry-safe: the router may re-dispatch a QUEUED/FAILED delivery.
+ */
+export interface NotificationTransport<TMessage = unknown> {
+  channel: NotificationChannel;
+  /**
+   * Whether this recipient is addressable on this channel right now — the
+   * destination exists (e-mail / phone / push subscription) AND the provider
+   * is configured. `false` simply skips the channel (no delivery row).
+   */
+  supports(recipient: TransportRecipient): boolean;
+  /** Transform the agnostic content into this channel's message shape. */
+  format(content: NotificationContent): TMessage;
+  /** Deliver the formatted message to the recipient. Throws on failure. */
+  send(message: TMessage, recipient: TransportRecipient): Promise<void>;
+}
+
+/**
+ * The host's product vocabulary. Everything below the surface (routing,
+ * delivery rows, retries, the wire) is identical for every host; WHICH
+ * categories exist and how they are labelled is not.
+ */
+export interface NotificationTaxonomy {
+  /** The preference categories, in the order the settings screen lists them. */
+  categories: readonly NotificationCategory[];
+}
+
+/** The taxonomy in force, defaulted to the four future-pay categories. */
+export function taxonomyOf(config: {
+  categories?: readonly NotificationCategory[];
+}): NotificationTaxonomy {
+  const categories = config.categories ?? NOTIFICATION_CATEGORIES;
+  if (categories.length === 0) {
+    throw new Error('@12-apps/notifications: `categories` must not be empty.');
+  }
+  return { categories: [...categories] };
+}
+
+/** The host's logger. Defaults to the console (the @12-apps/jobs precedent). */
+export interface NotificationLogger {
+  info(message: string, ...meta: unknown[]): void;
+  error(message: string, ...meta: unknown[]): void;
+}

package/src/web-push/index.ts

@@ -0,0 +1,70 @@
+import webpush from 'web-push';
+
+import type { WebPushSender, WebPushSubscription } from '../server/transports/web-push';
+
+/**
+ * `@12-apps/notifications/web-push` — the VAPID sender, behind its own subpath.
+ *
+ * VAPID signing and RFC 8291 payload encryption need the `web-push` package: a
+ * node-only dependency with its own crypto surface, which a host that never
+ * turns the channel on must not be made to install. So it is an OPTIONAL peer
+ * reached only through this subpath — the same arrangement `./hono` has, and the
+ * same reason `@12-apps/payments-backend` keeps its adapters off its root entry.
+ * Neither the root entry nor `./server` imports this file, so a bundle that
+ * never mentions web push never resolves `web-push`.
+ *
+ * The host's whole wiring:
+ *
+ *     import { vapidPushSender } from '@12-apps/notifications/web-push';
+ *
+ *     transports: [
+ *       {
+ *         channel: 'WEB_PUSH',
+ *         driver: 'vapid',
+ *         publicKey: env.VAPID_PUBLIC_KEY,
+ *         sender: vapidPushSender({
+ *           subject: env.VAPID_SUBJECT,
+ *           publicKey: env.VAPID_PUBLIC_KEY,
+ *           privateKey: env.VAPID_PRIVATE_KEY,
+ *         }),
+ *       },
+ *     ]
+ *
+ * Generate the key pair once with `npx web-push generate-vapid-keys`; `subject`
+ * is the `mailto:` or https contact URL the push services require.
+ */
+
+export interface VapidPushSenderConfig {
+  /** `mailto:ops@example.com` or an https contact URL. */
+  subject: string;
+  publicKey: string;
+  privateKey: string;
+}
+
+/**
+ * A signer for the WEB_PUSH transport.
+ *
+ * Errors pass through UNWRAPPED, and that is load-bearing: `web-push` rejects
+ * with an error carrying `statusCode`, and the transport reads it to tell a GONE
+ * subscription (404/410, prune it) from a transient failure (keep it, record the
+ * error, retry on the next sweep). Wrapping the error would turn the prune into
+ * a no-op and let dead subscriptions accumulate forever.
+ */
+export function vapidPushSender(config: VapidPushSenderConfig): WebPushSender {
+  if (!config.subject || !config.publicKey || !config.privateKey) {
+    throw new Error(
+      'vapidPushSender() needs `subject`, `publicKey` and `privateKey` — a partially ' +
+        'configured signer would fail on the first real send instead of at boot.',
+    );
+  }
+  return async (subscription: WebPushSubscription, payload: string): Promise<void> => {
+    // Set per send rather than once at module load: a process may hold two
+    // mounts (a platform sender and a tenant sender), and `web-push` keeps the
+    // details in module state.
+    webpush.setVapidDetails(config.subject, config.publicKey, config.privateKey);
+    await webpush.sendNotification(
+      { endpoint: subscription.endpoint, keys: subscription.keys },
+      payload,
+    );
+  };
+}

package/src/wire.ts

@@ -0,0 +1,62 @@
+/**
+ * The inbox WIRE shape — the one contract the two halves share.
+ *
+ * It lives in the root entry rather than in `./server` or `./react` because
+ * both halves need it and neither owns it: the api serializes to it, the panel
+ * deserializes from it, and a change here is a change to both at once. That is
+ * the same reason the response envelope and the route paths are the package's
+ * and not the host's.
+ */
+
+/** One inbox entry as the notification centre renders it. */
+export interface InboxNotification {
+  id: string;
+  type: string;
+  category: string;
+  title: string;
+  body: string;
+  link: string | null;
+  data: Record<string, unknown>;
+  /** ISO-8601, or null while unread. */
+  readAt: string | null;
+  /** ISO-8601. */
+  createdAt: string;
+}
+
+/** One page of the owner's inbox. */
+export interface ListNotificationsResult {
+  items: InboxNotification[];
+  /** Cursor for the next page, or null when this page is the last. */
+  nextCursor: string | null;
+}
+
+/** A stored notification row, as the db seam hands it back. */
+export interface NotificationRow {
+  id: string;
+  userId: string;
+  clientId: string | null;
+  type: string;
+  category: string;
+  title: string;
+  body: string;
+  link: string | null;
+  data: unknown;
+  readAt: Date | null;
+  deletedAt: Date | null;
+  createdAt: Date;
+}
+
+/** Row → wire. Dates become ISO strings; a null `data` becomes `{}`. */
+export function inboxWire(row: NotificationRow): InboxNotification {
+  return {
+    id: row.id,
+    type: row.type,
+    category: row.category,
+    title: row.title,
+    body: row.body,
+    link: row.link,
+    data: (row.data ?? {}) as Record<string, unknown>,
+    readAt: row.readAt ? row.readAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}