portal-mojo 0.1.0

package/src/admin/settings/SettingEditor.tsx

@@ -0,0 +1,157 @@
+import { useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useCan } from '../../client';
+import {
+    CollectionSelect, modal, toast, type CollectionSelectValue,
+} from '../../ui';
+import {
+    SettingModel, saveSettingAtomic, settingGroupLabel,
+    type SettingDraft, type SettingGroup, type SettingRow,
+} from './model';
+
+function initialGroup(row: SettingRow | null): number | null {
+    if (row?.group == null) return null;
+    return typeof row.group === 'number' ? row.group : row.group.id;
+}
+
+function SettingEditor({ row, close }: {
+    row: SettingRow | null;
+    close: (result: SettingRow | null) => void;
+}) {
+    const queryClient = useQueryClient();
+    const { can: canChooseGroup } = useCan('sys.groups');
+    const valueRef = useRef<HTMLTextAreaElement>(null);
+    const valueTouched = useRef(false);
+    const [key, setKey] = useState(row?.key ?? '');
+    const [isSecret, setIsSecret] = useState(row?.is_secret ?? false);
+    const [group, setGroup] = useState<number | null>(initialGroup(row));
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState('');
+
+    const changeSecrecy = (next: boolean) => {
+        setIsSecret(next);
+        valueTouched.current = false;
+        if (valueRef.current) valueRef.current.value = '';
+        setError('');
+    };
+
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault();
+        const draft: SettingDraft = {
+            key,
+            value: valueRef.current?.value ?? '',
+            valueTouched: valueTouched.current,
+            is_secret: isSecret,
+            group,
+        };
+        setBusy(true);
+        setError('');
+        try {
+            const saved = await saveSettingAtomic(row, draft);
+            if (saved) {
+                queryClient.setQueryData(SettingModel.keys.one(saved.id), saved);
+                await queryClient.invalidateQueries({ queryKey: SettingModel.keys.root });
+                toast.success(row ? 'Setting updated' : 'Setting created');
+                close(saved);
+            } else {
+                close(row);
+            }
+        } catch (reason) {
+            setError(reason instanceof Error ? reason.message : 'Setting could not be saved');
+        } finally {
+            setBusy(false);
+        }
+    };
+
+    const valueHelp = row?.is_secret && isSecret
+        ? 'Leave blank to preserve the existing secret. Enter a value only to replace it.'
+        : isSecret
+            ? 'The value becomes write-only after save and will not be returned by the API.'
+            : 'Plain settings may intentionally contain an empty string.';
+
+    return (
+        <form className="modal-pad" onSubmit={submit} noValidate>
+            <h2 className="modal-title">{row ? `Edit setting — ${row.key}` : 'Create setting'}</h2>
+            {error && <div className="form-alert">{error}</div>}
+            <div className="form-grid">
+                <div className="col-12">
+                    <label className="field">
+                        <span className="field-label">Key <em>*</em></span>
+                        <input
+                            className="input"
+                            value={key}
+                            disabled={row != null}
+                            placeholder="WEBHOOK_SECRET"
+                            onChange={(event) => setKey(event.target.value)}
+                        />
+                        <span className="field-help">Keys are immutable after creation.</span>
+                    </label>
+                </div>
+                <div className="col-12">
+                    <label className="switch-row">
+                        <input
+                            type="checkbox"
+                            role="switch"
+                            className="switch"
+                            checked={isSecret}
+                            onChange={(event) => changeSecrecy(event.target.checked)}
+                        />
+                        <span className="field-label">Secret</span>
+                    </label>
+                    {row && row.is_secret !== isSecret && (
+                        <span className="field-help">Changing secret status requires an explicit replacement value.</span>
+                    )}
+                </div>
+                <div className="col-12">
+                    <label className="field">
+                        <span className="field-label">{isSecret ? 'Secret replacement' : 'Value'}</span>
+                        <textarea
+                            ref={valueRef}
+                            className="input"
+                            rows={4}
+                            defaultValue={row && !row.is_secret ? (row.value ?? row.display_value ?? '') : ''}
+                            autoComplete="off"
+                            spellCheck={false}
+                            onChange={() => { valueTouched.current = true; setError(''); }}
+                        />
+                        <span className="field-help">{valueHelp}</span>
+                    </label>
+                </div>
+                <div className="col-12">
+                    {canChooseGroup ? (
+                        <CollectionSelect<SettingGroup>
+                            endpoint="/api/group"
+                            value={group as CollectionSelectValue}
+                            onChange={(id) => setGroup(id == null ? null : Number(id))}
+                            label="Group scope"
+                            placeholder="Search groups…"
+                            help="Clear the selection for a global setting."
+                        />
+                    ) : (
+                        <div className="field">
+                            <span className="field-label">Group scope</span>
+                            <div className="input" aria-readonly="true">
+                                {row ? settingGroupLabel(row.group) : 'Global'}
+                            </div>
+                            <span className="field-help">
+                                Scope changes require the system Groups permission.
+                            </span>
+                        </div>
+                    )}
+                </div>
+            </div>
+            <div className="modal-actions">
+                <button type="button" className="btn" disabled={busy} onClick={() => close(null)}>Cancel</button>
+                <button type="submit" className="btn btn-primary" disabled={busy || !key.trim()}>
+                    {busy ? 'Saving…' : row ? 'Save changes' : 'Create setting'}
+                </button>
+            </div>
+        </form>
+    );
+}
+
+export function showSettingEditor(row: SettingRow | null = null): Promise<SettingRow | null> {
+    return modal.open<SettingRow | null>((close) => (
+        <SettingEditor row={row} close={close} />
+    ), { size: 'md' });
+}

package/src/admin/settings/SettingsPage.tsx

@@ -0,0 +1,72 @@
+import { useQueryClient } from '@tanstack/react-query';
+import {
+    Badge, ModelTable, fmt, modal, type Column, type FilterDef,
+} from '../../ui';
+import {
+    SettingModel, settingGroupLabel, type SettingRow,
+} from './model';
+import { SettingDetail } from './SettingDetail';
+import { showSettingEditor } from './SettingEditor';
+
+const COLUMNS: Column<SettingRow>[] = [
+    {
+        key: 'key', label: 'Key', sortable: true, hideable: false, render: (row) => (
+            <div className="cell-user">
+                <span className="cell-avatar"><i className="bi bi-gear" /></span>
+                <span><span className="cell-name"><code>{row.key}</code></span><span className="cell-sub">#{row.id}</span></span>
+            </div>
+        ),
+    },
+    {
+        key: 'display_value', label: 'Value', render: (row) => (
+            <code>{row.is_secret ? row.display_value || '******' : row.display_value || '—'}</code>
+        ),
+    },
+    { key: 'group', label: 'Scope', render: (row) => settingGroupLabel(row.group) },
+    {
+        key: 'is_secret', label: 'Storage', sortable: true, align: 'center', render: (row) => (
+            <Badge tone={row.is_secret ? 'warning' : 'muted'}>{row.is_secret ? 'Secret' : 'Plain'}</Badge>
+        ),
+    },
+    { key: 'created', label: 'Created', sortable: true, render: (row) => fmt.date(row.created) },
+];
+
+const FILTERS: FilterDef[] = [
+    { key: 'is_secret', label: 'Storage', type: 'boolean', trueLabel: 'Secret', falseLabel: 'Plain' },
+    {
+        key: 'group__isnull', label: 'Scope', type: 'select', options: [
+            { value: 'true', label: 'Global' },
+            { value: 'false', label: 'Group scoped' },
+        ],
+    },
+];
+
+export function SettingsPage() {
+    const queryClient = useQueryClient();
+    const openDetail = (row: SettingRow) => {
+        void SettingModel.fetchOne(queryClient, row.id).catch(() => undefined);
+        void modal.detail((close) => <SettingDetail id={row.id} onClose={() => close(null)} />);
+    };
+    return (
+        <ModelTable<SettingRow>
+            model={SettingModel}
+            eyebrow="Account"
+            title="Settings"
+            searchPlaceholder="Search setting keys…"
+            columns={COLUMNS}
+            filters={FILTERS}
+            presets={[
+                { key: 'all', label: 'All', params: {} },
+                { key: 'global', label: 'Global', params: { group__isnull: 'true' } },
+                { key: 'group', label: 'Group scoped', params: { group__isnull: 'false' } },
+                { key: 'secret', label: 'Secrets', params: { is_secret: 'true' } },
+            ]}
+            defaultSort="key"
+            columnChooser
+            persistState
+            onRowClick={openDetail}
+            addLabel="New Setting"
+            onAdd={() => void showSettingEditor()}
+        />
+    );
+}

package/src/admin/settings/index.ts

@@ -0,0 +1,19 @@
+import { SETTINGS_PERMISSIONS } from './model';
+import { SettingsPage } from './SettingsPage';
+
+export * from './model';
+export * from './SettingEditor';
+export * from './SettingsPage';
+export * from './SettingDetail';
+
+/** Structurally satisfies AdminSection without importing the parent barrel. */
+export const SETTINGS_ADMIN_SECTION = {
+    id: 'settings',
+    title: 'Settings',
+    icon: 'bi-gear',
+    navigationGroup: 'operations' as const,
+    permissions: SETTINGS_PERMISSIONS,
+    routes: [
+        { path: '', component: SettingsPage, permissions: SETTINGS_PERMISSIONS },
+    ],
+};

package/src/admin/settings/model.ts

@@ -0,0 +1,143 @@
+import { defineModel, mojoSave, withFreshAuth, type Params } from '../../client';
+
+/** The exact system-level ANY-of gate declared by Setting.RestMeta. */
+export const SETTINGS_PERMISSIONS = ['sys.manage_settings', 'sys.groups'];
+
+export interface SettingGroup {
+    id: number;
+    name: string;
+    kind?: string;
+}
+
+export interface SettingRow {
+    id: number;
+    created: number;
+    modified: number;
+    key: string;
+    /** Absent for secret rows after the client sanitation boundary. */
+    value?: string;
+    display_value: string;
+    is_secret: boolean;
+    group: SettingGroup | number | null;
+}
+
+function sanitizeSettingRow(row: SettingRow): SettingRow {
+    const safe = { ...row };
+    if (safe.is_secret) delete safe.value;
+    return safe;
+}
+
+function normalizeSettingListParams(params: Params): Params {
+    const safe: Params = {};
+    for (const key of ['start', 'size', 'search', 'is_secret', 'group', 'group__isnull']) {
+        const value = params[key];
+        if (value !== undefined && value !== null && value !== '') safe[key] = value;
+    }
+    if (typeof params.sort === 'string') {
+        const field = params.sort.replace(/^-/, '');
+        if (['key', 'is_secret', 'created', 'modified'].includes(field)) safe.sort = params.sort;
+    }
+    return safe;
+}
+
+export const SettingModel = defineModel<SettingRow>({
+    name: 'setting',
+    endpoint: '/api/settings',
+    permissions: {
+        view: SETTINGS_PERMISSIONS,
+        manage: SETTINGS_PERMISSIONS,
+        create: SETTINGS_PERMISSIONS,
+    },
+    normalizeListParams: normalizeSettingListParams,
+    sanitizeRow: sanitizeSettingRow,
+});
+
+export interface SettingDraft {
+    key: string;
+    value: string;
+    /** True only after the operator edits the replacement-value control. */
+    valueTouched: boolean;
+    is_secret: boolean;
+    group: number | null;
+}
+
+function groupId(group: SettingRow['group']): number | null {
+    if (group == null) return null;
+    return typeof group === 'number' ? group : group.id;
+}
+
+/**
+ * Build one atomic django-mojo save body. Property insertion order is part of
+ * the wire contract: django-mojo applies each field against the model's
+ * current secrecy state. Create keeps is_secret→value. Existing transitions
+ * are directional: Plain→Secret is value→is_secret; Secret→Plain is
+ * is_secret→value. Same-secret replacement needs only value.
+ */
+export function buildSettingPayload(draft: SettingDraft, original: SettingRow | null): Record<string, unknown> | null {
+    const changes: Record<string, unknown> = {};
+    const key = draft.key.trim();
+    if (!key) throw new Error('Key is required');
+
+    if (original == null) {
+        if (draft.is_secret && draft.value === '') throw new Error('Enter a secret value');
+        changes.key = key;
+        changes.group = draft.group;
+        changes.is_secret = draft.is_secret;
+        // Plain settings deliberately support an empty string.
+        changes.value = draft.value;
+        return changes;
+    }
+
+    if (draft.group !== groupId(original.group)) changes.group = draft.group;
+
+    const secrecyChanged = draft.is_secret !== original.is_secret;
+    if (secrecyChanged) {
+        if (!draft.valueTouched) {
+            throw new Error('Enter a replacement value when changing secret status');
+        }
+        if (draft.is_secret && draft.value === '') throw new Error('Enter a secret replacement value');
+        if (draft.is_secret) {
+            // Plain → Secret: stage the plaintext while the row is still
+            // plain, then flip the flag so on_rest_pre_save encrypts it.
+            changes.value = draft.value;
+            changes.is_secret = true;
+        } else {
+            // Secret → Plain: flip first, then write the explicit plain
+            // replacement. Empty is valid in this direction.
+            changes.is_secret = false;
+            changes.value = draft.value;
+        }
+    } else if (original.is_secret) {
+        // Blank means preserve the write-only value. It never becomes a
+        // placeholder payload, even if the input was focused and cleared.
+        if (draft.valueTouched && draft.value !== '') changes.value = draft.value;
+    } else if (draft.valueTouched && draft.value !== (original.value ?? original.display_value ?? '')) {
+        changes.value = draft.value;
+    }
+
+    return Object.keys(changes).length > 0 ? changes : null;
+}
+
+/**
+ * Secret-bearing writes deliberately bypass TanStack MutationCache: mutation
+ * variables retain submitted bodies. Only the sanitized response may leave
+ * this helper and enter Query cache.
+ */
+export async function saveSettingAtomic(
+    original: SettingRow | null,
+    draft: SettingDraft,
+): Promise<SettingRow | null> {
+    const changes = buildSettingPayload(draft, original);
+    if (changes == null) return null;
+    const row = await withFreshAuth(() => mojoSave<SettingRow>(
+        SettingModel.endpoint,
+        original?.id ?? null,
+        changes,
+    ));
+    return sanitizeSettingRow(row);
+}
+
+export function settingGroupLabel(group: SettingRow['group']): string {
+    if (group == null) return 'Global';
+    return typeof group === 'number' ? `Group #${group}` : group.name;
+}

package/src/admin/shortlinks/ShortlinkDetail.tsx

@@ -0,0 +1,55 @@
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { ArmedButton, DetailView, FlatRow, fmt, toast } from '../../ui';
+import {
+    ShortlinkModel, ShortlinkReconciliationError, deleteShortlink, functionalShortlinkUrl,
+    refreshShortlinks, setShortlinkActive, useTrackedCounts,
+} from './models';
+
+export function ShortlinkDetail({ id, onClose }: { id: number; onClose: () => void }) {
+    const queryClient = useQueryClient();
+    const query = ShortlinkModel.useOne(id);
+    const [retryBlocked, setRetryBlocked] = useState(false);
+    const counts = useTrackedCounts(query.data ?? null);
+    if (!query.data) return <div className="modal-pad"><p>{query.isLoading ? 'Loading…' : 'Shortlink unavailable.'}</p><div className="modal-actions"><button className="btn" onClick={onClose}>Close</button></div></div>;
+    const row = query.data;
+    const capability = functionalShortlinkUrl(row.code);
+    const act = async (action: () => Promise<unknown>, success: string): Promise<boolean> => {
+        if (retryBlocked) return false;
+        try { await action(); toast.success(success); await query.refetch(); return true; }
+        catch (error) {
+            if (error instanceof ShortlinkReconciliationError) setRetryBlocked(true);
+            toast.error(error instanceof Error ? error.message : 'Shortlink operation failed');
+            return false;
+        }
+    };
+    const refresh = async () => {
+        try { await refreshShortlinks(queryClient); await query.refetch(); setRetryBlocked(false); toast.success('Authoritative shortlink state refreshed'); }
+        catch { toast.error('Refresh failed. Mutations remain blocked.'); }
+    };
+    return <DetailView title={row.code} subtitle={row.source || 'No source label'} icon="bi-link-45deg"
+        chips={[{ text: row.is_active ? 'Active' : 'Inactive', tone: row.is_active ? 'success' : 'muted' }]}
+        onClose={onClose} sections={[
+            { key: 'overview', label: 'Overview', icon: 'bi-info-circle', render: () => <div className="detail-section">
+                {retryBlocked && <div className="form-alert">The last change may have persisted, but reconciliation failed. Refresh successfully before retrying.</div>}
+                <div className="shortlink-actions"><button className="btn" onClick={() => void navigator.clipboard.writeText(capability)}><i className="bi bi-copy" /> Copy short URL</button><button className="btn" onClick={() => void refresh()}><i className="bi bi-arrow-clockwise" /> Refresh</button></div>
+                <FlatRow label="Short URL"><code>{capability}</code></FlatRow>
+                <FlatRow label="Source">{row.source || '—'}</FlatRow><FlatRow label="Hits">{row.hit_count}</FlatRow>
+                <FlatRow label="Expires">{row.expires_at ? fmt.datetime(row.expires_at) : 'Never'}</FlatRow>
+                <FlatRow label="Tracking">{row.track_clicks ? 'Enabled' : 'Disabled'}</FlatRow>
+                <FlatRow label="Bot passthrough">{row.bot_passthrough ? 'Enabled' : 'Disabled'}</FlatRow>
+                <FlatRow label="Protected">{row.is_protected ? 'Yes' : 'No'}</FlatRow>
+                <FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow>
+            </div> },
+            { key: 'traffic', label: 'Traffic', icon: 'bi-bar-chart', render: () => <div className="detail-section">
+                <h3>Tracked records</h3><p className="dim">Human and bot values count retained tracking records. Total hits may also include requests made while tracking was off.</p>
+                {counts.isLoading ? <p>Loading counts…</p> : counts.isError ? <div className="form-alert">Tracked counts unavailable.</div> : <div className="shortlink-counts"><div><b>{counts.data?.human ?? 0}</b><span>Human records</span></div><div><b>{counts.data?.bot ?? 0}</b><span>Bot records</span></div><div><b>{counts.data?.remainder ?? row.hit_count}</b><span>Hit-count remainder</span></div></div>}
+            </div> },
+            { key: 'controls', label: 'Controls', icon: 'bi-sliders', render: () => <div className="detail-section">
+                <h3>{row.is_active ? 'Deactivate link' : 'Reactivate link'}</h3><p>Changes use a single non-retrying request followed by an authoritative refresh.</p>
+                <button className="btn" disabled={retryBlocked} onClick={() => void act(() => setShortlinkActive(queryClient, row, !row.is_active), row.is_active ? 'Shortlink deactivated' : 'Shortlink reactivated')}>{row.is_active ? 'Deactivate' : 'Reactivate'}</button>
+                <h3>Delete link</h3><p>Deletion is permanent. Click history is removed by the backend cascade.</p>
+                <ArmedButton label="Delete shortlink" armedLabel={`Click again to delete ${row.code}`} disabled={retryBlocked} onConfirm={async () => { if (await act(() => deleteShortlink(queryClient, row), 'Shortlink deleted')) onClose(); }} />
+            </div> },
+        ]} />;
+}

package/src/admin/shortlinks/ShortlinkHistoryPage.tsx

@@ -0,0 +1,18 @@
+import { Badge, ModelTable, fmt, type Column, type FilterDef } from '../../ui';
+import { ShortlinkHistoryModel, type ShortlinkHistoryRow } from './models';
+
+const columns: Column<ShortlinkHistoryRow>[] = [
+    { key: 'created', label: 'Created', sortable: true, hideable: false, render: (row) => fmt.datetime(row.created) },
+    { key: 'shortlink', label: 'Code', render: (row) => row.code ? <code>{row.code}</code> : '—' },
+    { key: 'is_bot', label: 'Audience', sortable: true, render: (row) => <Badge tone={row.is_bot ? 'warning' : 'info'}>{row.is_bot ? 'Bot' : 'Human'}</Badge> },
+    { key: 'agent_summary', label: 'Agent summary' }, { key: 'referer_origin', label: 'Referrer origin', render: (row) => row.referer_origin ?? 'Direct / unknown' },
+];
+const filters: FilterDef[] = [
+    { key: 'shortlink', label: 'Shortlink ID', type: 'number' }, { key: 'is_bot', label: 'Bot', type: 'boolean' },
+    { key: 'created', label: 'Created', type: 'daterange' },
+];
+
+export function ShortlinkHistoryPage() {
+    return <ModelTable model={ShortlinkHistoryModel} eyebrow="Communications · Redirects" title="Tracked click records"
+        columns={columns} filters={filters} searchable={false} defaultSort="-created" columnChooser persistState persistKey="admin:shortlinks:history" />;
+}

package/src/admin/shortlinks/ShortlinksPage.tsx

@@ -0,0 +1,59 @@
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { Badge, ModelTable, fmt, modal, toast, type Column, type FilterDef } from '../../ui';
+import {
+    ShortlinkModel, ShortlinkReconciliationError, createShortlink, functionalShortlinkUrl,
+    refreshShortlinks, type ShortlinkRow,
+} from './models';
+import { ShortlinkDetail } from './ShortlinkDetail';
+
+const columns: Column<ShortlinkRow>[] = [
+    { key: 'code', label: 'Code', sortable: true, hideable: false, render: (row) => <code>{row.code}</code> },
+    { key: 'source', label: 'Source', sortable: true, render: (row) => row.source || '—' },
+    { key: 'is_active', label: 'State', sortable: true, render: (row) => <Badge tone={row.is_active ? 'success' : 'muted'}>{row.is_active ? 'Active' : 'Inactive'}</Badge> },
+    { key: 'hit_count', label: 'Hits', sortable: true, align: 'end' },
+    { key: 'expires_at', label: 'Expires', sortable: true, render: (row) => row.expires_at ? fmt.datetime(row.expires_at) : 'Never' },
+    { key: 'created', label: 'Created', sortable: true, render: (row) => fmt.datetime(row.created) },
+];
+const filters: FilterDef[] = [
+    { key: 'source', label: 'Source', type: 'text' }, { key: 'is_active', label: 'Active', type: 'boolean' },
+    { key: 'created', label: 'Created', type: 'daterange' },
+];
+
+function CreateShortlink({ close, blockRetries }: { close: (value: unknown) => void; blockRetries: () => void }) {
+    const queryClient = useQueryClient();
+    const [url, setUrl] = useState(''); const [source, setSource] = useState(''); const [days, setDays] = useState('3');
+    const [track, setTrack] = useState(false); const [botPassthrough, setBotPassthrough] = useState(false); const [busy, setBusy] = useState(false);
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault(); setBusy(true);
+        try {
+            const row = await createShortlink(queryClient, { url, source, expire_days: Math.max(0, Number(days) || 0), track_clicks: track, bot_passthrough: botPassthrough });
+            toast.success(`Shortlink ${row.code} created`); close(row);
+        } catch (error) {
+            if (error instanceof ShortlinkReconciliationError) blockRetries();
+            toast.error(error instanceof Error ? error.message : 'Shortlink creation failed');
+        } finally { setBusy(false); }
+    };
+    return <form className="modal-pad" onSubmit={(event) => void submit(event)}><h2 className="modal-title">Create shortlink</h2><p className="dim">The destination is sent once to the API and is deliberately omitted from cached Admin rows.</p>
+        <label className="field"><span className="field-label">Destination URL</span><input className="input" type="url" required value={url} onChange={(event) => setUrl(event.target.value)} /></label>
+        <label className="field"><span className="field-label">Source label</span><input className="input" maxLength={50} value={source} onChange={(event) => setSource(event.target.value)} /></label>
+        <label className="field"><span className="field-label">Expire after days</span><input className="input" type="number" min="0" value={days} onChange={(event) => setDays(event.target.value)} /><span className="field-help">0 means no expiry.</span></label>
+        <label className="check-row"><input type="checkbox" checked={track} onChange={(event) => setTrack(event.target.checked)} /> Track click records</label>
+        <label className="check-row"><input type="checkbox" checked={botPassthrough} onChange={(event) => setBotPassthrough(event.target.checked)} /> Allow known preview bots through</label>
+        <div className="modal-actions"><button type="button" className="btn" onClick={() => close(null)}>Cancel</button><button className="btn btn-primary" disabled={busy}>{busy ? 'Creating…' : 'Create'}</button></div>
+    </form>;
+}
+
+export function showShortlinkDetail(id: number): void { void modal.detail((close) => <ShortlinkDetail id={id} onClose={() => close(null)} />); }
+
+export function ShortlinksPage() {
+    const queryClient = useQueryClient(); const [retryBlocked, setRetryBlocked] = useState(false);
+    const refresh = async () => { try { await refreshShortlinks(queryClient); setRetryBlocked(false); toast.success('Shortlinks refreshed'); } catch { toast.error('Refresh failed. Mutations remain blocked.'); } };
+    return <div className="shortlinks-page">{retryBlocked && <div className="form-alert shortlink-page-alert">A change may have persisted without authoritative reconciliation. Creation is blocked until refresh succeeds. <button className="btn btn-compact" onClick={() => void refresh()}>Refresh</button></div>}
+        <ModelTable model={ShortlinkModel} eyebrow="Communications · Redirects" title="Shortlinks" columns={columns} filters={filters}
+            searchable={false} defaultSort="-created" columnChooser persistState persistKey="admin:shortlinks:links"
+            addLabel="Create shortlink" onAdd={retryBlocked ? undefined : () => void modal.open((close) => <CreateShortlink close={close} blockRetries={() => setRetryBlocked(true)} />, { size: 'sm' })}
+            onRowClick={(row) => showShortlinkDetail(row.id)} />
+        <p className="shortlink-origin-note">Displayed short URLs use the configured API origin: <code>{functionalShortlinkUrl('code')}</code>.</p>
+    </div>;
+}

package/src/admin/shortlinks/index.ts

@@ -0,0 +1,18 @@
+import type { AdminSection } from '../index';
+import { ShortlinkHistoryPage } from './ShortlinkHistoryPage';
+import { ShortlinksPage } from './ShortlinksPage';
+import { SHORTLINK_MANAGE_PERMISSIONS } from './models';
+
+export * from './models';
+export * from './ShortlinksPage';
+export * from './ShortlinkHistoryPage';
+export * from './ShortlinkDetail';
+
+export const SHORTLINKS_ADMIN_SECTION: AdminSection = {
+    id: 'shortlinks', basePath: 'shortlinks', title: 'Shortlinks', icon: 'bi-link-45deg', navigationGroup: 'communications',
+    permissions: SHORTLINK_MANAGE_PERMISSIONS,
+    routes: [
+        { path: 'links', label: 'Links', component: ShortlinksPage, permissions: SHORTLINK_MANAGE_PERMISSIONS },
+        { path: 'history', label: 'Click history', component: ShortlinkHistoryPage, permissions: SHORTLINK_MANAGE_PERMISSIONS },
+    ],
+};