fix(audit-tier-2): error-surface hygiene — toastError + CodedError sweep

Two mechanical sweeps closing the audit's HIGH §16 + MED §11 findings:

* 38 client components / 56 toast.error sites converted to
  toastError(err) so the new admin error inspector becomes usable from
  user-reported issues — every failed inline-edit, save, send, archive,
  upload, etc. now carries the request-id + error-code (Copy ID action).
* 26 service files / 62 bare-Error throws converted to CodedError or
  the existing AppError subclasses.  Adds new error codes:
  DOCUMENSO_UPSTREAM_ERROR (502), DOCUMENSO_AUTH_FAILURE (502),
  DOCUMENSO_TIMEOUT (504), OCR_UPSTREAM_ERROR (502),
  IMAP_UPSTREAM_ERROR (502), UMAMI_UPSTREAM_ERROR (502),
  UMAMI_NOT_CONFIGURED (409), and INSERT_RETURNING_EMPTY (500) for
  post-insert returning-empty guards.
* Five vitest assertions updated to match the new user-facing wording
  (client-merge "already been merged", expense/interest "couldn't find
  that …", documenso "signing service didn't respond").

Test status: 1168/1168 vitest, tsc clean.

Refs: docs/audit-comprehensive-2026-05-05.md HIGH §16 (auditor-H Issue 1)
+ MED §11 (auditor-G Issue 1).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/admin/brochures-admin-panel.tsx

@@ -29,6 +29,7 @@ import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
 import { Switch } from '@/components/ui/switch';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface BrochureRow {
   id: string;
@@ -123,8 +124,7 @@ function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange:
       toast.success('Default brochure updated');
       onChange();
     },
-    onError: (e) =>
-      toast.error(e instanceof Error ? e.message : 'Could not update default brochure'),
+    onError: (e) => toastError(e),
   });
 
   const archiveMutation = useMutation({
@@ -133,7 +133,7 @@ function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange:
       toast.success('Brochure archived');
       onChange();
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Archive failed'),
+    onError: (e) => toastError(e),
   });
 
   async function handleUpload(file: File) {
@@ -168,7 +168,7 @@ function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange:
       toast.success('New version uploaded');
       onChange();
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Upload failed');
+      toastError(err);
     } finally {
       setUploading(false);
     }
@@ -287,7 +287,7 @@ function CreateBrochureDialog({
       onCreated();
       onOpenChange(false);
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Could not create brochure'),
+    onError: (e) => toastError(e),
   });
 
   return (

src/components/admin/documenso/documenso-test-button.tsx

@@ -6,6 +6,7 @@ import { toast } from 'sonner';
 
 import { Button } from '@/components/ui/button';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface HealthResponse {
   ok: boolean;
@@ -35,7 +36,7 @@ export function DocumensoTestButton() {
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Test failed';
       setResult({ ok: false, error: message });
-      toast.error(message);
+      toastError(err);
     } finally {
       setPending(false);
     }

src/components/admin/duplicates/duplicates-review-queue.tsx

@@ -10,6 +10,7 @@ import { PageHeader } from '@/components/shared/page-header';
 import { EmptyState } from '@/components/shared/empty-state';
 import { Skeleton } from '@/components/ui/skeleton';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { cn } from '@/lib/utils';
 
 interface CandidatePair {
@@ -104,7 +105,7 @@ function CandidateRow({
       queryClient.invalidateQueries({ queryKey: ['admin', 'duplicates'] });
       queryClient.invalidateQueries({ queryKey: ['clients'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Merge failed'),
+    onError: (err) => toastError(err),
     onSettled: () => setBusy(null),
   });
 
@@ -114,7 +115,7 @@ function CandidateRow({
       toast.message('Dismissed');
       queryClient.invalidateQueries({ queryKey: ['admin', 'duplicates'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Dismiss failed'),
+    onError: (err) => toastError(err),
     onSettled: () => setBusy(null),
   });
 

src/components/admin/forms/form-template-form.tsx

@@ -19,6 +19,7 @@ import {
 } from '@/components/ui/select';
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import type { FormField } from '@/lib/validators/form-templates';
 
 interface FormTemplate {
@@ -97,7 +98,7 @@ export function FormTemplateForm({ open, onOpenChange, template, onSaved }: Prop
       onSaved();
       onOpenChange(false);
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Save failed'),
+    onError: (err) => toastError(err),
   });
 
   function updateField(idx: number, patch: Partial<FormField>) {

src/components/admin/forms/form-template-list.tsx

@@ -11,6 +11,7 @@ import { Button } from '@/components/ui/button';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { PageHeader } from '@/components/shared/page-header';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import type { FormField } from '@/lib/validators/form-templates';
 import { FormTemplateForm } from './form-template-form';
 
@@ -41,7 +42,7 @@ export function FormTemplateList() {
       toast.success('Template deleted');
       qc.invalidateQueries({ queryKey: ['admin', 'form-templates'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Delete failed'),
+    onError: (err) => toastError(err),
   });
 
   return (

src/components/admin/invitations/invitations-manager.tsx

@@ -12,6 +12,7 @@ import { Switch } from '@/components/ui/switch';
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Invite {
   id: string;
@@ -56,7 +57,7 @@ export function InvitationsManager() {
       setIsSuperAdmin(false);
       qc.invalidateQueries({ queryKey: ['admin', 'invitations'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to send invite'),
+    onError: (err) => toastError(err),
   });
 
   const resendMutation = useMutation({
@@ -66,7 +67,7 @@ export function InvitationsManager() {
       toast.success('Invite resent');
       qc.invalidateQueries({ queryKey: ['admin', 'invitations'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to resend'),
+    onError: (err) => toastError(err),
   });
 
   const revokeMutation = useMutation({
@@ -75,7 +76,7 @@ export function InvitationsManager() {
       toast.success('Invite revoked');
       qc.invalidateQueries({ queryKey: ['admin', 'invitations'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to revoke'),
+    onError: (err) => toastError(err),
   });
 
   return (

src/components/admin/sales-email-config-card.tsx

@@ -23,6 +23,7 @@ import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface SalesConfigResponse {
   data: {
@@ -160,7 +161,7 @@ export function SalesEmailConfigCard() {
       toast.success('Sales email settings saved');
       await refresh();
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Save failed');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/admin/shared/settings-form-card.tsx

@@ -18,6 +18,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 export type SettingFieldType =
   | 'string'
@@ -116,7 +117,7 @@ export function SettingsFormCard({ title, description, fields, extra }: Settings
       toast.success(`Saved ${changedFields.length} setting(s)`);
       setOriginals(values);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Save failed');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/admin/storage-admin-panel.tsx

@@ -17,6 +17,7 @@ import {
   DialogTitle,
 } from '@/components/ui/dialog';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 type BackendName = 's3' | 'filesystem';
 
@@ -57,8 +58,7 @@ export function StorageAdminPanel() {
       setDryRun(result.data);
       setConfirmOpen(true);
     },
-    onError: (e) =>
-      toast.error(e instanceof Error ? e.message : 'Storage migration dry-run failed'),
+    onError: (e) => toastError(e),
   });
 
   const migrateMutation = useMutation({
@@ -74,7 +74,7 @@ export function StorageAdminPanel() {
       toast.success(`Storage migration complete (${copied} file${copied === 1 ? '' : 's'} copied)`);
       queryClient.invalidateQueries({ queryKey: ['admin', 'storage', 'status'] });
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Storage migration failed'),
+    onError: (e) => toastError(e),
   });
 
   const testMutation = useMutation({

src/components/admin/website-analytics/umami-test-button.tsx

@@ -6,6 +6,7 @@ import { toast } from 'sonner';
 
 import { Button } from '@/components/ui/button';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface TestResponse {
   ok: boolean;
@@ -38,7 +39,7 @@ export function UmamiTestButton() {
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Test failed';
       setResult({ ok: false, error: message });
-      toast.error(message);
+      toastError(err);
     } finally {
       setPending(false);
     }