portal-mojo 0.2.6 → 0.2.8

package/src/account/NotificationPreferences.tsx

@@ -0,0 +1,152 @@
+// NotificationPreferences — the caller's notification settings over
+// /api/account/notification/preferences (django-mojo notification_prefs):
+//
+//   CHANNELS      three master cards (Email / Push / In app), one switch
+//                 each, writing the reserved all-kinds entry `"*"`:
+//                 `{"*": {email: false}}` silences every kind on email,
+//                 including kinds registered later.
+//   WHAT TO SEND  one row per kind × channel checkbox grid (partial update
+//                 `{kind: {channel: bool}}`; absent = on). A channel whose
+//                 master is off renders its column disabled; a kind that is
+//                 not delivered on a channel shows "—".
+//
+// Kinds: the `kinds` prop, else the server's registered catalogue (GET
+// `kinds`), plus any kind already stored in the caller's preferences; with
+// none at all, one "General" row. Every toggle is optimistic and reverts +
+// toasts the server's message on failure. Caller-only: the server reads
+// request.user and ignores any user param.
+import { useQueryClient } from '@tanstack/react-query';
+import { useMe } from '../client/runtime';
+import { toast } from '../ui';
+import {
+    ALL_KINDS, NOTIFICATION_CHANNELS, setNotificationPreferences,
+    type NotificationChannel, type NotificationKind, type NotificationPrefsMap as Prefs,
+    type NotificationPreferencesResponse,
+} from './api';
+import { accountKeys, useNotificationPreferences } from './models';
+
+const CHANNEL_LABEL: Record<NotificationChannel, string> = { email: 'Email', push: 'Push', in_app: 'In app' };
+
+export const DEFAULT_NOTIFICATION_KINDS: NotificationKind[] = [{ kind: 'general', label: 'General' }];
+
+function titleCase(kind: string): string {
+    return kind.replace(/[_.-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** prop kinds ▸ server catalogue ▸ stored kinds ▸ "General". */
+export function resolveNotificationKinds(
+    kinds: NotificationKind[] | undefined,
+    serverKinds: NotificationKind[] | null | undefined,
+    preferences: Prefs | undefined,
+): NotificationKind[] {
+    const base = (kinds ?? serverKinds ?? []).filter((k) => k.kind !== ALL_KINDS);
+    const listed = new Set(base.map((k) => k.kind));
+    const stored = Object.keys(preferences ?? {})
+        .filter((kind) => kind !== ALL_KINDS && !listed.has(kind))
+        .sort()
+        .map((kind) => ({ kind, label: titleCase(kind) }));
+    const all = [...base, ...stored];
+    return all.length ? all : DEFAULT_NOTIFICATION_KINDS;
+}
+
+export interface NotificationPreferencesProps {
+    /** The kinds this app sends (label/description/channels). Overrides the server catalogue. */
+    kinds?: NotificationKind[];
+    /** Sub-lines under the channel cards; defaults describe each channel. */
+    channelHints?: Partial<Record<NotificationChannel, string>>;
+}
+
+export function NotificationPreferences({ kinds, channelHints }: NotificationPreferencesProps) {
+    const qc = useQueryClient();
+    const { data: me } = useMe();
+    const uid = me?.id ?? null;
+    const key = accountKeys.notificationPreferences(uid);
+    const { data, isPending, isError, error } = useNotificationPreferences(uid);
+    const prefs = data?.preferences ?? {};
+    const rows = resolveNotificationKinds(kinds, data?.kinds, prefs);
+    const masterOn = (channel: NotificationChannel) => prefs[ALL_KINDS]?.[channel] !== false;
+
+    const write = async (kind: string, channel: NotificationChannel, next: boolean) => {
+        const prev = qc.getQueryData<NotificationPreferencesResponse>(key);
+        const current = prev?.preferences ?? {};
+        qc.setQueryData<NotificationPreferencesResponse>(key, {
+            kinds: prev?.kinds ?? null,
+            preferences: { ...current, [kind]: { ...(current[kind] ?? {}), [channel]: next } },
+        });
+        try {
+            const merged = await setNotificationPreferences({ [kind]: { [channel]: next } });
+            qc.setQueryData<NotificationPreferencesResponse>(key, (now) => ({ kinds: now?.kinds ?? prev?.kinds ?? null, preferences: merged }));
+        } catch (err) {
+            if (prev) qc.setQueryData(key, prev);
+            toast.error(err instanceof Error ? err.message : 'Failed to update notification settings');
+        }
+    };
+
+    const hints: Record<NotificationChannel, string> = {
+        email: channelHints?.email ?? (typeof me?.email === 'string' && me.email ? me.email : 'Your email address'),
+        push: channelHints?.push ?? 'Phones and apps',
+        in_app: channelHints?.in_app ?? 'Portal bell',
+    };
+
+    if (isPending) return <div className="acct-skel" aria-busy="true"><span className="skel skel-block" /></div>;
+    if (isError) return <p className="dim" role="alert">{error instanceof Error ? error.message : 'Failed to load notification settings.'}</p>;
+
+    return (
+        <div className="acct-notify">
+            <div className="acct-label">Channels</div>
+            <div className="acct-channels">
+                {NOTIFICATION_CHANNELS.map((channel) => (
+                    <label key={channel} className={`acct-channel${masterOn(channel) ? '' : ' is-off'}`}>
+                        <span className="acct-channel-text">
+                            <span className="acct-channel-name">{CHANNEL_LABEL[channel]}</span>
+                            <span className="acct-channel-hint" title={hints[channel]}>{hints[channel]}</span>
+                        </span>
+                        <input
+                            type="checkbox"
+                            role="switch"
+                            className="switch"
+                            checked={masterOn(channel)}
+                            aria-label={`${CHANNEL_LABEL[channel]} notifications`}
+                            onChange={(e) => void write(ALL_KINDS, channel, e.target.checked)}
+                        />
+                    </label>
+                ))}
+            </div>
+            <p className="acct-note">Turning a channel off silences everything below on that channel, including kinds added later.</p>
+
+            <div className="acct-grid" role="table" aria-label="What to send">
+                <div className="acct-grid-head" role="row">
+                    <span className="acct-label" role="columnheader">What to send</span>
+                    {NOTIFICATION_CHANNELS.map((channel) => (
+                        <span key={channel} className="acct-grid-col" role="columnheader">{CHANNEL_LABEL[channel]}</span>
+                    ))}
+                </div>
+                {rows.map((row) => (
+                    <div key={row.kind} className="acct-grid-row" role="row">
+                        <span className="acct-grid-kind" role="rowheader">
+                            <span className="acct-grid-label">{row.label}</span>
+                            {row.description && <span className="acct-grid-desc">{row.description}</span>}
+                        </span>
+                        {NOTIFICATION_CHANNELS.map((channel) => {
+                            const delivered = !row.channels || row.channels.includes(channel);
+                            if (!delivered) return <span key={channel} className="acct-grid-cell acct-grid-na" role="cell" aria-label={`${row.label} is not sent by ${CHANNEL_LABEL[channel]}`}>—</span>;
+                            const on = prefs[row.kind]?.[channel] !== false;
+                            return (
+                                <span key={channel} className="acct-grid-cell" role="cell">
+                                    <input
+                                        type="checkbox"
+                                        checked={on}
+                                        disabled={!masterOn(channel)}
+                                        title={masterOn(channel) ? undefined : `${CHANNEL_LABEL[channel]} is off for everything`}
+                                        aria-label={`${row.label} by ${CHANNEL_LABEL[channel].toLowerCase()}`}
+                                        onChange={(e) => void write(row.kind, channel, e.target.checked)}
+                                    />
+                                </span>
+                            );
+                        })}
+                    </div>
+                ))}
+            </div>
+        </div>
+    );
+}

package/src/account/PasskeyList.tsx

@@ -0,0 +1,144 @@
+// PasskeyList — one user's passkeys with rename / enable-disable / remove,
+// over /api/account/passkeys?user=<id> (the two REST-editable fields are
+// friendly_name and is_enabled; delete is real, CAN_DELETE). Generalised
+// from the admin User detail's module-private PasskeysModal so the
+// self-service AccountModal and the admin modal render ONE list.
+//
+// Authority: the live owner, or a global user-management grant. It is
+// re-read at every confirmation (permission ref) — losing it while a
+// confirm is open, or unmounting, refuses the pending write.
+import { useEffect, useRef } from 'react';
+import { useCan, useMe } from '../client/runtime';
+import { Badge, fmt, formModal, modal, toast } from '../ui';
+import { PasskeyModel, type PasskeyRow } from './credential-models';
+
+const USER_ADMIN_PERMISSIONS = ['sys.users', 'sys.manage_users'];
+
+export interface PasskeyListProps {
+    userId: number;
+    /** Offer Disable on enabled rows (admin). Enable on disabled rows is always offered. */
+    showDisable?: boolean;
+    /** Empty-state copy override. */
+    emptyText?: string;
+}
+
+const SHORT_DATE = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' });
+const SHORT_DATE_YEAR = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+
+/** "Aug 21" this year, "Aug 21, 2024" otherwise. Epoch seconds in. */
+export function shortDate(epochSeconds: number | null | undefined): string {
+    if (epochSeconds == null) return '—';
+    const d = new Date(epochSeconds * 1000);
+    if (Number.isNaN(d.getTime())) return '—';
+    return (d.getFullYear() === new Date().getFullYear() ? SHORT_DATE : SHORT_DATE_YEAR).format(d);
+}
+
+function passkeyIcon(row: PasskeyRow): string {
+    const transports = (row.transports ?? '').split(',');
+    if (transports.includes('usb') || transports.includes('nfc')) return 'bi-usb-drive';
+    const name = (row.friendly_name ?? '').toLowerCase();
+    if (/iphone|android|phone/.test(name)) return 'bi-phone';
+    return 'bi-fingerprint';
+}
+
+export function PasskeyList({ userId, showDisable = true, emptyText }: PasskeyListProps) {
+    const admin = useCan(USER_ADMIN_PERMISSIONS).can;
+    const meId = useMe().data?.id;
+    const isSelf = meId === userId;
+    const allowed = isSelf || admin;
+    const permission = useRef(allowed); permission.current = allowed;
+    useEffect(() => { permission.current = allowed; return () => { permission.current = false; }; }, [allowed]);
+    const { data, isPending, isError, error } = PasskeyModel.useList({ user: userId, size: 25, sort: '-created' });
+    const save = PasskeyModel.useSave();
+    const del = PasskeyModel.useDelete();
+    const rows = data?.rows ?? [];
+    const label = (row: PasskeyRow | undefined) => row?.friendly_name || 'Unnamed passkey';
+
+    const rename = async (row: PasskeyRow) => {
+        const result = await formModal({
+            title: 'Rename passkey',
+            submitText: 'Save',
+            fields: [{
+                name: 'friendly_name', type: 'text', label: 'Name', required: true,
+                placeholder: 'MacBook Pro · Touch ID', help: 'It only has to make sense to you.',
+            }],
+            initial: { friendly_name: row.friendly_name ?? '' },
+        });
+        const name = result?.friendly_name;
+        if (!permission.current || typeof name !== 'string' || !name.trim()) return;
+        try {
+            await save.mutateAsync({ id: row.id, changes: { friendly_name: name.trim() } });
+            toast.success('Passkey renamed');
+        } catch (err) {
+            toast.error(err instanceof Error ? err.message : 'Failed to rename passkey');
+        }
+    };
+
+    const setEnabled = async (row: PasskeyRow, next: boolean) => {
+        if (!permission.current) return;
+        try {
+            await save.mutateAsync({ id: row.id, changes: { is_enabled: next } });
+            toast.success(next ? 'Passkey enabled' : 'Passkey disabled');
+        } catch (err) {
+            toast.error(err instanceof Error ? err.message : 'Failed to update passkey');
+        }
+    };
+
+    const remove = async (row: PasskeyRow) => {
+        const ok = await modal.confirm({
+            title: 'Remove passkey',
+            message: isSelf
+                ? <>Remove <b>{label(row)}</b> ({row.rp_id || 'unknown site'}) from your account? You&rsquo;ll need to add it again to sign in with it. The device itself is not erased.</>
+                : <>Remove <b>{label(row)}</b> for {row.rp_id || 'unknown relying party'}, user #{userId}? Reenrollment is required to restore it. The physical device is not erased.</>,
+            confirmText: 'Remove',
+            danger: true,
+        });
+        if (!ok || !permission.current) return;
+        try {
+            await del.mutateAsync({ id: row.id });
+            toast.success('Passkey removed');
+        } catch (err) {
+            toast.error(err instanceof Error ? err.message : 'Failed to remove passkey');
+        }
+    };
+
+    if (isPending) return <div className="acct-skel" aria-busy="true"><span className="skel skel-block" /></div>;
+    if (isError) return <p className="dim" role="alert">{error instanceof Error ? error.message : 'Failed to load passkeys.'}</p>;
+    if (rows.length === 0) {
+        return (
+            <div className="us-empty">
+                <i className="bi bi-fingerprint" />
+                <div>{emptyText ?? 'No passkeys registered'}</div>
+            </div>
+        );
+    }
+    const busy = !allowed || save.isPending || del.isPending;
+    return (
+        <ul className="acct-cards" aria-label="Passkeys">
+            {rows.map((p) => (
+                <li key={p.id} className={`acct-card${p.is_enabled ? '' : ' is-off'}`}>
+                    <span className="acct-card-icon" aria-hidden="true"><i className={`bi ${passkeyIcon(p)}`} /></span>
+                    <div className="acct-card-info">
+                        <span className="acct-card-title">
+                            {label(p)}
+                            {!p.is_enabled && <Badge tone="muted">Disabled</Badge>}
+                        </span>
+                        <span className="acct-card-meta">
+                            Added {shortDate(p.created)} · {p.last_used ? `last used ${fmt.relative(p.last_used)}` : 'never used'}
+                        </span>
+                    </div>
+                    <div className="acct-card-actions" inert={busy}>
+                        <button type="button" className="btn btn-compact" aria-label={`Rename ${label(p)}`} onClick={() => void rename(p)}>Rename</button>
+                        {!p.is_enabled && (
+                            <button type="button" className="btn btn-compact" aria-label={`Enable ${label(p)}`} onClick={() => void setEnabled(p, true)}>Enable</button>
+                        )}
+                        {p.is_enabled && showDisable && (
+                            <button type="button" className="btn btn-compact" aria-label={`Disable ${label(p)}`} onClick={() => void setEnabled(p, false)}>Disable</button>
+                        )}
+                        <button type="button" className="btn btn-compact acct-danger" aria-label={`Remove ${label(p)}`} onClick={() => void remove(p)}>Remove</button>
+                    </div>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/account/api.ts

@@ -0,0 +1,236 @@
+// account/api — thin, typed wrappers over the django-mojo self-service
+// account wire (the AccountModal's transport). Each function is ONE call
+// through the single envelope boundary (mojoCall); every server-gated call
+// (@requires_fresh_auth) runs under withFreshAuth so a 440 re-prompts over
+// the current screen and retries once.
+//
+// One-time values (TOTP secret/uri/QR, recovery codes, the phone-change
+// session_token) are RETURNED to the caller and never written to any
+// TanStack cache here — callers keep them in component state for the life of
+// the dialog that shows them.
+//
+// Wire authority: django-mojo account/rest/totp.py, rest/user.py,
+// rest/verify.py, rest/notification_prefs.py (read 2026-10-07).
+import { MojoError } from '../client/errors';
+import { mojoCall } from '../client/client';
+import { withFreshAuth } from '../client/auth';
+
+export {
+    confirmEmailChange,
+    isPasskeyRegistrationSupported,
+    passkeyErrorMessage,
+    registerPasskey,
+    revokeOtherSessions,
+    suggestPasskeyName,
+    type RegisteredPasskey,
+} from '../client/auth';
+
+const message = (body: { message?: string }, fallback: string) =>
+    typeof body.message === 'string' && body.message ? body.message : fallback;
+
+// ── Authenticator app (TOTP) ──────────────────────────────────────────
+
+export interface TotpSetup {
+    /** Base32 secret for manual entry. One-time: keep in dialog state only. */
+    secret: string;
+    /** otpauth:// provisioning URI. */
+    uri: string;
+    /** `data:image/…;base64,` QR of `uri`, or null when it is not a safe data image. */
+    qrCode: string | null;
+}
+
+const SAFE_QR = /^data:image\/(png|svg\+xml);base64,[A-Za-z0-9+/=]+$/;
+
+/** Only a base64 PNG/SVG data URL may become an <img src>. */
+export function safeQrDataUrl(value: unknown): string | null {
+    return typeof value === 'string' && SAFE_QR.test(value) ? value : null;
+}
+
+/**
+ * `POST /api/account/totp/setup` (fresh auth). Replaces any stored secret and
+ * DISABLES an active authenticator until `confirmTotp` succeeds.
+ */
+export async function startTotpSetup(): Promise<TotpSetup> {
+    const body = await withFreshAuth(() => mojoCall('/api/account/totp/setup', { method: 'POST', body: {} }));
+    const data = (body.data ?? {}) as { secret?: unknown; uri?: unknown; qr_code?: unknown };
+    return {
+        secret: typeof data.secret === 'string' ? data.secret : '',
+        uri: typeof data.uri === 'string' ? data.uri : '',
+        qrCode: safeQrDataUrl(data.qr_code),
+    };
+}
+
+/**
+ * `POST /api/account/totp/confirm {code}` (fresh auth) → the 8 recovery codes,
+ * shown ONCE. The server also sets requires_mfa.
+ */
+export async function confirmTotp(code: string): Promise<string[]> {
+    const body = await withFreshAuth(() => mojoCall('/api/account/totp/confirm', { method: 'POST', body: { code } }));
+    return recoveryCodesOf(body.data);
+}
+
+/** `DELETE /api/account/totp` (fresh auth). requires_mfa is NOT cleared. */
+export async function disableTotp(): Promise<void> {
+    await withFreshAuth(() => mojoCall('/api/account/totp', { method: 'DELETE' }));
+}
+
+export interface RecoveryCodeStatus {
+    enrolled: boolean;
+    remaining: number;
+}
+
+/**
+ * Enrollment + remaining recovery codes from `GET …/totp/recovery-codes` —
+ * the only self-visible "authenticator is on" signal (400 = not enrolled).
+ * The masked hints are dropped here so a cached status never holds them.
+ */
+export async function getRecoveryCodeStatus(): Promise<RecoveryCodeStatus> {
+    try {
+        const body = await mojoCall('/api/account/totp/recovery-codes');
+        const data = (body.data ?? {}) as { remaining?: unknown };
+        return { enrolled: true, remaining: typeof data.remaining === 'number' ? data.remaining : 0 };
+    } catch (error) {
+        if (error instanceof MojoError && error.status === 400) return { enrolled: false, remaining: 0 };
+        throw error;
+    }
+}
+
+/** The masked hints (`a4k2-xxxx-xxxx`) for the View dialog — component state only. */
+export async function getMaskedRecoveryCodes(): Promise<{ remaining: number; codes: string[] }> {
+    const body = await mojoCall('/api/account/totp/recovery-codes');
+    const data = (body.data ?? {}) as { remaining?: unknown; codes?: unknown };
+    return {
+        remaining: typeof data.remaining === 'number' ? data.remaining : 0,
+        codes: Array.isArray(data.codes) ? data.codes.filter((c): c is string => typeof c === 'string') : [],
+    };
+}
+
+/** `POST …/recovery-codes/regenerate {code}` (fresh auth) → a fresh set, shown ONCE. */
+export async function regenerateRecoveryCodes(code: string): Promise<string[]> {
+    const body = await withFreshAuth(() => mojoCall('/api/account/totp/recovery-codes/regenerate', { method: 'POST', body: { code } }));
+    return recoveryCodesOf(body.data);
+}
+
+function recoveryCodesOf(data: unknown): string[] {
+    const codes = (data as { recovery_codes?: unknown } | undefined)?.recovery_codes;
+    return Array.isArray(codes) ? codes.filter((c): c is string => typeof c === 'string') : [];
+}
+
+// ── Password ──────────────────────────────────────────────────────────
+
+/**
+ * Self password change: `POST /api/user/me {current_password, new_password}`.
+ * Wrong/missing current → 400 with the server's message. Not fresh-auth
+ * gated and no session rotation (user.py:819-828).
+ */
+export async function changePassword(currentPassword: string, newPassword: string): Promise<void> {
+    await mojoCall('/api/user/me', {
+        method: 'POST',
+        body: { current_password: currentPassword, new_password: newPassword },
+    });
+}
+
+// ── Email / phone changes and verification ────────────────────────────
+
+/**
+ * `POST /api/auth/email/change/request {email, method:'code'}` (fresh auth).
+ * A 6-digit code goes to the NEW address; finish with confirmEmailChange().
+ */
+export async function requestEmailChange(email: string): Promise<string> {
+    const body = await withFreshAuth(() => mojoCall('/api/auth/email/change/request', {
+        method: 'POST',
+        body: { email, method: 'code' },
+    }));
+    return message(body, 'A verification code has been sent to your new email address.');
+}
+
+export interface PhoneChangeTicket {
+    /** One-time token pairing the code with this request. Dialog state only. */
+    sessionToken: string;
+    message: string;
+}
+
+/**
+ * `POST /api/auth/phone/change/request {phone_number}` (fresh auth). The
+ * session_token rides at the envelope's TOP level, not under `data`.
+ */
+export async function requestPhoneChange(phoneNumber: string): Promise<PhoneChangeTicket> {
+    const body = await withFreshAuth(() => mojoCall('/api/auth/phone/change/request', {
+        method: 'POST',
+        body: { phone_number: phoneNumber },
+    }));
+    const token = (body as { session_token?: unknown }).session_token;
+    if (typeof token !== 'string' || !token) throw new MojoError('The server did not return a phone change session', 0);
+    return { sessionToken: token, message: message(body, 'A verification code has been sent to your new phone number.') };
+}
+
+/** `POST /api/auth/phone/change/confirm {session_token, code}` — commits + verifies the number. */
+export async function confirmPhoneChange(sessionToken: string, code: string): Promise<string> {
+    const body = await mojoCall('/api/auth/phone/change/confirm', {
+        method: 'POST',
+        body: { session_token: sessionToken, code },
+    });
+    return message(body, 'Phone number updated successfully.');
+}
+
+/** `POST /api/auth/verify/{email|phone}/send` — a code (email asks for `method:'code'`). */
+export async function sendVerificationCode(channel: 'email' | 'phone'): Promise<string> {
+    const body = await mojoCall(`/api/auth/verify/${channel}/send`, {
+        method: 'POST',
+        body: channel === 'email' ? { method: 'code' } : {},
+    });
+    return message(body, 'Verification code sent');
+}
+
+/** `POST /api/auth/verify/{email|phone}/confirm {code}`. */
+export async function confirmVerificationCode(channel: 'email' | 'phone', code: string): Promise<string> {
+    const body = await mojoCall(`/api/auth/verify/${channel}/confirm`, { method: 'POST', body: { code } });
+    return message(body, channel === 'email' ? 'Email verified' : 'Phone verified');
+}
+
+/** `POST /api/auth/username/change {username}` (fresh auth) → the saved username. */
+export async function changeUsername(username: string): Promise<string> {
+    const body = await withFreshAuth(() => mojoCall('/api/auth/username/change', { method: 'POST', body: { username } }));
+    const saved = (body.data as { username?: unknown } | undefined)?.username;
+    return typeof saved === 'string' ? saved : username;
+}
+
+// ── Notification preferences ──────────────────────────────────────────
+
+export type NotificationChannel = 'email' | 'push' | 'in_app';
+export const NOTIFICATION_CHANNELS: readonly NotificationChannel[] = ['email', 'push', 'in_app'];
+/** The reserved all-kinds entry: `"*".<channel> === false` silences a channel. */
+export const ALL_KINDS = '*';
+
+export type NotificationPrefsMap = Record<string, Partial<Record<NotificationChannel, boolean>>>;
+
+export interface NotificationKind {
+    kind: string;
+    label: string;
+    description?: string;
+    /** Channels this kind is delivered on; null/absent = all. */
+    channels?: NotificationChannel[] | null;
+}
+
+export interface NotificationPreferencesResponse {
+    preferences: NotificationPrefsMap;
+    /** The server's registered kinds, when it ships the registry. */
+    kinds: NotificationKind[] | null;
+}
+
+export async function getNotificationPreferences(): Promise<NotificationPreferencesResponse> {
+    const body = await mojoCall('/api/account/notification/preferences');
+    const data = (body.data ?? {}) as { preferences?: unknown; kinds?: unknown };
+    const preferences = data.preferences && typeof data.preferences === 'object' ? data.preferences as NotificationPrefsMap : {};
+    const kinds = Array.isArray(data.kinds)
+        ? data.kinds.filter((k): k is NotificationKind => Boolean(k) && typeof (k as NotificationKind).kind === 'string' && (k as NotificationKind).kind !== ALL_KINDS)
+        : null;
+    return { preferences, kinds };
+}
+
+/** Partial update `{preferences: {kind: {channel: bool}}}` → the merged map. */
+export async function setNotificationPreferences(partial: NotificationPrefsMap): Promise<NotificationPrefsMap> {
+    const body = await mojoCall('/api/account/notification/preferences', { method: 'POST', body: { preferences: partial } });
+    const data = (body.data ?? {}) as { preferences?: unknown };
+    return data.preferences && typeof data.preferences === 'object' ? data.preferences as NotificationPrefsMap : {};
+}