portal-mojo 0.1.0

package/src/client/record-feed.ts

@@ -0,0 +1,329 @@
+import { mojoList, mojoSave } from './client';
+
+export type RecordFeedId = number | string;
+export type RecordFeedTimestamp = number | string;
+export type RecordFeedAdapterKind = 'ticket-note' | 'incident-history';
+
+export interface FileReference {
+    id: number;
+    filename: string;
+    content_type: string;
+    category: string | null;
+}
+
+export interface RecordFeedNoteDraft {
+    text: string;
+    attachment?: FileReference;
+}
+
+export interface RecordFeedAuthor {
+    id: RecordFeedId | null;
+    name: string;
+    avatarUrl?: string;
+}
+
+export interface RecordFeedItemBase {
+    id: RecordFeedId;
+    created: RecordFeedTimestamp;
+    content: string;
+    author: RecordFeedAuthor;
+    metadata: Record<string, unknown>;
+    /** Wire-shaped django-mojo row; sensitive-domain adapters may sanitize it. */
+    raw: Record<string, unknown>;
+    attachment?: FileReference | null;
+    /** Client-only marker used by adapter-mode optimistic rows. */
+    pending?: boolean;
+}
+
+export interface RecordFeedComment extends RecordFeedItemBase {
+    kind: 'comment';
+}
+
+export interface RecordFeedAssistantNote extends RecordFeedItemBase {
+    kind: 'assistant';
+}
+
+export interface RecordFeedSystemEvent extends RecordFeedItemBase {
+    kind: 'system';
+    event?: string;
+}
+
+export interface RecordFeedStatusEvent extends RecordFeedItemBase {
+    kind: 'status';
+    from: string | null;
+    to: string | null;
+}
+
+export type RecordFeedItem =
+    | RecordFeedComment
+    | RecordFeedAssistantNote
+    | RecordFeedSystemEvent
+    | RecordFeedStatusEvent;
+
+export interface RecordFeedPage {
+    /** Chronological: oldest of the latest window first. */
+    items: RecordFeedItem[];
+    count: number;
+    hasEarlier: boolean;
+}
+
+export type RecordFeedQueryKey = readonly [
+    'record-feed',
+    RecordFeedAdapterKind,
+    RecordFeedId,
+    RecordFeedId | null,
+];
+
+export interface RecordFeedAdapter {
+    kind: RecordFeedAdapterKind;
+    parentId: RecordFeedId;
+    groupId: RecordFeedId | null;
+    /** Stable, structural and record-scoped. Safe for exact Query operations. */
+    queryKey: RecordFeedQueryKey;
+    fetch(): Promise<RecordFeedPage>;
+    addNote(draft: RecordFeedNoteDraft): Promise<RecordFeedItem>;
+    /** Sanitizes optimistic cache and mutation variables for sensitive domains. */
+    sanitizeDraft?(text: string): string;
+}
+
+export interface FeedAdapterOptions {
+    groupId?: RecordFeedId | null;
+    sanitizeRow?: (row: Record<string, unknown>) => Record<string, unknown>;
+    sanitizeText?: (text: string) => string;
+}
+
+interface WireFeedUser {
+    id?: RecordFeedId | null;
+    display_name?: unknown;
+    username?: unknown;
+    email?: unknown;
+    avatar?: unknown;
+}
+
+interface WireFeedRow extends Record<string, unknown> {
+    id?: unknown;
+    created?: unknown;
+    user?: unknown;
+    note?: unknown;
+    metadata?: unknown;
+    kind?: unknown;
+}
+
+function objectOrEmpty(value: unknown): Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : {};
+}
+
+export function safeFileReference(value: unknown): FileReference | null {
+    const raw = objectOrEmpty(value);
+    const id = raw.id;
+    if (typeof id !== 'number' || !Number.isSafeInteger(id) || id <= 0
+        || typeof raw.filename !== 'string' || !raw.filename
+        || typeof raw.content_type !== 'string' || !raw.content_type
+        || (raw.category !== null && raw.category !== undefined && typeof raw.category !== 'string')) return null;
+    return { id, filename: raw.filename, content_type: raw.content_type, category: raw.category == null ? null : raw.category };
+}
+
+/** Rebuild media before any domain sanitizer, normalizer, or cache sees it. */
+export function safeRecordFeedRow(raw: Record<string, unknown>): Record<string, unknown> {
+    return { ...raw, media: safeFileReference(raw.media) };
+}
+
+function optionalText(value: unknown): string | null {
+    if (value === null || value === undefined || value === '') return null;
+    return String(value);
+}
+
+function avatarUrl(value: unknown): string | undefined {
+    if (typeof value === 'string' && value) return value;
+    const avatar = objectOrEmpty(value);
+    return typeof avatar.url === 'string' && avatar.url ? avatar.url : undefined;
+}
+
+function normalizeAuthor(value: unknown, fallback: string): RecordFeedAuthor {
+    const user = objectOrEmpty(value) as WireFeedUser;
+    const name = optionalText(user.display_name)
+        ?? optionalText(user.username)
+        ?? optionalText(user.email)
+        ?? fallback;
+    return {
+        id: typeof user.id === 'number' || typeof user.id === 'string' ? user.id : null,
+        name,
+        avatarUrl: avatarUrl(user.avatar),
+    };
+}
+
+function structuredStatus(metadata: Record<string, unknown>): { from: string | null; to: string | null } | null {
+    const nested = objectOrEmpty(metadata.status_change);
+    const isStatus = metadata.type === 'status_change' || Object.keys(nested).length > 0;
+    if (!isStatus) return null;
+    const from = optionalText(metadata.old_status ?? nested.old_status ?? nested.from);
+    const to = optionalText(metadata.new_status ?? nested.new_status ?? nested.to);
+    // A type marker without either structured endpoint is not enough. In
+    // particular, never recover a transition by regexing the prose note.
+    return from !== null || to !== null ? { from, to } : null;
+}
+
+function isCanonicalAssistant(row: WireFeedRow, metadata: Record<string, unknown>, content: string): boolean {
+    if (content.startsWith('[LLM Agent]')) return true;
+    if (row.kind === 'handler:llm') return true;
+    if (metadata.handler === 'llm' || metadata.origin === 'llm') return true;
+    const action = objectOrEmpty(metadata.action);
+    return action.handler === 'llm';
+}
+
+function isLegacyAssistant(row: WireFeedRow, metadata: Record<string, unknown>): boolean {
+    // These older ticket records encoded assistant context without a handler.
+    // Only null-user rows qualify; null user on its own is always System.
+    if (row.user !== null && row.user !== undefined) return false;
+    const action = objectOrEmpty(metadata.action);
+    if (Object.keys(action).length > 0) return true;
+    return metadata.type === 'context' && metadata.references !== null && metadata.references !== undefined;
+}
+
+/**
+ * Normalize ticket notes and incident history through one strict precedence:
+ * structured status → canonical LLM → legacy null-user LLM → user → system.
+ */
+export function normalizeRecordFeedItem(raw: Record<string, unknown>): RecordFeedItem {
+    const safeRaw = safeRecordFeedRow(raw);
+    const row = safeRaw as WireFeedRow;
+    const metadata = objectOrEmpty(row.metadata);
+    const content = optionalText(row.note) ?? '';
+    const id = typeof row.id === 'number' || typeof row.id === 'string'
+        ? row.id
+        : `missing-${optionalText(row.created) ?? 'record'}`;
+    const created = typeof row.created === 'number' || typeof row.created === 'string'
+        ? row.created
+        : 0;
+    const status = structuredStatus(metadata);
+
+    if (status) {
+        return {
+            id, created, content, metadata, raw: safeRaw, attachment: safeFileReference(safeRaw.media),
+            kind: 'status', from: status.from, to: status.to,
+            author: normalizeAuthor(row.user, 'System'),
+        };
+    }
+
+    if (isCanonicalAssistant(row, metadata, content) || isLegacyAssistant(row, metadata)) {
+        return {
+            id, created, content, metadata, raw: safeRaw, attachment: safeFileReference(safeRaw.media),
+            kind: 'assistant',
+            author: normalizeAuthor(row.user, 'AI Agent'),
+        };
+    }
+
+    if (row.user !== null && row.user !== undefined) {
+        return {
+            id, created, content, metadata, raw: safeRaw, attachment: safeFileReference(safeRaw.media),
+            kind: 'comment',
+            author: normalizeAuthor(row.user, 'Unknown user'),
+        };
+    }
+
+    return {
+        id, created, content, metadata, raw: safeRaw, attachment: safeFileReference(safeRaw.media),
+        kind: 'system', event: optionalText(row.kind) ?? optionalText(metadata.type) ?? undefined,
+        author: normalizeAuthor(null, 'System'),
+    };
+}
+
+export function recordFeedQueryKey(
+    kind: RecordFeedAdapterKind,
+    parentId: RecordFeedId,
+    groupId: RecordFeedId | null = null,
+): RecordFeedQueryKey {
+    return ['record-feed', kind, parentId, groupId] as const;
+}
+
+interface AdapterConfig {
+    kind: RecordFeedAdapterKind;
+    endpoint: string;
+    parentId: RecordFeedId;
+    groupId: RecordFeedId | null;
+    postKind?: string;
+    sanitizeRow?: (row: Record<string, unknown>) => Record<string, unknown>;
+    sanitizeText?: (text: string) => string;
+}
+
+function makeAdapter(config: AdapterConfig): RecordFeedAdapter {
+    const { kind, endpoint, parentId, groupId, postKind, sanitizeRow, sanitizeText } = config;
+    const queryKey = recordFeedQueryKey(kind, parentId, groupId);
+
+    return {
+        kind,
+        parentId,
+        groupId,
+        queryKey,
+        sanitizeDraft: (text) => sanitizeText ? sanitizeText(text) : text,
+        async fetch() {
+            const page = await mojoList<Record<string, unknown>>(endpoint, {
+                parent: parentId,
+                ...(groupId === null ? {} : { group: groupId }),
+                graph: 'default',
+                sort: '-created',
+                start: 0,
+                size: 100,
+            });
+            const newestFirst = page.rows.map((row) => {
+                const rebuilt = safeRecordFeedRow(row);
+                return normalizeRecordFeedItem(sanitizeRow ? sanitizeRow(rebuilt) : rebuilt);
+            });
+            return {
+                items: newestFirst.reverse(),
+                count: page.count,
+                hasEarlier: page.count > page.rows.length,
+            };
+        },
+        async addNote(draft) {
+            const safeText = sanitizeText ? sanitizeText(draft.text) : draft.text;
+            const raw = await mojoSave<Record<string, unknown>>(endpoint, null, {
+                parent: parentId,
+                // django-mojo's generic REST saver consumes ForeignKeys as a
+                // bare primary key (`{"group": 5}`), permission-checks the
+                // related row, then assigns it. Keep create scope identical
+                // to the group-aware list/cache scope.
+                ...(groupId === null ? {} : { group: groupId }),
+                note: safeText,
+                ...(draft.attachment ? { media: draft.attachment.id } : {}),
+                ...(postKind ? { kind: postKind } : {}),
+            });
+            const rebuilt = safeRecordFeedRow(raw);
+            const safeRaw = sanitizeRow ? sanitizeRow(rebuilt) : rebuilt;
+            return normalizeRecordFeedItem(safeRaw);
+        },
+    };
+}
+
+/** Ticket comments and ticket status-change records. */
+export function createTicketNoteAdapter(
+    parentId: RecordFeedId,
+    options: FeedAdapterOptions = {},
+): RecordFeedAdapter {
+    return makeAdapter({
+        kind: 'ticket-note',
+        endpoint: '/api/incident/ticket/note',
+        parentId,
+        groupId: options.groupId ?? null,
+        sanitizeRow: options.sanitizeRow,
+        sanitizeText: options.sanitizeText,
+    });
+}
+
+/** Incident comments and automated incident history. */
+export function createIncidentHistoryAdapter(
+    parentId: RecordFeedId,
+    options: FeedAdapterOptions = {},
+): RecordFeedAdapter {
+    return makeAdapter({
+        kind: 'incident-history',
+        endpoint: '/api/incident/incident/history',
+        parentId,
+        groupId: options.groupId ?? null,
+        postKind: 'comment',
+        sanitizeRow: options.sanitizeRow,
+        sanitizeText: options.sanitizeText,
+    });
+}

package/src/client/safe-export.ts

@@ -0,0 +1,71 @@
+import { downloadBlob, mojoList } from './client';
+import type { Params } from './types';
+
+export interface SafeExportField<T> {
+    key: string;
+    label?: string;
+    value?: (row: T) => unknown;
+}
+
+export interface SafeExporterOptions<T> {
+    endpoint: string;
+    filename: string;
+    fields: readonly SafeExportField<T>[];
+    sanitizeRow: (row: T) => T;
+    pageSize?: number;
+    maxRows?: number;
+}
+
+function scalar(value: unknown): string | number | boolean | null {
+    if (value == null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value ?? null;
+    return JSON.stringify(value) ?? String(value);
+}
+
+function csvCell(value: unknown): string {
+    const text = String(value ?? '');
+    return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+/**
+ * Build a bounded, client-side exporter for domains whose server formats
+ * expose unsafe fields. Rows are sanitized before they are accumulated and
+ * only the declared projection can reach the resulting file.
+ */
+export function createSafeExporter<T>(options: SafeExporterOptions<T>) {
+    const pageSize = Math.min(250, Math.max(1, options.pageSize ?? 100));
+    const maxRows = Math.max(pageSize, options.maxRows ?? 10_000);
+    return async (format: 'csv' | 'json', normalizedParams: Params): Promise<void> => {
+        const base: Params = { ...normalizedParams };
+        for (const key of ['start', 'size', 'page', 'download_format', 'filename']) delete base[key];
+        const projected: Record<string, string | number | boolean | null>[] = [];
+        let start = 0;
+        let count = Infinity;
+        while (start < count && projected.length < maxRows) {
+            const page = await mojoList<T>(options.endpoint, { ...base, start, size: pageSize });
+            count = page.count;
+            for (const wireRow of page.rows) {
+                const row = options.sanitizeRow(wireRow);
+                const record: Record<string, string | number | boolean | null> = {};
+                for (const field of options.fields) {
+                    const value = field.value
+                        ? field.value(row)
+                        : (row as unknown as Record<string, unknown>)[field.key];
+                    record[field.label ?? field.key] = scalar(value);
+                }
+                projected.push(record);
+                if (projected.length >= maxRows) break;
+            }
+            if (!page.rows.length) break;
+            start += page.rows.length;
+        }
+        if (count > maxRows) throw new Error(`Export exceeds the ${maxRows.toLocaleString()} row safety limit; narrow the filters and try again.`);
+        const filename = `${options.filename}.${format}`;
+        if (format === 'json') {
+            downloadBlob(new Blob([JSON.stringify(projected, null, 2)], { type: 'application/json' }), filename);
+            return;
+        }
+        const headers = options.fields.map((field) => field.label ?? field.key);
+        const body = [headers.map(csvCell).join(','), ...projected.map((row) => headers.map((key) => csvCell(row[key])).join(','))].join('\r\n');
+        downloadBlob(new Blob([body], { type: 'text/csv;charset=utf-8' }), filename);
+    };
+}

package/src/client/types.ts

@@ -0,0 +1,278 @@
+// Shared types for the mojo portal baseline.
+
+// Type-only — erased at compile time; zod ships as a portal-mojo dependency
+// (the single sanctioned dependency, added with B3 FormView validation).
+import type { ZodType } from 'zod';
+
+/** django-mojo list response body (inside the envelope): rows + paging meta. */
+export interface MojoList<T> {
+    rows: T[];
+    count: number;
+    start: number;
+    size: number;
+}
+
+/** Wire params: everything the server understands is a flat query dict. */
+export type Params = Record<string, string | number | boolean | null | undefined>;
+
+// ── SchemaForm field language (data side) ─────────────────────────────
+// The TYPES live here because model definitions (defineModel) CARRY form
+// configs as plain data — web-mojo's User.ADD_FORM/EDIT_FORM heritage.
+// Rendering stays in portal-mojo/ui (SchemaForm/formModal re-export these).
+
+/**
+ * One value as a controlled form input holds it (server rows may carry
+ * numbers/null). Arrays joined B4 (#1278) for the list-valued registry types
+ * (multiselect ids, collection-multiselect ids, daterange pairs) — they ride
+ * the JSON save body as real lists.
+ */
+export type FieldValue = string | number | boolean | null | Array<string | number>;
+export type FieldValues = Record<string, FieldValue>;
+
+/**
+ * Declarative conditional visibility — FormBuilder.js:863-888 semantics:
+ * the controlling field's value is String()-coerced and matched against the
+ * allowed list; `negate` flips the result.
+ */
+export interface ShowWhenRule {
+    /** Controlling field name (dotted names allowed, e.g. 'metadata.kind'). */
+    field: string;
+    value: FieldValue | FieldValue[];
+    negate?: boolean;
+}
+/** Either the declarative rule or a predicate over the live form values. */
+export type ShowWhen = ShowWhenRule | ((values: FieldValues) => boolean);
+
+/**
+ * Field types. The first row are the BUILTINS SchemaForm/FormView render
+ * inline; everything after resolves through the ui field-type REGISTRY
+ * (ui/field-registry — web-mojo INPUT_TYPES + FormBuilder aliases carried
+ * verbatim). `(string & {})` keeps the union open for app-registered types
+ * (registerFieldType) without losing autocompletion on the known names.
+ * An unknown name renders a text input WITH one console.warn — never nothing.
+ */
+export type FieldType =
+    | 'text' | 'email' | 'tel' | 'select' | 'switch' | 'textarea'
+    | 'file' | 'image'
+    | 'tag' | 'tags'
+    | 'multiselect'
+    | 'collection' | 'collectionmultiselect' | 'collection-multiselect'
+    | 'combo' | 'combobox' | 'autocomplete'
+    | 'address'
+    | 'datepicker' | 'monthpicker' | 'yearpicker'
+    | 'daterange' | 'monthrange' | 'yearrange'
+    | 'timepicker' | 'datetimepicker' | 'timezone'
+    | (string & {});
+
+/** A select/multiselect/combo option as Field data carries it. */
+export interface FieldOption {
+    value: string | number;
+    label: string;
+    /** ComboBox: muted second line in the dropdown. */
+    description?: string;
+    /** MultiSelectDropdown: row refuses to toggle. */
+    disabled?: boolean;
+}
+
+/** Structural image-editor options kept client-side so model field data never imports ui. */
+export interface FieldImageEditOptions {
+    filename?: string;
+    title?: string;
+    size?: 'sm' | 'md' | 'lg';
+    startMode?: string;
+    modes?: readonly string[];
+    maxHistory?: number;
+    saveText?: string;
+    crop?: {
+        aspectRatio?: number | null;
+        minCropSize?: number;
+        fixedCropSize?: { width: number; height: number } | null;
+        cropAndScale?: { width: number; height: number } | null;
+    };
+}
+
+// Structural mirrors of ui/date/PresetRail's preset types (client code must
+// not import ui). String-returning `range()` (canonical YYYY-MM-DD strings)
+// is assignable to the rail's ParsedDate|string contract by covariance.
+export interface FieldPreset { label: string; range: () => { start: string; end: string }; divider?: undefined }
+export interface FieldPresetDivider { divider: true; label?: undefined; range?: undefined }
+/** 'default' picks the precision's built-in quick-range list. */
+export type FieldPresets = 'default' | true | Array<FieldPreset | FieldPresetDivider>;
+
+export interface Field {
+    /**
+     * Field name — the wire key. Dotted names ('permissions.manage_users')
+     * read/write nested dict values; FormView expands them to partial dicts
+     * on save (django-mojo MERGES dict bodies into JSONFields — rest.py
+     * on_rest_update_jsonfield).
+     */
+    name: string;
+    type: FieldType;
+    label: string;
+    placeholder?: string;
+    required?: boolean;
+    help?: string;
+    columns?: 6 | 12;
+    options?: FieldOption[];
+    /** Conditional visibility. Hidden fields never submit/save and their errors clear. */
+    showWhen?: ShowWhen;
+    /**
+     * Per-field zod schema, validated against the COMMITTED input value
+     * (string for text-ish types, boolean for switch). A failing parse blocks
+     * the save of that field only; the first issue's message shows in the
+     * field's error slot. Server-side validation stays authoritative.
+     */
+    schema?: ZodType;
+    /** Locks the control (registry types; builtins ignore it today). */
+    disabled?: boolean;
+
+    // file / image — one completed django-mojo File relation id or null.
+    /** Picker accept grammar (MIME values, wildcards, or .extensions). */
+    accept?: string | string[];
+    /** Local selection guard. Server policy remains authoritative. */
+    maxFileSize?: number;
+    /** Explicit upload destination. Omitted keys use the caller's personal scope. */
+    uploadDestination?: { fileManagerId?: number; groupId?: number; use?: string };
+    /** Called once when a completed upload is abandoned without authoritative attachment. */
+    onUploadOrphan?: (fileId: number) => void;
+    /** Image-only pre-upload edit. Omitted/false preserves the direct upload path. */
+    imageEdit?: boolean | FieldImageEditOptions;
+    /** Require an edited result; Cancel retains the local selection for retry/discard. */
+    imageEditRequired?: boolean;
+
+    // ── Registry-type props (B4 #1278) — see docs/forms.md value table ──
+    /** date/range pickers: grid precision. EXPLICIT value beats the
+     *  monthpicker/yearpicker/monthrange/yearrange alias mapping. */
+    precision?: 'day' | 'month' | 'year';
+    /**
+     * Wire shape override at the field-wire boundary (date/datetime types):
+     * 'epoch' (default — django-mojo datetimes are epoch SECONDS) or 'date'
+     * (canonical YYYY-MM-DD string — DateFields serialize OUT this way).
+     * timepicker reuses the prop for its serialization: 'iso' (default)
+     * or 'iana'.
+     */
+    outputFormat?: 'epoch' | 'date' | 'iso' | 'iana';
+    /** date/range pickers: trigger display tokens (YYYY MMM DD …). */
+    displayFormat?: string;
+    /** Bounds: canonical date strings for pickers, time strings for timepicker. */
+    min?: string | number;
+    max?: string | number;
+    /** daterange: the quick-range rail. */
+    presets?: FieldPresets;
+    /** daterange, day precision: 1 or 2 panes (default 2). */
+    months?: 1 | 2;
+    /** tag: the CSV joiner (one char). daterange: the display separator. */
+    separator?: string;
+    /** timepicker/datetimepicker clock: '24h' (default) | '12h'. */
+    timeFormat?: '12h' | '24h';
+    /** timepicker: minute stepping increment. */
+    step?: number;
+    /** timepicker/datetimepicker: enable the zone picker (an array is also the list). */
+    timezone?: boolean | string[];
+    /** Zone list for timezone/timepicker types (overrides the engine list). */
+    timezones?: string[];
+
+    // collection / collectionmultiselect ­— the server-backed pickers.
+    /** Any defineModel definition (structurally: carries the endpoint). */
+    model?: { endpoint: string };
+    /** Bare endpoint when no model definition exists. */
+    endpoint?: string;
+    /** Row field shown as the label (dot paths ok). Default 'name'. */
+    labelField?: string;
+    /** Row field used as the id (dot paths ok). Default 'id'. */
+    valueField?: string;
+    /** collection: rows fetched per search (`size` wire param). */
+    maxItems?: number;
+    /** collection: fetch the unsearched first page on open. Default true. */
+    emptyFetch?: boolean;
+    /** Search debounce ms (collection types). */
+    debounceMs?: number;
+    /** Fold the active group in as the `group` wire param (fetch HELD without one). */
+    requiresActiveGroup?: boolean;
+    /** Extra wire params merged into every picker fetch. */
+    defaultParams?: Params | (() => Params | null | undefined);
+    /** collectionmultiselect: search input above the list. */
+    enableSearch?: boolean;
+
+    // tag / combo extras.
+    maxTags?: number;
+    allowDuplicates?: boolean;
+    /** combo: typed text not matching an option commits as-is. Default true. */
+    allowCustom?: boolean;
+    /** combo: render option descriptions. */
+    showDescription?: boolean;
+    /** combo/timezone: cap on rendered suggestions. */
+    maxSuggestions?: number;
+
+    // address — provider details → declared form fields. address1 defaults
+    // to this field's own name; every other destination is opt-in.
+    addressFields?: Partial<Record<
+        'address1' | 'address2' | 'city' | 'state' | 'state_code' |
+        'postal_code' | 'country' | 'country_code' | 'latitude' |
+        'longitude' | 'formatted_address' | 'place_id', string
+    >>;
+    /** ISO country constraint for provider suggestions. Default US. */
+    country?: string;
+    /** Minimum characters before address suggestions. Default 3. */
+    minChars?: number;
+}
+
+/**
+ * SchemaForm's value map. Widened with B4 (#1278) from string|boolean to the
+ * full FieldValue union — registry types put lists (multiselect ids,
+ * daterange pairs), numbers (epoch dates, collection ids) and null (cleared
+ * pickers) in form state, and the submit payload carries them verbatim.
+ */
+export type FormData = Record<string, FieldValue>;
+
+/** A named model form — exactly what ui's formModal renders. */
+export interface ModelForm {
+    title: string;
+    fields: Field[];
+    submitText?: string;
+}
+
+/**
+ * django-mojo datetimes serialize as EPOCH SECONDS (measured against a live
+ * server, not assumed) — fmt.date/relative accept them directly.
+ */
+export type MojoTimestamp = number | null;
+
+/**
+ * The default-graph user row exactly as /api/user serializes it (verified
+ * live against mverify 2026-08-04). Note what is NOT here: no `role`, no
+ * `created`, no passkey/MFA fields (those ride only the `me` graph).
+ */
+export interface User {
+    id: number;
+    display_name: string | null; // null on real rows (system/deleted accounts)
+    username: string;
+    email: string;
+    phone_number: string | null;
+    first_name?: string;
+    last_name?: string;
+    is_active: boolean;
+    is_superuser: boolean;
+    is_email_verified: boolean;
+    is_phone_verified: boolean;
+    is_dob_verified?: boolean;
+    is_online: boolean;
+    last_login: MojoTimestamp;
+    last_activity: MojoTimestamp;
+    permissions: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    dob?: string | null;
+    /** Capability-free relation shape retained in Query caches. */
+    avatar?: { id: number } | null;
+    org?: { id: number; name: string } | number | null;
+}
+
+/** Strip avatar URLs/thumbnails/capabilities before a User-shaped row enters a cache. */
+export function sanitizeAvatarRelation(value: unknown): { id: number } | null {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) return { id: value };
+    if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+        const id = (value as Record<string, unknown>).id;
+        if (typeof id === 'number' && Number.isSafeInteger(id) && id > 0) return { id };
+    }
+    return null;
+}