@marktiderman/genesis-notifications 0.0.0-stage → 0.1.0

package/src/server/secret-links.ts

@@ -0,0 +1,53 @@
+/**
+ * Secret links: a link whose query is a credential (a one-time sign-in, an
+ * invite, a response's edit link). They never go in `notifications.data` or
+ * a push. The domain stores a reference (`{ response_id }`) and, for a token
+ * that exists only hashed, passes the plaintext as `notify({ secret })`; the
+ * runner builds the link at send time, for the email only.
+ */
+
+/** What a secret link is built from. */
+export interface SecretLinkRef {
+  /** The notification's `data` (references, never secrets). */
+  data: Record<string, unknown>;
+  /** The plaintext from `notify({ secret })`, decrypted for this send only. */
+  secret: string | null;
+  notificationId: string;
+  tenantId: string | null;
+}
+
+/** Type key → how its link is built. A builder signs the link with its own key, or puts `secret` in it. */
+export type SecretLinks = Readonly<Record<string, (ref: SecretLinkRef) => string | Promise<string>>>;
+
+/** No builder for a type whose emails need one, or a builder that gave back something that isn't an https link. */
+export class SecretLinkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SecretLinkError";
+  }
+}
+
+/**
+ * The secret link for one notification, built server-side at send time.
+ * Throws a `SecretLinkError` when there is no builder for `type` or it gives
+ * something other than an `https:` URL (`http:` only for localhost).
+ *
+ * @stability Beta
+ */
+export async function resolveSecretLink(links: SecretLinks, type: string, ref: SecretLinkRef): Promise<string> {
+  const build = Object.prototype.hasOwnProperty.call(links, type) ? links[type] : undefined;
+  if (!build) throw new SecretLinkError(`No secret link builder for type ${type}`);
+  const link = await build(ref);
+  let url: URL;
+  try {
+    url = new URL(link);
+  } catch {
+    throw new SecretLinkError(`The secret link for type ${type} is not a URL`);
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:")) throw new SecretLinkError(`The secret link for type ${type} is not https`);
+  return url.toString();
+}
+
+/** What a template puts where the secret link goes; the runner swaps it in at send time, so the stored render never holds it. */
+export const SECRET_LINK_PLACEHOLDER = "https://genesis-secret-link.invalid/";

package/src/server/store.ts

@@ -0,0 +1,150 @@
+/**
+ * The database half, through the service role: what the runner and the
+ * handler call. `supabaseNotificationStore(admin)` wraps migration 0001's
+ * functions; tests (and an app with another queue) pass their own.
+ */
+import type { Channel, NotificationTypeRow } from "../core/registry";
+
+type RpcResult = { data: unknown; error: { message?: string; code?: string | null } | null };
+
+/** The part of a Supabase client the store uses, signed in with the service role (`SUPABASE_SECRET_KEY`). */
+export interface RpcClient {
+  // Loose on purpose: a client typed by an app's Database narrows `rpc`'s names to its own.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  rpc: (fn: any, args?: any) => PromiseLike<RpcResult>;
+}
+
+/** A database refusal, with its SQLSTATE; never the row it refused. */
+export class NotificationStoreError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly code: string | null,
+  ) {
+    super(`${operation} failed${code ? ` (${code})` : ""}`);
+    this.name = "NotificationStoreError";
+  }
+}
+
+export interface ClaimedDevice {
+  id: string;
+  token: string;
+  platform: string;
+}
+
+export interface SenderIdentity {
+  from_name: string | null;
+  reply_to: string | null;
+  domain: string | null;
+  domain_verified: boolean;
+}
+
+/** One claimed send job, as genesis_notifications_claim hands it over. */
+export interface ClaimedJob {
+  id: string;
+  claim_id: string;
+  notification_id: string;
+  channel: Exclude<Channel, "in_app">;
+  attempt: number;
+  deferrals: number;
+  redelivery: boolean;
+  type: string;
+  category: string;
+  tenant_id: string | null;
+  user_id: string | null;
+  email: string | null;
+  recipient_name: string | null;
+  data: Record<string, unknown>;
+  thread_key: string | null;
+  collapse_key: string | null;
+  badge: number | null;
+  brand: Record<string, unknown> | null;
+  transactional: boolean;
+  /** Preferences can't turn it off, so its email has no unsubscribe link. */
+  critical: boolean;
+  push_privacy: "default" | "generic";
+  ios_category: string | null;
+  hide_previews: boolean;
+  devices: ClaimedDevice[] | null;
+  sender: SenderIdentity | null;
+  rendered: RenderedEmail | null;
+  rendered_hash: string | null;
+  secret: string | null;
+}
+
+/** An email as first rendered: what every retry sends. */
+export interface RenderedEmail {
+  from: string;
+  to: string[];
+  reply_to?: string;
+  subject: string;
+  html: string;
+  text: string;
+  headers?: Record<string, string>;
+  tags?: { name: string; value: string }[];
+}
+
+export type SettleOutcome =
+  | { status: "sent"; provider_id?: string | null }
+  | { status: "skipped"; reason: string }
+  | { status: "filtered" }
+  | { status: "failed"; error: string; provider_id?: string | null }
+  | { status: "retry"; error: string; retry_at: string; counted: boolean; provider_id?: string | null };
+
+export interface PushTicketRow {
+  device_id: string;
+  ticket_id: string | null;
+  status: "sent" | "failed";
+  error: string | null;
+}
+
+export interface NotificationStore {
+  /** `maxAttempts`: a job whose lease ran out that many times fails (`lease_expired`) instead of coming back. */
+  claim(channel: "push" | "email", limit: number, leaseSeconds: number, maxAttempts?: number): Promise<ClaimedJob[]>;
+  storeRendered(id: string, claimId: string, rendered: RenderedEmail, hash: string): Promise<{ rendered: RenderedEmail; hash: string } | null>;
+  settle(id: string, claimId: string, outcome: SettleOutcome): Promise<boolean>;
+  /** Keeps the provider's id the moment a send returns, before it settles, so an early webhook finds the job. False when the claim is gone. */
+  recordProviderId(id: string, claimId: string, providerId: string): Promise<boolean>;
+  pushTickets(deliveryId: string, tickets: PushTicketRow[]): Promise<void>;
+  receiptsClaim(limit: number): Promise<{ id: number; ticket_id: string }[]>;
+  receiptsSettle(results: { id: number; status: "delivered" | "failed"; error: string | null }[]): Promise<void>;
+  emailEvent(providerId: string, event: "delivered" | "bounced" | "complained", permanent: boolean): Promise<boolean>;
+  /** For a login (`userId`), or someone with none by the SHA-256 of their address; for one tenant's mail (`tenantId`), or mail sent for none. */
+  unsubscribe(userId: string | null, emailHash: string | null, category: string, tenantId: string | null): Promise<boolean>;
+  syncTypes(rows: NotificationTypeRow[]): Promise<number>;
+}
+
+/**
+ * The store over migration 0001's functions.
+ *
+ * @stability Beta
+ */
+export function supabaseNotificationStore(client: RpcClient): NotificationStore {
+  const call = async <T>(fn: string, args: Record<string, unknown>): Promise<T> => {
+    const { data, error } = await client.rpc(fn, args);
+    if (error) throw new NotificationStoreError(fn, error.code ?? null);
+    return data as T;
+  };
+  return {
+    claim: (channel, limit, leaseSeconds, maxAttempts = 8) =>
+      call<ClaimedJob[]>("genesis_notifications_claim", { p_channel: channel, p_limit: limit, p_lease_seconds: leaseSeconds, p_max_attempts: maxAttempts }).then((rows) => rows ?? []),
+    async storeRendered(id, claimId, rendered, hash) {
+      const rows = await call<{ rendered: RenderedEmail | null; rendered_hash: string | null }[]>("genesis_notifications_store_rendered", { p_id: id, p_claim: claimId, p_rendered: rendered, p_hash: hash });
+      const row = rows?.[0];
+      return row?.rendered && row.rendered_hash ? { rendered: row.rendered, hash: row.rendered_hash } : null;
+    },
+    settle: (id, claimId, outcome) => call<boolean>("genesis_notifications_settle", { p_id: id, p_claim: claimId, p_outcome: outcome }).then(Boolean),
+    recordProviderId: (id, claimId, providerId) =>
+      call<boolean>("genesis_notifications_record_provider_id", { p_id: id, p_claim: claimId, p_provider_id: providerId }).then(Boolean),
+    async pushTickets(deliveryId, tickets) {
+      await call("genesis_notifications_push_tickets", { p_delivery: deliveryId, p_tickets: tickets });
+    },
+    receiptsClaim: (limit) => call<{ id: number; ticket_id: string }[]>("genesis_notifications_receipts_claim", { p_limit: limit }).then((r) => r ?? []),
+    async receiptsSettle(results) {
+      await call("genesis_notifications_receipts_settle", { p_results: results });
+    },
+    emailEvent: (providerId, event, permanent) => call<boolean>("genesis_notifications_email_event", { p_provider_id: providerId, p_event: event, p_permanent: permanent }).then(Boolean),
+    unsubscribe: (userId, emailHash, category, tenantId) =>
+      call<boolean>("genesis_notifications_unsubscribe", { p_user_id: userId, p_email_hash: emailHash, p_category: category, p_tenant_id: tenantId }).then(Boolean),
+    syncTypes: (rows) => call<number>("genesis_notifications_sync_types", { p_rows: rows }),
+  };
+}

package/src/server/unsubscribe.ts

@@ -0,0 +1,78 @@
+/**
+ * One-click unsubscribe (RFC 8058) for mail that isn't transactional: the
+ * `List-Unsubscribe` and `List-Unsubscribe-Post` headers, and a signed token
+ * that names who, which category and which tenant, so the endpoint needs no
+ * sign-in. The token never carries an address: someone with no login is named
+ * by the SHA-256 of their lower-cased address (what the suppression list keeps).
+ * The unsubscribe is for the tenant the email came from, not every tenant.
+ */
+import { base64url, fromBase64url, hmacSha256, sha256Hex, timingSafeEqual } from "./crypto";
+
+export interface UnsubscribeClaims {
+  /** The login, when the recipient has one. */
+  userId?: string;
+  /** SHA-256 (hex) of the lower-cased, trimmed address, when they have none (`emailHash`). */
+  emailHash?: string;
+  category: string;
+  /** The tenant the email came from; the unsubscribe holds for it only. */
+  tenantId?: string;
+}
+
+/** What the suppression list keys an address by: SHA-256 of it lower-cased and trimmed (as `genesis_notifications_email_hash`). */
+export function emailHash(email: string): Promise<string> {
+  return sha256Hex(email.trim().toLowerCase());
+}
+
+/** The secret must be at least 32 characters. */
+function checkSecret(secret: string) {
+  if (typeof secret !== "string" || secret.length < 32) throw new Error("The unsubscribe secret must be at least 32 characters");
+}
+
+/** A signed, URL-safe token for `claims`. */
+export async function createUnsubscribeToken(secret: string, claims: UnsubscribeClaims): Promise<string> {
+  checkSecret(secret);
+  if (claims.emailHash !== undefined && !/^[0-9a-f]{64}$/.test(claims.emailHash)) throw new Error("createUnsubscribeToken: emailHash is a SHA-256 hex digest (emailHash(address))");
+  const payload = base64url(new TextEncoder().encode(JSON.stringify({ u: claims.userId, h: claims.emailHash, c: claims.category, t: claims.tenantId, v: 2 })));
+  const sig = base64url(await hmacSha256(secret, `unsubscribe.${payload}`));
+  return `${payload}.${sig}`;
+}
+
+/** The claims of a token this secret signed, or null for anything else. */
+export async function verifyUnsubscribeToken(secret: string, token: string): Promise<UnsubscribeClaims | null> {
+  checkSecret(secret);
+  if (typeof token !== "string" || token.length > 2000) return null;
+  const [payload, sig, extra] = token.split(".");
+  if (!payload || !sig || extra !== undefined) return null;
+  let given: Uint8Array;
+  try {
+    given = fromBase64url(sig);
+  } catch {
+    return null;
+  }
+  const expected = await hmacSha256(secret, `unsubscribe.${payload}`);
+  if (!timingSafeEqual(given, expected)) return null;
+  try {
+    const raw = JSON.parse(new TextDecoder().decode(fromBase64url(payload))) as { u?: unknown; h?: unknown; c?: unknown; t?: unknown; v?: unknown };
+    if (raw.v !== 2 || typeof raw.c !== "string") return null;
+    const hash = typeof raw.h === "string" && /^[0-9a-f]{64}$/.test(raw.h) ? raw.h : undefined;
+    if (typeof raw.u !== "string" && !hash) return null;
+    return {
+      category: raw.c,
+      ...(typeof raw.u === "string" ? { userId: raw.u } : {}),
+      ...(hash ? { emailHash: hash } : {}),
+      ...(typeof raw.t === "string" ? { tenantId: raw.t } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The RFC 8058 headers for one email. `url` is your unsubscribe endpoint; the token goes in its query. */
+export function unsubscribeHeaders(url: string, token: string): Record<string, string> {
+  const link = new URL(url);
+  link.searchParams.set("t", token);
+  return {
+    "List-Unsubscribe": `<${link.toString()}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+  };
+}

package/src/server/webhook.ts

@@ -0,0 +1,55 @@
+/**
+ * Resend's webhooks are signed the Standard Webhooks way (Svix): headers
+ * `svix-id`, `svix-timestamp` and `svix-signature` (`v1,<base64 HMAC-SHA256
+ * of "id.timestamp.body">`, with the base64 secret after `whsec_`).
+ */
+import { fromBase64, hmacSha256, timingSafeEqual } from "./crypto";
+
+/** How far a webhook's timestamp may be from now: five minutes, as Svix checks. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+
+/** Whether `body` was signed with `secret`; false for anything stale, unsigned or malformed. */
+export async function verifyResendWebhook(secret: string, headers: Headers, body: string, now = Date.now()): Promise<boolean> {
+  const id = headers.get("svix-id") ?? headers.get("webhook-id");
+  const timestamp = headers.get("svix-timestamp") ?? headers.get("webhook-timestamp");
+  const signatures = headers.get("svix-signature") ?? headers.get("webhook-signature");
+  if (!secret || !id || !timestamp || !signatures || !/^\d{1,12}$/.test(timestamp)) return false;
+  if (Math.abs(now / 1000 - Number(timestamp)) > WEBHOOK_TOLERANCE_SECONDS) return false;
+  let key: Uint8Array;
+  try {
+    key = fromBase64(secret.startsWith("whsec_") ? secret.slice(6) : secret);
+  } catch {
+    return false;
+  }
+  const expected = await hmacSha256(key, `${id}.${timestamp}.${body}`);
+  for (const part of signatures.split(" ")) {
+    const [version, sig] = part.split(",");
+    if (version !== "v1" || !sig) continue;
+    let given: Uint8Array;
+    try {
+      given = fromBase64(sig);
+    } catch {
+      continue;
+    }
+    if (timingSafeEqual(given, expected)) return true;
+  }
+  return false;
+}
+
+/** What the notifier does with an email event; null for the events it doesn't use. */
+export function emailEventOf(payload: unknown): { providerId: string; event: "delivered" | "bounced" | "complained"; permanent: boolean } | null {
+  const p = payload as { type?: unknown; data?: { email_id?: unknown; bounce?: { type?: unknown } } } | null;
+  const id = p?.data?.email_id;
+  if (typeof id !== "string" || !id || id.length > 200) return null;
+  switch (p?.type) {
+    case "email.delivered":
+      return { providerId: id, event: "delivered", permanent: false };
+    case "email.bounced":
+      // Only what Resend names "Permanent" is a hard bounce; anything else (Transient, Undetermined, none) doesn't suppress.
+      return { providerId: id, event: "bounced", permanent: p.data?.bounce?.type === "Permanent" };
+    case "email.complained":
+      return { providerId: id, event: "complained", permanent: true };
+    default:
+      return null;
+  }
+}

package/src/supabase/index.ts

@@ -0,0 +1,210 @@
+/**
+ * `@marktiderman/genesis-notifications/supabase`: the migration this package
+ * ships (`migrations/0001_genesis_notifications.sql`, with its pgTAP test),
+ * and `notificationsClient(supabase)`, the browser and phone side over it:
+ * the person's feed, unread count, marks and preferences under row level
+ * security, the realtime nudge on `user:<id>`, and the admin views.
+ *
+ * @packageDocumentation
+ */
+import type { Channel, ChannelChoices, NotificationRow } from "../core/index";
+
+export const NOTIFICATIONS_PACKAGE = "@marktiderman/genesis-notifications";
+
+/** The migrations to copy, in order, with their tests. */
+export const NOTIFICATIONS_MIGRATIONS = [
+  { package: NOTIFICATIONS_PACKAGE, file: "migrations/0001_genesis_notifications.sql", test: "migrations/tests/0001_genesis_notifications.test.sql" },
+] as const;
+
+type Result = { data: unknown; error: { message?: string; code?: string | null } | null; count?: number | null };
+
+interface Query extends PromiseLike<Result> {
+  select(columns: string, options?: { count?: "exact"; head?: boolean }): Query;
+  eq(column: string, value: unknown): Query;
+  is(column: string, value: null): Query;
+  not(column: string, op: string, value: unknown): Query;
+  lt(column: string, value: unknown): Query;
+  order(column: string, options?: { ascending?: boolean }): Query;
+  limit(n: number): Query;
+  maybeSingle(): PromiseLike<Result>;
+}
+
+interface Channel_ {
+  on(type: "broadcast", filter: { event: string }, callback: (payload: unknown) => void): Channel_;
+  subscribe(callback?: (status: string) => void): Channel_;
+}
+
+/** The parts of a Supabase client used here; a `SupabaseClient` fits, typed by your Database or not. */
+export interface NotificationsSupabaseLike {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  rpc: (fn: any, args?: any) => PromiseLike<Result>;
+  from(table: string): unknown;
+  channel(name: string, options?: { config?: { private?: boolean } }): unknown;
+  removeChannel(channel: unknown): unknown;
+  realtime?: { setAuth?: (token?: string | null) => unknown };
+}
+
+/** A database refusal, with its SQLSTATE. */
+export class NotificationsClientError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly code: string | null,
+  ) {
+    super(`${operation} failed${code ? ` (${code})` : ""}`);
+    this.name = "NotificationsClientError";
+  }
+}
+
+export type FeedFilter = "all" | "unread" | "archived";
+
+/** One row of the admin's delivery log: no content, a masked address. */
+export interface DeliveryLogRow {
+  id: string;
+  notification_id: string;
+  tenant_id: string | null;
+  type: string;
+  channel: "push" | "email";
+  status: string;
+  attempts: number;
+  error: string | null;
+  skip_reason: string | null;
+  recipient_masked: string | null;
+  created_at: string;
+  sent_at: string | null;
+}
+
+export interface SuppressionRow {
+  email_hash: string;
+  category: string;
+  reason: "bounce" | "complaint" | "unsubscribe" | "manual";
+  email_masked: string | null;
+  created_at: string;
+}
+
+export interface NotificationsClient {
+  feed(options?: { filter?: FeedFilter; limit?: number; before?: string }): Promise<NotificationRow[]>;
+  unreadCount(): Promise<number>;
+  mark(ids: readonly string[], state: "seen" | "read" | "unread" | "archived" | "unarchived"): Promise<number>;
+  markAll(state: "seen" | "read"): Promise<number>;
+  /** The signed-in person's choices (category → channel → on); `{}` before they chose. */
+  choices(userId: string): Promise<ChannelChoices>;
+  /** One category and channel; `null` returns it to the default. Resolves the person's choices after. */
+  setChoice(category: string, channel: Channel, on: boolean | null): Promise<ChannelChoices>;
+  /** Calls `onChange` whenever the person's feed changes (a broadcast on `user:<id>`). Returns the stop. */
+  subscribe(userId: string, onChange: () => void): () => void;
+  /** Admin: the delivery log (row level security shows an admin their tenants'). */
+  deliveryLog(options?: { tenantId?: string | null; status?: string; limit?: number }): Promise<DeliveryLogRow[]>;
+  /** Admin: the suppression list (platform admins). */
+  suppressions(options?: { limit?: number }): Promise<SuppressionRow[]>;
+  removeSuppression(emailHash: string, category?: string): Promise<boolean>;
+  /** Admin: a test notification to yourself, on every channel you have. */
+  sendTest(tenantId?: string | null): Promise<string | null>;
+}
+
+/**
+ * A preferences row as category → channel → on: `channels`, with the push
+ * and email of a category switched off as a whole (migration 0005's
+ * `categories`) filled in where no channel was chosen, as the server reads it.
+ */
+export function choicesOf(row: { channels?: unknown; categories?: unknown } | null): ChannelChoices {
+  const object = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+  const out: ChannelChoices = {};
+  for (const [category, chosen] of Object.entries(object(row?.channels))) {
+    const cell: Partial<Record<Channel, boolean>> = {};
+    for (const [ch, on] of Object.entries(object(chosen))) if (typeof on === "boolean" && (ch === "in_app" || ch === "push" || ch === "email")) cell[ch] = on;
+    out[category] = cell;
+  }
+  for (const [category, on] of Object.entries(object(row?.categories))) {
+    if (on !== false) continue;
+    const cell = { ...out[category] };
+    cell.push ??= false;
+    cell.email ??= false;
+    out[category] = cell;
+  }
+  return out;
+}
+
+export const FEED_COLUMNS = "id, type, category, tenant_id, data, thread_key, created_at, seen_at, read_at, archived_at";
+const LOG_COLUMNS = "id, notification_id, tenant_id, type, channel, status, attempts, error, skip_reason, recipient_masked, created_at, sent_at";
+
+/**
+ * The browser and phone side of the notifier, under the signed-in person's
+ * row level security.
+ *
+ * @stability Beta
+ */
+export function notificationsClient(client: NotificationsSupabaseLike): NotificationsClient {
+  const must = (operation: string, result: Result) => {
+    if (result.error) throw new NotificationsClientError(operation, result.error.code ?? null);
+    return result;
+  };
+  const table = (name: string) => client.from(name) as Query;
+  return {
+    async feed({ filter = "all", limit = 50, before } = {}) {
+      let q = table("notifications").select(FEED_COLUMNS).eq("in_feed", true);
+      q = filter === "archived" ? q.not("archived_at", "is", null) : q.is("archived_at", null);
+      if (filter === "unread") q = q.is("read_at", null);
+      if (before) q = q.lt("created_at", before);
+      const { data } = must("notifications", await q.order("created_at", { ascending: false }).limit(Math.min(Math.max(1, limit), 200)));
+      return (data as NotificationRow[] | null) ?? [];
+    },
+    async unreadCount() {
+      const { count } = must(
+        "notifications",
+        await table("notifications").select("id", { count: "exact", head: true }).eq("in_feed", true).is("read_at", null).is("archived_at", null),
+      );
+      return count ?? 0;
+    },
+    async mark(ids, state) {
+      if (!ids.length) return 0;
+      const { data } = must("genesis_notifications_mark", await client.rpc("genesis_notifications_mark", { p_ids: ids, p_state: state }));
+      return Number(data ?? 0);
+    },
+    async markAll(state) {
+      const { data } = must("genesis_notifications_mark_all", await client.rpc("genesis_notifications_mark_all", { p_state: state }));
+      return Number(data ?? 0);
+    },
+    async choices(userId) {
+      const { data } = must("notification_preferences", await table("notification_preferences").select("channels, categories").eq("user_id", userId).maybeSingle());
+      return choicesOf(data as { channels?: unknown; categories?: unknown } | null);
+    },
+    async setChoice(category, channel, on) {
+      const { data } = must("genesis_notifications_set_preference", await client.rpc("genesis_notifications_set_preference", { p_category: category, p_channel: channel, p_on: on }));
+      return (data as ChannelChoices | null) ?? {};
+    },
+    subscribe(userId, onChange) {
+      if (typeof client.channel !== "function") {
+        // Loud, not fatal: without realtime the feed still refetches on focus and pull to refresh.
+        console.warn("[genesis-notifications] this Supabase client has no realtime (client.channel); the feed won't update live.");
+        return () => {};
+      }
+      const channel = client.channel(`user:${userId}`, { config: { private: true } }) as Channel_;
+      channel.on("broadcast", { event: "notification" }, () => onChange()).subscribe();
+      return () => {
+        client.removeChannel(channel);
+      };
+    },
+    async deliveryLog({ tenantId, status, limit = 100 } = {}) {
+      let q = table("notification_deliveries").select(LOG_COLUMNS);
+      if (tenantId !== undefined) q = tenantId === null ? q.is("tenant_id", null) : q.eq("tenant_id", tenantId);
+      if (status) q = q.eq("status", status);
+      const { data } = must("notification_deliveries", await q.order("created_at", { ascending: false }).limit(Math.min(Math.max(1, limit), 500)));
+      return (data as DeliveryLogRow[] | null) ?? [];
+    },
+    async suppressions({ limit = 200 } = {}) {
+      const { data } = must(
+        "notification_suppressions",
+        await table("notification_suppressions").select("email_hash, category, reason, email_masked, created_at").order("created_at", { ascending: false }).limit(Math.min(Math.max(1, limit), 1000)),
+      );
+      return (data as SuppressionRow[] | null) ?? [];
+    },
+    async removeSuppression(emailHash, category = "*") {
+      const { data } = must("genesis_notifications_remove_suppression", await client.rpc("genesis_notifications_remove_suppression", { p_email_hash: emailHash, p_category: category }));
+      return Boolean(data);
+    },
+    async sendTest(tenantId = null) {
+      const { data } = must("genesis_notifications_send_test", await client.rpc("genesis_notifications_send_test", { p_tenant: tenantId }));
+      return (data as string | null) ?? null;
+    },
+  };
+}