@marktiderman/genesis-notifications 0.0.0-stage → 0.1.1

package/src/core/types.ts

@@ -0,0 +1,90 @@
+/**
+ * The shapes the notifier's parts share: what a domain passes to `notify()`,
+ * a feed row as the database returns it, and a person's preferences.
+ */
+import type { Channel, NotificationData } from "./registry";
+
+/** A recipient with a login, by user id. */
+export interface UserRecipient {
+  userId: string;
+  /** Their own app icon badge (an unread count), over the call's `badge`. */
+  badge?: number;
+}
+
+/**
+ * Someone with no login (an invitee, a form respondent): email only, never a
+ * feed. `ref` is the domain's id for them ("people:42"), so erasing them
+ * finds their rows.
+ */
+export interface EmailRecipient {
+  email: string;
+  name?: string;
+  ref?: string;
+}
+
+/** A user id string, or one of the two shapes. */
+export type Recipient = string | UserRecipient | EmailRecipient;
+
+/** A brand the caller passes (the tenant's default is used for what it leaves out). */
+export interface NotificationBrand {
+  name?: string;
+  logoUrl?: string;
+  /** A CSS colour (`#1d4ed8`), for the email's accent. */
+  color?: string;
+  /** Where a recipient goes from the email's footer. */
+  url?: string;
+}
+
+/** What a domain asks for. The notifier decides channel, timing and preferences. */
+export interface NotifyInput<K extends string = string> {
+  type: K;
+  recipients: readonly Recipient[];
+  /** References and display values the type's render reads. Never a secret or a secret link. */
+  data?: NotificationData;
+  /** Unique per recipient: the same key again is the same notification, never a second one. */
+  idempotencyKey: string;
+  /** Groups pushes on the lock screen (iOS `threadId`): a conversation id. */
+  threadKey?: string;
+  /** A newer one replaces an older one with the same key that hasn't gone out (and on screen). */
+  collapseKey?: string;
+  /** The app icon badge, as the caller counts it. */
+  badge?: number;
+  /** The practice, workspace or organization it belongs to: its sender identity and defaults apply. */
+  tenantId?: string;
+  brand?: NotificationBrand;
+  /**
+   * A plaintext token that exists only hashed in the domain's tables (an
+   * invite). It travels only on the email's send job, encrypted, and is
+   * cleared once the email is sent; `resolveSecretLink` receives it.
+   */
+  secret?: string;
+}
+
+/** One row `notify()` made or found again. */
+export interface NotifyResult {
+  notificationId: string;
+  recipientKey: string;
+  /** False when the idempotency key had been used for this recipient already. */
+  created: boolean;
+}
+
+/** A feed row, as the browser reads it under row level security. */
+export interface NotificationRow {
+  id: string;
+  type: string;
+  category: string;
+  tenant_id: string | null;
+  data: NotificationData;
+  thread_key: string | null;
+  created_at: string;
+  seen_at: string | null;
+  read_at: string | null;
+  archived_at: string | null;
+}
+
+/** Delivery states. */
+export const DELIVERY_STATUSES = ["pending", "sending", "sent", "delivered", "failed", "skipped", "cancelled"] as const;
+export type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
+
+/** A person's explicit choices: category id → channel → on. Absent means the default. */
+export type ChannelChoices = Record<string, Partial<Record<Channel, boolean>>>;

package/src/core/validate.ts

@@ -0,0 +1,73 @@
+/**
+ * Checks `notify()` runs before anything reaches the database (which checks
+ * the same again): recipients are well formed, and `data` holds no secret.
+ */
+import type { NotificationData } from "./registry";
+import type { Recipient } from "./types";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMAIL = /^[^\s@<>,;:"()[\]\\]+@[^\s@<>,;:"()[\]\\]+\.[^\s@<>,;:"()[\]\\]+$/;
+
+/**
+ * Keys that hold a secret by their name, matched on the key split into words
+ * (`inviteToken` is `invite_token`): any key ending in token, code, secret,
+ * key, otp or password, and a few more by word. The database refuses the same
+ * list. A backstop, not a guarantee: it catches the usual names, so a display
+ * value named that way (`country_code`) is refused too; name it otherwise.
+ */
+export const SECRET_KEY = /((token|code|secret|key|otp|password)|(^|[._-])(signature|sig|magic_?link|invite_?link|reset_?link))$/;
+
+/** A key as words, lower case: `inviteToken` → `invite_token`. */
+export function keyWords(key: string): string {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+/**
+ * A link, absolute (`https://…`, `mailto:…`) or relative (`/…`, `./…`, `?…`,
+ * `#…`), with a query or fragment parameter whose name ends in token, code,
+ * secret, key, otp, password, sig or signature (`?token=`, `#access_token=`,
+ * `&inviteCode=`).
+ */
+export const SECRET_URL = /^([a-z][a-z0-9+.-]*:|\/|\.\.?\/|(?=[?#]))\S*[?&#;][^=&#;\s]*(token|code|secret|key|otp|password|signature|sig)=/i;
+
+/** `data` held something that looks like a secret: build such links at send time instead. */
+export class SecretInDataError extends Error {
+  constructor(readonly path: string) {
+    super(`notify: data.${path} looks like a secret. Store a reference and build the link at send time with resolveSecretLink.`);
+    this.name = "SecretInDataError";
+  }
+}
+
+/** Throws a `SecretInDataError` naming the first key (or link) that looks like a secret. */
+export function assertNoSecrets(data: NotificationData | undefined, path = ""): void {
+  if (!data || typeof data !== "object") return;
+  for (const [key, value] of Object.entries(data)) {
+    const here = path ? `${path}.${key}` : key;
+    if (SECRET_KEY.test(keyWords(key))) throw new SecretInDataError(here);
+    if (typeof value === "string" && SECRET_URL.test(value)) throw new SecretInDataError(here);
+    if (value && typeof value === "object") assertNoSecrets(value as NotificationData, here);
+  }
+}
+
+/** The recipients as `genesis_notify` takes them; throws on a malformed one. */
+export function recipientsToJson(recipients: readonly Recipient[]): ({ user_id: string; badge?: number } | { email: string; name?: string; ref?: string })[] {
+  if (!Array.isArray(recipients) || recipients.length === 0) throw new Error("notify: no recipients");
+  if (recipients.length > 1000) throw new Error("notify: at most 1000 recipients a call");
+  return recipients.map((r, i) => {
+    if (typeof r === "string") {
+      if (!UUID.test(r)) throw new Error(`notify: recipient ${i} is not a user id`);
+      return { user_id: r };
+    }
+    if ("userId" in r) {
+      if (!UUID.test(r.userId)) throw new Error(`notify: recipient ${i} is not a user id`);
+      if (r.badge === undefined) return { user_id: r.userId };
+      if (!Number.isInteger(r.badge) || r.badge < 0 || r.badge > 99999) throw new Error(`notify: recipient ${i}'s badge is a whole number from 0`);
+      return { user_id: r.userId, badge: r.badge };
+    }
+    if ("email" in r) {
+      const email = r.email.trim();
+      if (!EMAIL.test(email) || email.length > 254) throw new Error(`notify: recipient ${i} has no valid email address`);
+      return { email, ...(r.name ? { name: r.name.slice(0, 200) } : {}), ...(r.ref ? { ref: r.ref.slice(0, 200) } : {}) };
+    }
+    throw new Error(`notify: recipient ${i} is neither a user id nor an email`);
+  });
+}

package/src/email/index.tsx

@@ -0,0 +1,142 @@
+/**
+ * `@marktiderman/genesis-notifications/email`: React Email templates for the
+ * notifier. `BrandLayout` wraps a message in the tenant's brand (logo or
+ * name, accent colour, footer with the unsubscribe link when there is one);
+ * `reactEmailTemplate` turns a component into an `EmailTemplate` the runner
+ * takes. Server-only; needs `@react-email/components` (an optional peer).
+ *
+ * ```tsx
+ * const templates = {
+ *   "chat.message": reactEmailTemplate((ctx) => ({
+ *     subject: `${ctx.text.title} sent you a message`,
+ *     body: (
+ *       <BrandLayout ctx={ctx} preview={ctx.text.body}>
+ *         <EmailText>{ctx.text.body}</EmailText>
+ *         {ctx.url ? <EmailButton ctx={ctx} href={ctx.url}>Reply</EmailButton> : null}
+ *       </BrandLayout>
+ *     ),
+ *   })),
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Body, Button, Container, Head, Heading, Hr, Html, Img, Link, Preview, Section, Text, render } from "@react-email/components";
+import type { EmailContent, EmailTemplate, EmailTemplateContext } from "../server/email-render";
+
+const SAFE_COLOR = /^#[0-9a-fA-F]{3,8}$/;
+
+function accentOf(ctx: EmailTemplateContext): string {
+  return typeof ctx.brand.color === "string" && SAFE_COLOR.test(ctx.brand.color) ? ctx.brand.color : "#111827";
+}
+
+function httpsOrNull(url: unknown): string | null {
+  if (typeof url !== "string") return null;
+  try {
+    return new URL(url).protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface BrandLayoutProps {
+  ctx: EmailTemplateContext;
+  /** The inbox preview line. */
+  preview?: string;
+  /** Default `ctx.text.title`. */
+  heading?: string;
+  /** Words before the unsubscribe link. Default "Don't want these emails?". */
+  unsubscribeLabel?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The brand frame every notification email shares.
+ *
+ * @stability Beta
+ */
+export function BrandLayout({ ctx, preview, heading, unsubscribeLabel = "Don't want these emails?", children }: BrandLayoutProps) {
+  const accent = accentOf(ctx);
+  const logo = httpsOrNull(ctx.brand.logoUrl);
+  const site = httpsOrNull(ctx.brand.url);
+  return (
+    <Html lang="en">
+      <Head />
+      {preview ? <Preview>{preview}</Preview> : null}
+      <Body style={{ backgroundColor: "#f6f7f9", margin: 0, padding: "24px 0", fontFamily: "-apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif" }}>
+        <Container style={{ backgroundColor: "#ffffff", borderRadius: 8, padding: 24, maxWidth: 560 }}>
+          <Section style={{ marginBottom: 16 }}>
+            {logo ? (
+              <Img src={logo} alt={ctx.brand.name ?? ""} height={32} />
+            ) : ctx.brand.name ? (
+              <Text style={{ margin: 0, fontWeight: 600, fontSize: 16, color: accent }}>{ctx.brand.name}</Text>
+            ) : null}
+          </Section>
+          <Heading as="h1" style={{ fontSize: 20, lineHeight: "28px", margin: "0 0 12px", color: "#111827" }}>
+            {heading ?? ctx.text.title}
+          </Heading>
+          {children}
+          <Hr style={{ borderColor: "#e5e7eb", margin: "24px 0 12px" }} />
+          <Text style={{ fontSize: 12, color: "#6b7280", margin: 0 }}>
+            {site && ctx.brand.name ? <Link href={site} style={{ color: "#6b7280" }}>{ctx.brand.name}</Link> : ctx.brand.name ?? null}
+            {ctx.unsubscribeUrl ? (
+              <>
+                {ctx.brand.name ? " · " : null}
+                {unsubscribeLabel}{" "}
+                <Link href={ctx.unsubscribeUrl} style={{ color: "#6b7280", textDecoration: "underline" }}>
+                  Unsubscribe
+                </Link>
+              </>
+            ) : null}
+          </Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+/** A paragraph in the brand's type. */
+export function EmailText({ children }: { children?: ReactNode }) {
+  return <Text style={{ fontSize: 15, lineHeight: "24px", color: "#111827", margin: "0 0 16px", whiteSpace: "pre-wrap" }}>{children}</Text>;
+}
+
+/** A button in the brand's accent. */
+export function EmailButton({ ctx, href, children }: { ctx: EmailTemplateContext; href: string; children?: ReactNode }) {
+  return (
+    <Button href={href} style={{ backgroundColor: accentOf(ctx), color: "#ffffff", borderRadius: 6, padding: "10px 16px", fontSize: 15, textDecoration: "none" }}>
+      {children}
+    </Button>
+  );
+}
+
+/**
+ * Turn a React Email component into the runner's `EmailTemplate`: HTML and a
+ * plain-text part from the same element.
+ *
+ * @stability Beta
+ */
+export function reactEmailTemplate(build: (ctx: EmailTemplateContext) => { subject: string; body: ReactElement }): EmailTemplate {
+  return async (ctx): Promise<EmailContent> => {
+    const { subject, body } = build(ctx);
+    const [html, text] = await Promise.all([render(body), render(body, { plainText: true })]);
+    return { subject, html, text };
+  };
+}
+
+/** The default template, on the brand layout: the registry's title and body, and a button to the link. */
+export const brandedDefaultTemplate: EmailTemplate = reactEmailTemplate((ctx) => ({
+  subject: ctx.text.title,
+  body: (
+    <BrandLayout ctx={ctx} preview={ctx.text.body}>
+      {ctx.text.body ? <EmailText>{ctx.text.body}</EmailText> : null}
+      {ctx.secretLink ?? ctx.url ? (
+        <EmailButton ctx={ctx} href={(ctx.secretLink ?? ctx.url)!}>
+          Open
+        </EmailButton>
+      ) : null}
+    </BrandLayout>
+  ),
+}));
+
+export type { EmailContent, EmailTemplate, EmailTemplateContext };

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @marktiderman/genesis-notifications: the registry and shared types (the `/core` entry).
+ *
+ * @packageDocumentation
+ */
+export * from "./core/index";

package/src/native/index.tsx

@@ -0,0 +1,283 @@
+/**
+ * `@marktiderman/genesis-notifications/native`: the notifier on the phone.
+ *
+ *   NotificationsFeed            the feed on genesis-ui-native's NotificationsPage
+ *   useNotificationsFeedHeader   the "Mark all read" header for the feed's Stack.Screen
+ *   ChannelPreferences           category × channel switches, as NotificationSettings' `categories` part
+ *   NotificationPreferences      genesis-native's NotificationSettings with that part in place
+ *   notificationsPushBackend     the push block's `PushBackend` on this package's migration
+ *   pushOptionsFrom(registry)    the push block's categories, Android channels and device categories
+ *   notificationAction           a tapped action button (Reply, Mark as read), with the notification id
+ *
+ * The device side stays in genesis-native's push block (registration,
+ * permission, routing, badge, hiding a push for the screen already open);
+ * this is what connects it to the notifier.
+ *
+ * @packageDocumentation
+ */
+import { useMemo } from "react";
+import { NativeListItem, NativeSwitch } from "@marktiderman/genesis-ui-native/components";
+import { NotificationsPage, getNotificationsPageStackOptions, type NotificationItem, type NotificationsPageProps } from "@marktiderman/genesis-ui-native/layouts";
+import {
+  NotificationSettings,
+  notificationAction,
+  type CategoriesPartProps,
+  type NotificationAction,
+  type NotificationCategory,
+  type NotificationPreferences as PushPreferences,
+  type NotificationSettingsProps,
+  type PushBackend,
+  type PushDeviceCategory,
+  type PushOptions,
+} from "@marktiderman/genesis-native/push";
+import type { Channel, NotificationRegistry } from "../core/index";
+import { useNotifications, usePreferences, type FeedItem } from "../react/index";
+import { choicesOf } from "../supabase/index";
+
+export { notificationAction, type NotificationAction };
+
+export const CHANNEL_LABELS: Record<Channel, string> = { in_app: "In the app", push: "Push", email: "Email" };
+
+/** How many notifications the feed (and its header) reads: one query, shared by both. */
+export const NOTIFICATIONS_FEED_LIMIT = 100;
+
+export interface NotificationsFeedProps extends Omit<NotificationsPageProps, "items" | "refreshing" | "onRefresh" | "onMarkAllRead"> {
+  /** Opens a notification's link (`router.push(item.url)`); it is marked read first. */
+  onOpen?: (item: FeedItem) => void;
+  limit?: number;
+}
+
+/**
+ * The feed on ui-native's `NotificationsPage`: pull to refresh, unread dots,
+ * a tap marks read and opens. Realtime refetches it (NotificationsProvider).
+ *
+ * @stability Beta
+ */
+export function NotificationsFeed({ onOpen, limit = NOTIFICATIONS_FEED_LIMIT, ...page }: NotificationsFeedProps) {
+  const { items, isRefetching, refetch, markRead } = useNotifications({ limit });
+  const rows = useMemo<NotificationItem[]>(
+    () =>
+      items.map((item) => ({
+        id: item.id,
+        title: item.title,
+        ...(item.body ? { body: item.body } : {}),
+        timestamp: item.created_at,
+        unread: item.unread,
+        onPress: () => {
+          if (item.unread) void markRead(item.id);
+          onOpen?.(item);
+        },
+      })),
+    [items, markRead, onOpen],
+  );
+  return (
+    <NotificationsPage
+      testID="notifications"
+      {...page}
+      items={rows}
+      refreshing={isRefetching}
+      onRefresh={async () => {
+        await refetch();
+      }}
+    />
+  );
+}
+
+/**
+ * The feed's `Stack.Screen` options, with "Mark all read" while anything is
+ * unread. Pass the feed's `limit` if you changed it, so both read one query.
+ */
+export function useNotificationsFeedHeader(options: { headerTitle?: string; limit?: number } = {}): Record<string, unknown> {
+  const { items, markAllRead } = useNotifications({ limit: options.limit ?? NOTIFICATIONS_FEED_LIMIT });
+  const unread = items.some((i) => i.unread);
+  // With nothing unread the header gets an explicit empty right side: leaving it out would keep the old button.
+  return getNotificationsPageStackOptions({
+    headerTitle: options.headerTitle,
+    ...(unread ? { onMarkAllRead: () => void markAllRead() } : { headerRight: () => null }),
+  });
+}
+
+/**
+ * Category × channel switches (push and email, and the feed when a type
+ * offers it as optional), for NotificationSettings' `categories` slot. It
+ * ignores the push block's own category switches and reads the notifier's
+ * preferences instead.
+ *
+ * @stability Beta
+ */
+export function ChannelPreferences(_props: Partial<CategoriesPartProps> & { channelLabels?: Partial<Record<Channel, string>> }) {
+  const { rows, status, set } = usePreferences();
+  const labels = { ...CHANNEL_LABELS, ..._props.channelLabels };
+  return (
+    <>
+      {rows.flatMap((row) =>
+        row.channels.map((ch) => (
+          <NativeListItem
+            key={`${row.id}:${ch}`}
+            testID={`notification-preference-${row.id}-${ch}`}
+            title={row.label}
+            subtitle={row.critical ? `${labels[ch]} · Always on` : labels[ch]}
+            trailing={
+              <NativeSwitch
+                testID={`notification-preference-${row.id}-${ch}-switch`}
+                accessibilityLabel={`${row.label}: ${labels[ch]}`}
+                checked={Boolean(row.values[ch])}
+                disabled={status !== "ready" || row.critical}
+                onCheckedChange={(on) => void set(row.id, ch, on).catch(() => undefined)}
+              />
+            }
+          />
+        )),
+      )}
+    </>
+  );
+}
+
+/**
+ * Settings → Notifications with the notifier's channel switches: the push
+ * block's permission, quiet hours and previews, and `ChannelPreferences` for
+ * the categories. Needs the push block and NotificationsProvider.
+ *
+ * @stability Beta
+ */
+export function NotificationPreferences(props: NotificationSettingsProps) {
+  return <NotificationSettings {...props} slots={{ categories: ChannelPreferences, ...props.slots }} />;
+}
+
+/**
+ * What the push block needs from the registry: a category per notification
+ * category (its Android channel; NotificationSettings shows the categories
+ * section only when there are some), and the device categories with their
+ * action buttons.
+ *
+ * @stability Beta
+ */
+export function pushOptionsFrom(registry: NotificationRegistry): Pick<PushOptions, "categories" | "deviceCategories"> {
+  const categories: NotificationCategory[] = registry.androidChannels().map((c) => ({
+    id: c.id,
+    title: c.name,
+    ...(c.description ? { description: c.description } : {}),
+    importance: c.importance,
+  }));
+  const deviceCategories: PushDeviceCategory[] = registry.deviceCategories();
+  return { categories, deviceCategories };
+}
+
+type Result = { data: unknown; error: { code?: string | null } | null };
+
+/** The parts of a Supabase client the backend uses. */
+export interface PushBackendClientLike {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  rpc: (fn: any, args?: any) => PromiseLike<Result>;
+  from(table: string): unknown;
+}
+
+interface PreferencesQuery {
+  select(columns: string): { eq(column: string, value: string): { maybeSingle(): PromiseLike<Result> } };
+  upsert(row: Record<string, unknown>, options: { onConflict: string }): { select(columns: string): PromiseLike<Result> };
+}
+
+/** A database refusal, with its SQLSTATE; never a token. */
+export class NotificationsPushBackendError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly code: string | null,
+  ) {
+    super(`${operation} failed${code ? ` (${code})` : ""}`);
+    this.name = "NotificationsPushBackendError";
+  }
+}
+
+function clock(value: unknown, fallback: string): string {
+  const match = typeof value === "string" ? /^(\d{2}):(\d{2})/.exec(value) : null;
+  return match ? `${match[1]}:${match[2]}` : fallback;
+}
+
+/**
+ * The push block's `PushBackend` on genesis-notifications' migration:
+ * registers with this install's id (so a token moves between logins only on
+ * its own phone), and keeps the push block's category switches as each
+ * category's push channel (`genesis_notifications_set_preference`, one cell
+ * at a time, so nothing else in the row is overwritten). A category no
+ * notifier type sends push in (chat's `messages` while chat still sends
+ * through 0005's sender) keeps its switch in 0005's `categories`, which that
+ * sender reads, instead of failing the whole save. Quiet hours and previews
+ * are the same columns as before.
+ *
+ * @stability Beta
+ */
+export function notificationsPushBackend(client: PushBackendClientLike): PushBackend {
+  const must = (operation: string, result: Result) => {
+    if (result.error) throw new NotificationsPushBackendError(operation, result.error.code ?? null);
+    return result.data;
+  };
+  // The push channel per category as last loaded or saved, so a save writes only what changed.
+  let known: Record<string, boolean> = {};
+  // 0005's `categories` as last loaded or saved: the switches of categories the notifier has no push type in.
+  let legacy: Record<string, boolean> = {};
+  return {
+    usesInstallationId: true,
+    async register(token, platform, appVersion, installationId) {
+      must("genesis_push_register", await client.rpc("genesis_push_register", { p_token: token, p_platform: platform, p_app_version: appVersion, p_installation_id: installationId ?? null }));
+    },
+    async forget(token) {
+      must("genesis_push_forget", await client.rpc("genesis_push_forget", { p_token: token }));
+    },
+    async loadPreferences(userId) {
+      const data = must(
+        "notification_preferences",
+        await (client.from("notification_preferences") as PreferencesQuery)
+          .select("channels, categories, quiet_hours_enabled, quiet_hours_start, quiet_hours_end, time_zone, hide_previews")
+          .eq("user_id", userId)
+          .maybeSingle(),
+      ) as Record<string, unknown> | null;
+      known = {};
+      legacy = {};
+      if (!data) return null;
+      if (data.categories && typeof data.categories === "object") {
+        for (const [category, on] of Object.entries(data.categories as Record<string, unknown>)) if (typeof on === "boolean") legacy[category] = on;
+      }
+      // As the server reads it: the push channel chosen, or 0005's switch for the whole category.
+      for (const [category, row] of Object.entries(choicesOf(data))) if (typeof row.push === "boolean") known[category] = row.push;
+      return {
+        categories: { ...known },
+        quietHours: {
+          enabled: data.quiet_hours_enabled === true,
+          start: clock(data.quiet_hours_start, "22:00"),
+          end: clock(data.quiet_hours_end, "07:00"),
+          timeZone: typeof data.time_zone === "string" ? data.time_zone : null,
+        },
+        hidePreviews: data.hide_previews === true,
+      } satisfies PushPreferences;
+    },
+    async savePreferences(userId, p) {
+      let legacyChanged = false;
+      for (const [category, on] of Object.entries(p.categories)) {
+        if (known[category] === on) continue;
+        const result = await client.rpc("genesis_notifications_set_preference", { p_category: category, p_channel: "push", p_on: on });
+        // 42704 is only "no type in that category uses push"; any other refusal (a critical category, 22023) is thrown.
+        if (result.error?.code === "42704") {
+          // No notifier type sends push in this category: keep the switch where 0005's sender reads it.
+          legacy[category] = on;
+          legacyChanged = true;
+        } else {
+          must("genesis_notifications_set_preference", result);
+          // The server moved this category's 0005 switch into channel choices.
+          if (category in legacy) delete legacy[category];
+        }
+        known[category] = on;
+      }
+      const row = {
+        ...(legacyChanged ? { categories: { ...legacy } } : {}),
+        user_id: userId,
+        quiet_hours_enabled: p.quietHours.enabled,
+        quiet_hours_start: p.quietHours.start,
+        quiet_hours_end: p.quietHours.end,
+        time_zone: p.quietHours.timeZone,
+        hide_previews: p.hidePreviews,
+      };
+      const data = must("notification_preferences", await (client.from("notification_preferences") as PreferencesQuery).upsert(row, { onConflict: "user_id" }).select("user_id"));
+      if (!Array.isArray(data) || data.length !== 1) throw new NotificationsPushBackendError("notification_preferences", "no_rows");
+    },
+  };
+}