@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/error-messages.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Editor-facing error catalogue.
+ *
+ * Single source of truth for every error / soft-skip / alert / endpoint
+ * failure that surfaces to a content editor in the admin UI. Plugin
+ * internals throw / log machine codes; this file maps each code to
+ * plain-English copy keyed by `{ title, body, action?, explanation? }`.
+ *
+ * Why this exists: editors hit the Translation Hub, AlertBanner, doc-view
+ * Translate modal, etc. and used to see raw `err.message` text like
+ * "NoObjectGeneratedError: Response was not valid JSON" or internal codes
+ * like "Code: permanent.config". Engineers can debug those; editors can't.
+ * Every render site now routes through `editorMessageFor(code, ctx)` and
+ * shows the raw text only behind a "Show technical details" disclosure.
+ *
+ * Adding a new code: add the literal to `EditorErrorCode`, register a
+ * formatter in `MESSAGES`, set `isPermanentFailure` if applicable. Tests
+ * in `error-messages.test.ts` enforce that every code has a formatter.
+ */
+/**
+ * Every code an editor can encounter in the UI. Grouped by source:
+ *
+ * - `bulk.*` — `FailureCode` from `tasks/bulk-translate-doc-task.ts`
+ *   classifyError(). Persisted on `bulk_translate_units.failureCode`.
+ * - `soft-skip.*` — Validation outcome from `lib/output-validation.ts`
+ *   when an LLM response is rejected without erroring. Persisted on
+ *   `translation-usage.targetLocales[].softSkippedFields[].reasonCode`.
+ * - `cost-guard.*` — Throws from `lib/cost-guards.ts`. Persisted on
+ *   `translation-alerts.metadata.code` when alert is `cost-guard-abort`.
+ * - `alert.*` — `translation-alerts.alertType`. The collection itself
+ *   already enums these.
+ * - `endpoint.*` — Response.error.code from `endpoints/translation-hub/*`.
+ * - `marker.*` — Special-case `failureMessage` values written by admin
+ *   actions (cancel / force-reset) that aren't real failures.
+ */
+export type EditorErrorCode = 'bulk.transient.rate_limited' | 'bulk.transient.provider' | 'bulk.transient.crashed' | 'bulk.permanent.schema' | 'bulk.permanent.too_large' | 'bulk.permanent.config' | 'bulk.permanent.deleted' | 'bulk.unknown' | 'soft-skip.echoed' | 'soft-skip.too-short' | 'soft-skip.too-long' | 'soft-skip.placeholders' | 'soft-skip.refusal' | 'soft-skip.injection' | 'soft-skip.control-chars' | 'cost-guard.per-call' | 'cost-guard.per-doc' | 'cost-guard.daily-cap' | 'alert.persistent-failure' | 'alert.cost-guard-abort' | 'alert.provider-outage' | 'endpoint.invalid_state' | 'endpoint.not_found' | 'endpoint.totp_invalid' | 'endpoint.totp_missing' | 'endpoint.totp_plugin_unavailable' | 'endpoint.daily_cap_exceeded' | 'endpoint.concurrent_batch' | 'endpoint.not_configured' | 'endpoint.window_expired' | 'endpoint.cost_unavailable' | 'endpoint.invalid_batch_id' | 'endpoint.invalid_json' | 'endpoint.forbidden' | 'endpoint.unauthorized' | 'marker.cancelled-by-admin' | 'marker.force-reset-by-admin' | 'marker.cancelled-mid-flight';
+/**
+ * One editor-facing message. UI components destructure this directly.
+ *
+ * - `title`: short — banner heading / status pill label / toast title
+ *   (3–8 words).
+ * - `body`: 1–2 plain sentences. Names what happened and the impact
+ *   the editor will feel.
+ * - `action`: optional 1-sentence CTA — what the editor can do next.
+ *   Omitted when the action is implicit (e.g. close a modal).
+ * - `explanation`: only for permanent failures. Inline expandable
+ *   "Why won't this work?" text shown when the editor clicks the
+ *   disabled Retry button or a help affordance. Explains WHY this
+ *   class of failure won't fix itself on retry.
+ */
+export type EditorMessage = {
+    title: string;
+    body: string;
+    action?: string;
+    explanation?: string;
+};
+/**
+ * Context used to template messages with concrete values. Every field
+ * optional — formatters that need a value handle missing gracefully
+ * (e.g. fall back to "this document" when collection slug is absent).
+ *
+ * Numeric fields are pre-formatted in `body`/`title` via `formatUsd`
+ * and `formatNumber` helpers so the catalogue itself stays free of
+ * locale-aware formatting concerns.
+ */
+export type EditorErrorContext = {
+    /** Locale code e.g. "fr". Mapped to a friendly label via `localeLabel`. */
+    locale?: string;
+    /** Count of items affected — fields failed, retries used, etc. */
+    count?: number;
+    /** Max attempts attempted (e.g. retry exhaustion). */
+    maxAttempts?: number;
+    /** Current batch status (e.g. "running", "failed"). */
+    status?: string;
+    /** Hours elapsed since a window opened. */
+    hoursElapsed?: number;
+    /** Hours allowed inside the window. */
+    hoursWindow?: number;
+    /** USD spent so far. */
+    spent?: number;
+    /** USD this request would add. */
+    delta?: number;
+    /** USD cap. */
+    cap?: number;
+    /** USD remaining inside the cap. */
+    remaining?: number;
+    /** Character count observed (cost-guard surfaces). */
+    chars?: number;
+    /** Character limit configured (cost-guard surfaces). */
+    limit?: number;
+    /** Length ratio observed (soft-skip too-short/too-long). */
+    ratio?: number;
+    /** Length ratio threshold (min for too-short, max for too-long). */
+    ratioThreshold?: number;
+    /** Placeholder ids missing from the translation (soft-skip placeholders). */
+    missingPlaceholders?: readonly string[];
+    /** Placeholder ids the translation added (soft-skip placeholders). */
+    extraPlaceholders?: readonly string[];
+    /** Collection slug — passed through for log context, not displayed. */
+    collection?: string;
+    /** Document id — passed through for log context, not displayed. */
+    documentId?: string | number;
+    /** Global slug, for global translation paths. */
+    globalSlug?: string;
+};
+/**
+ * Returns the editor-facing message for a given code. When the code is
+ * unknown (e.g. legacy data with a code we no longer ship), returns a
+ * safe fallback rather than rendering `undefined` in the UI.
+ */
+export declare function editorMessageFor(code: EditorErrorCode | string | null | undefined, ctx?: EditorErrorContext): EditorMessage;
+/**
+ * `true` when the code names a failure that won't fix itself on retry
+ * — used to disable the Retry button in the UI and show the inline
+ * "Why won't this work?" explanation. Conservative by design: when
+ * we're not sure, allow retry.
+ */
+export declare function isPermanentFailure(code: EditorErrorCode | string | null | undefined): boolean;
+/**
+ * Adapter from the bulk worker's `FailureCode` (machine enum on the
+ * `bulk_translate_units.failureCode` column) to an `EditorErrorCode`.
+ * Keeps the persistence enum unchanged while letting the UI key off
+ * the catalogue.
+ */
+export declare function editorCodeFromFailureCode(failureCode: string | null | undefined): EditorErrorCode;
+/**
+ * Adapter from the alerts collection's `alertType` enum to an
+ * `EditorErrorCode`. Used by AlertBanner to render the friendly
+ * message via the catalogue.
+ */
+export declare function editorCodeFromAlertType(alertType: string | null | undefined): EditorErrorCode;
+/**
+ * Adapter from the cost-guard throw's `code` property to an
+ * `EditorErrorCode`. Used in API catch blocks that emitAlert.
+ */
+export declare function editorCodeFromCostGuardCode(costGuardCode: string | null | undefined): EditorErrorCode;
+/**
+ * Adapter from a `failureMessage` enum marker (admin action) to an
+ * `EditorErrorCode`. Returns `null` when the message is a real error
+ * (not an admin marker) so callers can fall back to `failureCode`.
+ */
+export declare function editorCodeFromFailureMessageMarker(failureMessage: string | null | undefined): EditorErrorCode | null;
+/**
+ * Coarse failure category used to drive UI tone + grouping. Five buckets:
+ *
+ *  - `config-error` — legit configuration issue. Authentication missing
+ *    or invalid, no model configured, no provider registered. WON'T fix
+ *    itself on retry; editor needs to talk to engineering.
+ *
+ *  - `transient-provider-error` — provider returned something invalid,
+ *    timed out, hit a 5xx, was rate-limited, or returned a non-finite
+ *    cost (broken instrumentation pattern observed in production where
+ *    most units in the same batch succeeded). WILL fix itself on retry.
+ *
+ *  - `cancelled-mid-flight` — the unit was in-flight when the admin
+ *    clicked Cancel. The underlying error may look like anything; the
+ *    relevant context is that the batch is `cancelled` / `cancelling`,
+ *    so reporting it as a config / provider failure misdirects the
+ *    editor.
+ *
+ *  - `output-validation-error` — the model returned content that failed
+ *    schema validation (Vercel AI SDK's `NoObjectGeneratedError`, JSON
+ *    schema rejects). Retry MIGHT help with a different temperature /
+ *    model; engineering may need to relax the schema.
+ *
+ *  - `unknown-error` — fallback bucket. Raw error logged for diagnosis.
+ *    NEVER use as a "we don't care" catch-all — every new error class
+ *    should get its own bucket.
+ */
+export type FailureCategory = 'config-error' | 'transient-provider-error' | 'cancelled-mid-flight' | 'output-validation-error' | 'unknown-error';
+/**
+ * Input to `categorizeFailure`. Caller passes whatever it has from the
+ * persisted unit row plus the parent batch's status (so we can detect
+ * `cancelled-mid-flight` without making the categorizer re-query the
+ * DB). Server-side callers also pass the raw `err` value before the
+ * row is persisted; client-side callers won't have it and pass only
+ * the persisted strings.
+ */
+export type CategorizeFailureInput = {
+    /** Persisted `failureCode` (e.g. `permanent.config`). */
+    failureCode?: string | null;
+    /** Persisted `failureMessage` (raw error text or admin marker). */
+    failureMessage?: string | null;
+    /** Parent batch status — `cancelled` / `cancelling` flips most errors to `cancelled-mid-flight`. */
+    batchStatus?: string | null;
+    /** Worker attempts so far — informational, used by callers that need to show context. */
+    attemptCount?: number;
+    /**
+     * Raw thrown error, when available. Server-side callers (worker
+     * `catch` block) have this; client-side callers don't.
+     */
+    err?: unknown;
+};
+/** Result of `categorizeFailure`. */
+export type CategorizedFailure = {
+    category: FailureCategory;
+    /**
+     * Chip label suitable for status badges (3-4 words, Sentence case).
+     * Derived from category, not from raw error text.
+     */
+    label: string;
+    /**
+     * Editor-facing code keyed into the message catalogue. UI surfaces
+     * pass this to `<EditorError code={…}>` or `editorMessageFor` to
+     * render title + body + action.
+     */
+    editorCode: EditorErrorCode;
+    /**
+     * One-line plain-English message (mirrors the catalogue's `title`).
+     * Pre-computed so callers that render in a constrained space (chip,
+     * table cell) don't need to call `editorMessageFor` themselves.
+     */
+    userMessage: string;
+    /**
+     * Optional raw error text, suitable for an "engineering details"
+     * disclosure. Returned only when the category isn't a marker (admin
+     * cancel / cancel-mid-flight) — those don't have engineer-relevant
+     * detail beyond the marker itself.
+     */
+    details?: string;
+};
+/**
+ * Coarse-grained failure categorizer used by `bulk_translate_units` UI
+ * surfaces (BatchRow expanded row, BucketRow locale detail, Failure
+ * drawer chip). Pure function over the persisted row + parent batch
+ * status. Server-side callers (worker) can also pass the raw thrown
+ * error before persistence.
+ *
+ * Decision order:
+ *  1. Admin markers (failureMessage = 'cancelled_by_admin' /
+ *     'force-reset by admin') short-circuit to the existing marker
+ *     codes — those aren't real failures.
+ *  2. If the parent batch is `cancelled` or `cancelling` AND the unit
+ *     has a real failure (failureCode present, not just the admin
+ *     marker), classify as `cancelled-mid-flight`. The user's mental
+ *     model is "I cancelled, so this stopped" — not "my config is
+ *     broken."
+ *  3. Message-hint patterns override the persisted `failureCode` when
+ *     they clearly point at a different bucket (defends against
+ *     `classifyError` drift in legacy data — e.g. pre-v1.2.6 the
+ *     COST_UNDEFINED case persisted as `permanent.config`).
+ *  4. Map `failureCode` to a category via the static tables.
+ *  5. Fallback: `unknown-error`.
+ */
+export declare function categorizeFailure(input: CategorizeFailureInput): CategorizedFailure;