@asteby/metacore-runtime-react 25.0.0 → 25.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @asteby/metacore-runtime-react
 
+## 25.1.0
+
+### Minor Changes
+
+- a7da67d: feat(errors): los toasts de mutación/acción muestran la causa real del servidor
+
+  Nuevo helper compartido `toastServerError` / `extractServerError` (`server-error.ts`): en vez de tragarse el `details` y mostrar solo el `message` genérico ("Error creating record"), el toast muestra el `message` como título y el `details`/`errors` de validación como descripción. Cableado en `action-modal-dispatcher` (create/edit/acciones declarativas). Cualquier consumidor puede reusarlo. Así un 500 del kernel (p. ej. un error de Postgres o un guard declarativo) llega legible al usuario/operador.
+
 ## 25.0.0
 
 ### Minor Changes

package/dist/action-modal-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-modal-dispatcher.d.ts","sourceRoot":"","sources":["../src/action-modal-dispatcher.tsx"],"names":[],"mappings":"AAwDA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAExB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AA0FhD,wBAAgB,qBAAqB,CAAC,EAClC,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,GACZ,EAAE,gBAAgB,sCA+DlB"}
+{"version":3,"file":"action-modal-dispatcher.d.ts","sourceRoot":"","sources":["../src/action-modal-dispatcher.tsx"],"names":[],"mappings":"AAyDA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAExB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AA0FhD,wBAAgB,qBAAqB,CAAC,EAClC,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,GACZ,EAAE,gBAAgB,sCA+DlB"}

package/dist/action-modal-dispatcher.js

@@ -12,6 +12,7 @@ import { useTranslation } from 'react-i18next';
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, Button, Input, Textarea, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Switch, } from '@asteby/metacore-ui/primitives';
 import { Loader2 } from 'lucide-react';
 import { toast } from 'sonner';
+import { toastServerError, toastServerSuccess } from './server-error';
 import { useApi } from './api-context';
 import { DynamicIcon } from './dynamic-icon';
 import { DynamicLineItems } from './dynamic-line-items';
@@ -263,16 +264,16 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
             const url = buildActionUrl(endpoint, model, record.id, action.key);
             const res = await api.post(url, {});
             if (res.data.success) {
-                toast.success(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.success'));
+                toastServerSuccess(res.data, { t });
                 onOpenChange(false);
                 onSuccess();
             }
             else {
-                toast.error(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.error'));
+                toastServerError({ response: { data: res.data } }, { t });
             }
         }
         catch (err) {
-            toast.error(err?.response?.data?.message || t('common.error'));
+            toastServerError(err, { t });
         }
         finally {
             setExecuting(false);
@@ -360,16 +361,16 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
             const url = buildActionUrl(endpoint, model, record.id, action.key);
             const res = await api.post(url, formData);
             if (res.data.success) {
-                toast.success(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.success'));
+                toastServerSuccess(res.data, { t });
                 onOpenChange(false);
                 onSuccess();
             }
             else {
-                toast.error(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.error'));
+                toastServerError({ response: { data: res.data } }, { t });
             }
         }
         catch (err) {
-            toast.error(err?.response?.data?.message || t('common.error'));
+            toastServerError(err, { t });
         }
         finally {
             setExecuting(false);
@@ -489,16 +490,16 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
             const url = buildActionUrl(endpoint, model, record?.id, action.key);
             const res = await api.post(url, formData);
             if (res.data.success) {
-                toast.success(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.success'));
+                toastServerSuccess(res.data, { t });
                 onOpenChange(false);
                 onSuccess();
             }
             else {
-                toast.error(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.error'));
+                toastServerError({ response: { data: res.data } }, { t });
             }
         }
         catch (err) {
-            toast.error(err?.response?.data?.message || t('common.error'));
+            toastServerError(err, { t });
         }
         finally {
             setExecuting(false);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types';
 export { LicenseGate, LicenseExpiryBanner, LicenseStatusBadge, isLicenseOperable, isLicenseBlocking, isPresetEntitled, isTrialExpired, type LicenseGateProps, type LicenseExpiryBannerProps, type LicenseStatusBadgeProps, type LicenseState, type LicenseStatus, type LicenseBranding, } from './license';
 export * from './options-context';
+export { extractServerError, toastServerError, toastServerSuccess, type ExtractedError, type Translate, } from './server-error';
 export * from './dynamic-table';
 export { DynamicKanban, type DynamicKanbanProps, deriveStages, groupByStage, isTransitionAllowed, applyOptimisticMove, selectCardColumns, UNASSIGNED_LANE, } from './dynamic-kanban';
 export { useStageAutomations, StageAutomationsButton, isTagColumn, automationFieldOptions, groupAutomationsByStage, activeAutomationCount, type StageAutomation, type StageAutomationAction, type StageAutomationActionType, type NewStageAutomation, type UseStageAutomationsResult, type StageAutomationsButtonProps, } from './stage-automations';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -6,6 +6,7 @@
 export * from './types';
 export { LicenseGate, LicenseExpiryBanner, LicenseStatusBadge, isLicenseOperable, isLicenseBlocking, isPresetEntitled, isTrialExpired, } from './license';
 export * from './options-context';
+export { extractServerError, toastServerError, toastServerSuccess, } from './server-error';
 export * from './dynamic-table';
 export { DynamicKanban, deriveStages, groupByStage, isTransitionAllowed, applyOptimisticMove, selectCardColumns, UNASSIGNED_LANE, } from './dynamic-kanban';
 export { useStageAutomations, StageAutomationsButton, isTagColumn, automationFieldOptions, groupAutomationsByStage, activeAutomationCount, } from './stage-automations';

package/dist/server-error.d.ts

@@ -0,0 +1,47 @@
+/** Structured, display-ready view of an error: a headline + an optional cause. */
+export interface ExtractedError {
+    /** Primary line — the server's `message` (may be an i18n key) or a fallback. */
+    title: string;
+    /** Secondary line — the specific cause: `details`, `error`, joined validation
+     *  `errors`, or a raw network/thrown message. Undefined when nothing more
+     *  specific than the title is available. */
+    description?: string;
+}
+/**
+ * Pull the best available headline + cause out of an axios error, a raw
+ * `{ success:false, ... }` response body, or a thrown Error/string. Pure — no
+ * i18n, no toast — so it is unit-testable and reusable (dialogs, inline errors).
+ *
+ * Resolution:
+ *   title       ← data.message (else the specific cause, so the toast is never
+ *                 empty; else `fallbackTitle`)
+ *   description ← data.details → data.error → joined data.errors → raw err.message
+ */
+export declare function extractServerError(err: unknown, fallbackTitle: string): ExtractedError;
+/** i18n translator, tolerant of non-keys (returns `defaultValue`/the input). */
+export type Translate = (key: string, opts?: {
+    defaultValue?: string;
+}) => string;
+/**
+ * Toast a successful mutation/action response, LOCALIZED. The kernel/host often
+ * returns a hardcoded English `message` ("Record created successfully"); echoing
+ * it verbatim leaks English into a Spanish UI. So we only translate the server
+ * message when it is an i18n KEY (dotted, e.g. "pos.rate.created"); a prose
+ * message is dropped in favour of the localized `fallbackKey` (default
+ * "common.success"). Pass the app's `t`.
+ */
+export declare function toastServerSuccess(data: unknown, opts?: {
+    t?: Translate;
+    fallbackKey?: string;
+}): void;
+/**
+ * Toast a server/network error, surfacing the REAL cause as the description
+ * instead of a bare generic line. Pass the app's `t` so an i18n-key `message`
+ * (e.g. "pos.error.no_rate") is localized; a plain-text message passes through
+ * unchanged. Use everywhere a mutation/action can fail.
+ */
+export declare function toastServerError(err: unknown, opts?: {
+    t?: Translate;
+    fallback?: string;
+}): void;
+//# sourceMappingURL=server-error.d.ts.map

package/dist/server-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-error.d.ts","sourceRoot":"","sources":["../src/server-error.ts"],"names":[],"mappings":"AAaA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb;;gDAE4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAuBtF;AAED,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CAAA;AAUjF;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOhG"}

package/dist/server-error.js

@@ -0,0 +1,100 @@
+// Shared server/network error surfacing for declarative mutations & actions.
+//
+// Kernel/host handlers answer a failed write with a consistent envelope:
+//   { success: false, message: "<headline / i18n key>", details: "<real cause>" }
+// where `details` carries what actually went wrong (a Postgres error, a
+// declarative guard failure, a validation reason). The historical toast pattern
+//   toast.error(err?.response?.data?.message || t('common.error'))
+// threw `details` away and showed only the generic headline ("Error creating
+// record") — so a user/operator saw "something failed" with no way to know WHY
+// or report it. This module keeps the headline but ALSO surfaces the cause as
+// the toast description, in ONE place so every call site behaves identically.
+import { toast } from 'sonner';
+/** Flattens a validation `errors` payload (string | string[] | field→msgs map)
+ *  into a single newline-joined string, or undefined when empty. */
+function joinErrors(errors) {
+    if (!errors)
+        return undefined;
+    if (typeof errors === 'string')
+        return errors || undefined;
+    if (Array.isArray(errors))
+        return errors.filter(Boolean).map(String).join('\n') || undefined;
+    if (typeof errors === 'object') {
+        const parts = Object.entries(errors).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : String(v)}`);
+        return parts.join('\n') || undefined;
+    }
+    return undefined;
+}
+/**
+ * Pull the best available headline + cause out of an axios error, a raw
+ * `{ success:false, ... }` response body, or a thrown Error/string. Pure — no
+ * i18n, no toast — so it is unit-testable and reusable (dialogs, inline errors).
+ *
+ * Resolution:
+ *   title       ← data.message (else the specific cause, so the toast is never
+ *                 empty; else `fallbackTitle`)
+ *   description ← data.details → data.error → joined data.errors → raw err.message
+ */
+export function extractServerError(err, fallbackTitle) {
+    // Accept either an axios error (`err.response.data`) or a bare response body
+    // (`{ success, message, details }`) passed straight in.
+    const maybeAxios = err?.response?.data;
+    const data = maybeAxios ?? err;
+    if (data && typeof data === 'object' && ('message' in data || 'details' in data || 'errors' in data || 'error' in data)) {
+        const d = data;
+        const message = typeof d.message === 'string' ? d.message.trim() : '';
+        const details = (typeof d.details === 'string' && d.details.trim()) ||
+            (typeof d.error === 'string' && d.error.trim()) ||
+            joinErrors(d.errors) ||
+            '';
+        if (message && details && message !== details)
+            return { title: message, description: details };
+        if (message || details)
+            return { title: message || details };
+    }
+    // Non-HTTP failure (network down, CORS, a thrown string/Error): show it as
+    // the cause under the generic fallback headline.
+    const raw = typeof err === 'string' ? err : err?.message;
+    if (typeof raw === 'string' && raw.trim())
+        return { title: fallbackTitle, description: raw.trim() };
+    return { title: fallbackTitle };
+}
+/** A dotted, space-free token (e.g. "pos.rate.created") — the shape of an i18n
+ *  key, as opposed to human prose ("Record created successfully"). Used to
+ *  decide whether a server-sent message is safe to translate or should be
+ *  replaced by a localized fallback. */
+function looksLikeI18nKey(s) {
+    return /^[a-z0-9_-]+(\.[a-z0-9_-]+)+$/i.test(s);
+}
+/**
+ * Toast a successful mutation/action response, LOCALIZED. The kernel/host often
+ * returns a hardcoded English `message` ("Record created successfully"); echoing
+ * it verbatim leaks English into a Spanish UI. So we only translate the server
+ * message when it is an i18n KEY (dotted, e.g. "pos.rate.created"); a prose
+ * message is dropped in favour of the localized `fallbackKey` (default
+ * "common.success"). Pass the app's `t`.
+ */
+export function toastServerSuccess(data, opts) {
+    const t = opts?.t;
+    const fallbackKey = opts?.fallbackKey ?? 'common.success';
+    const fallback = t ? t(fallbackKey, { defaultValue: 'Success' }) : 'Success';
+    const msg = data?.message;
+    if (t && typeof msg === 'string' && msg && looksLikeI18nKey(msg)) {
+        toast.success(t(msg, { defaultValue: fallback }));
+        return;
+    }
+    toast.success(fallback);
+}
+/**
+ * Toast a server/network error, surfacing the REAL cause as the description
+ * instead of a bare generic line. Pass the app's `t` so an i18n-key `message`
+ * (e.g. "pos.error.no_rate") is localized; a plain-text message passes through
+ * unchanged. Use everywhere a mutation/action can fail.
+ */
+export function toastServerError(err, opts) {
+    const t = opts?.t;
+    const fallback = opts?.fallback ?? (t ? t('common.error', { defaultValue: 'Something went wrong' }) : 'Something went wrong');
+    const { title, description } = extractServerError(err, fallback);
+    const shownTitle = t ? t(title, { defaultValue: title }) : title;
+    toast.error(shownTitle, description ? { description } : undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "25.0.0",
+  "version": "25.1.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/__tests__/server-error.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { extractServerError } from '../server-error'
+
+describe('extractServerError', () => {
+  it('surfaces details as description under message headline', () => {
+    const err = { response: { data: { success: false, message: 'Error creating record', details: 'ERROR: column "x" does not exist (SQLSTATE 42703)' } } }
+    expect(extractServerError(err, 'fallback')).toEqual({ title: 'Error creating record', description: 'ERROR: column "x" does not exist (SQLSTATE 42703)' })
+  })
+  it('accepts a bare response body', () => {
+    expect(extractServerError({ success: false, message: 'm', details: 'd' }, 'fb')).toEqual({ title: 'm', description: 'd' })
+  })
+  it('uses details as title when no message', () => {
+    expect(extractServerError({ response: { data: { details: 'boom' } } }, 'fb')).toEqual({ title: 'boom' })
+  })
+  it('joins validation errors object', () => {
+    const r = extractServerError({ response: { data: { message: 'Validation error', errors: { name: ['required'], sku: 'dup' } } } }, 'fb')
+    expect(r.title).toBe('Validation error'); expect(r.description).toContain('name: required'); expect(r.description).toContain('sku: dup')
+  })
+  it('falls back for a thrown string / network error', () => {
+    expect(extractServerError('Network Error', 'fb')).toEqual({ title: 'fb', description: 'Network Error' })
+    expect(extractServerError({}, 'fb')).toEqual({ title: 'fb' })
+  })
+  it('does not duplicate when message equals details', () => {
+    expect(extractServerError({ response: { data: { message: 'same', details: 'same' } } }, 'fb')).toEqual({ title: 'same' })
+  })
+})
+
+import { vi } from 'vitest'
+import { toastServerSuccess } from '../server-error'
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }))
+import { toast } from 'sonner'
+describe('toastServerSuccess', () => {
+  const t = (k: string, o?: { defaultValue?: string }) => (k === 'common.success' ? 'Registro creado' : (o?.defaultValue ?? k))
+  it('drops English prose in favour of localized fallback', () => {
+    toastServerSuccess({ message: 'Record created successfully' }, { t })
+    expect((toast.success as any).mock.calls.at(-1)[0]).toBe('Registro creado')
+  })
+  it('translates a dotted i18n key', () => {
+    const t2 = (k: string, o?: { defaultValue?: string }) => (k === 'pos.rate.created' ? 'Tasa creada' : (k === 'common.success' ? 'Registro creado' : (o?.defaultValue ?? k)))
+    toastServerSuccess({ message: 'pos.rate.created' }, { t: t2 })
+    expect((toast.success as any).mock.calls.at(-1)[0]).toBe('Tasa creada')
+  })
+})

package/src/action-modal-dispatcher.tsx

@@ -35,6 +35,7 @@ import {
 } from '@asteby/metacore-ui/primitives'
 import { Loader2 } from 'lucide-react'
 import { toast } from 'sonner'
+import { toastServerError, toastServerSuccess } from './server-error'
 import { useApi } from './api-context'
 import { DynamicIcon } from './dynamic-icon'
 import { DynamicLineItems } from './dynamic-line-items'
@@ -417,14 +418,14 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
             const url = buildActionUrl(endpoint, model, record.id, action.key)
             const res = await api.post(url, {})
             if (res.data.success) {
-                toast.success(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.success'))
+                toastServerSuccess(res.data, { t })
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toast.error(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.error'))
+                toastServerError({ response: { data: res.data } }, { t })
             }
         } catch (err: any) {
-            toast.error(err?.response?.data?.message || t('common.error'))
+            toastServerError(err, { t })
         } finally {
             setExecuting(false)
         }
@@ -539,14 +540,14 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
             const url = buildActionUrl(endpoint, model, record.id, action.key)
             const res = await api.post(url, formData)
             if (res.data.success) {
-                toast.success(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.success'))
+                toastServerSuccess(res.data, { t })
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toast.error(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.error'))
+                toastServerError({ response: { data: res.data } }, { t })
             }
         } catch (err: any) {
-            toast.error(err?.response?.data?.message || t('common.error'))
+            toastServerError(err, { t })
         } finally {
             setExecuting(false)
         }
@@ -744,14 +745,14 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
             const url = buildActionUrl(endpoint, model, record?.id, action.key)
             const res = await api.post(url, formData)
             if (res.data.success) {
-                toast.success(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.success'))
+                toastServerSuccess(res.data, { t })
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toast.error(res.data.message ? t(res.data.message, { defaultValue: res.data.message }) : t('common.error'))
+                toastServerError({ response: { data: res.data } }, { t })
             }
         } catch (err: any) {
-            toast.error(err?.response?.data?.message || t('common.error'))
+            toastServerError(err, { t })
         } finally {
             setExecuting(false)
         }

package/src/index.ts

@@ -20,6 +20,13 @@ export {
     type LicenseBranding,
 } from './license'
 export * from './options-context'
+export {
+    extractServerError,
+    toastServerError,
+    toastServerSuccess,
+    type ExtractedError,
+    type Translate,
+} from './server-error'
 export * from './dynamic-table'
 export {
     DynamicKanban,

package/src/server-error.ts

@@ -0,0 +1,121 @@
+// Shared server/network error surfacing for declarative mutations & actions.
+//
+// Kernel/host handlers answer a failed write with a consistent envelope:
+//   { success: false, message: "<headline / i18n key>", details: "<real cause>" }
+// where `details` carries what actually went wrong (a Postgres error, a
+// declarative guard failure, a validation reason). The historical toast pattern
+//   toast.error(err?.response?.data?.message || t('common.error'))
+// threw `details` away and showed only the generic headline ("Error creating
+// record") — so a user/operator saw "something failed" with no way to know WHY
+// or report it. This module keeps the headline but ALSO surfaces the cause as
+// the toast description, in ONE place so every call site behaves identically.
+import { toast } from 'sonner'
+
+/** Structured, display-ready view of an error: a headline + an optional cause. */
+export interface ExtractedError {
+    /** Primary line — the server's `message` (may be an i18n key) or a fallback. */
+    title: string
+    /** Secondary line — the specific cause: `details`, `error`, joined validation
+     *  `errors`, or a raw network/thrown message. Undefined when nothing more
+     *  specific than the title is available. */
+    description?: string
+}
+
+/** Flattens a validation `errors` payload (string | string[] | field→msgs map)
+ *  into a single newline-joined string, or undefined when empty. */
+function joinErrors(errors: unknown): string | undefined {
+    if (!errors) return undefined
+    if (typeof errors === 'string') return errors || undefined
+    if (Array.isArray(errors)) return errors.filter(Boolean).map(String).join('\n') || undefined
+    if (typeof errors === 'object') {
+        const parts = Object.entries(errors as Record<string, unknown>).map(
+            ([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : String(v)}`,
+        )
+        return parts.join('\n') || undefined
+    }
+    return undefined
+}
+
+/**
+ * Pull the best available headline + cause out of an axios error, a raw
+ * `{ success:false, ... }` response body, or a thrown Error/string. Pure — no
+ * i18n, no toast — so it is unit-testable and reusable (dialogs, inline errors).
+ *
+ * Resolution:
+ *   title       ← data.message (else the specific cause, so the toast is never
+ *                 empty; else `fallbackTitle`)
+ *   description ← data.details → data.error → joined data.errors → raw err.message
+ */
+export function extractServerError(err: unknown, fallbackTitle: string): ExtractedError {
+    // Accept either an axios error (`err.response.data`) or a bare response body
+    // (`{ success, message, details }`) passed straight in.
+    const maybeAxios = (err as { response?: { data?: unknown } } | undefined)?.response?.data
+    const data = maybeAxios ?? err
+
+    if (data && typeof data === 'object' && ('message' in data || 'details' in data || 'errors' in data || 'error' in data)) {
+        const d = data as { message?: unknown; details?: unknown; error?: unknown; errors?: unknown }
+        const message = typeof d.message === 'string' ? d.message.trim() : ''
+        const details =
+            (typeof d.details === 'string' && d.details.trim()) ||
+            (typeof d.error === 'string' && d.error.trim()) ||
+            joinErrors(d.errors) ||
+            ''
+        if (message && details && message !== details) return { title: message, description: details }
+        if (message || details) return { title: message || details }
+    }
+
+    // Non-HTTP failure (network down, CORS, a thrown string/Error): show it as
+    // the cause under the generic fallback headline.
+    const raw = typeof err === 'string' ? err : (err as { message?: unknown } | undefined)?.message
+    if (typeof raw === 'string' && raw.trim()) return { title: fallbackTitle, description: raw.trim() }
+    return { title: fallbackTitle }
+}
+
+/** i18n translator, tolerant of non-keys (returns `defaultValue`/the input). */
+export type Translate = (key: string, opts?: { defaultValue?: string }) => string
+
+/** A dotted, space-free token (e.g. "pos.rate.created") — the shape of an i18n
+ *  key, as opposed to human prose ("Record created successfully"). Used to
+ *  decide whether a server-sent message is safe to translate or should be
+ *  replaced by a localized fallback. */
+function looksLikeI18nKey(s: string): boolean {
+    return /^[a-z0-9_-]+(\.[a-z0-9_-]+)+$/i.test(s)
+}
+
+/**
+ * Toast a successful mutation/action response, LOCALIZED. The kernel/host often
+ * returns a hardcoded English `message` ("Record created successfully"); echoing
+ * it verbatim leaks English into a Spanish UI. So we only translate the server
+ * message when it is an i18n KEY (dotted, e.g. "pos.rate.created"); a prose
+ * message is dropped in favour of the localized `fallbackKey` (default
+ * "common.success"). Pass the app's `t`.
+ */
+export function toastServerSuccess(
+    data: unknown,
+    opts?: { t?: Translate; fallbackKey?: string },
+): void {
+    const t = opts?.t
+    const fallbackKey = opts?.fallbackKey ?? 'common.success'
+    const fallback = t ? t(fallbackKey, { defaultValue: 'Success' }) : 'Success'
+    const msg = (data as { message?: unknown } | undefined)?.message
+    if (t && typeof msg === 'string' && msg && looksLikeI18nKey(msg)) {
+        toast.success(t(msg, { defaultValue: fallback }))
+        return
+    }
+    toast.success(fallback)
+}
+
+/**
+ * Toast a server/network error, surfacing the REAL cause as the description
+ * instead of a bare generic line. Pass the app's `t` so an i18n-key `message`
+ * (e.g. "pos.error.no_rate") is localized; a plain-text message passes through
+ * unchanged. Use everywhere a mutation/action can fail.
+ */
+export function toastServerError(err: unknown, opts?: { t?: Translate; fallback?: string }): void {
+    const t = opts?.t
+    const fallback =
+        opts?.fallback ?? (t ? t('common.error', { defaultValue: 'Something went wrong' }) : 'Something went wrong')
+    const { title, description } = extractServerError(err, fallback)
+    const shownTitle = t ? t(title, { defaultValue: title }) : title
+    toast.error(shownTitle, description ? { description } : undefined)
+}