@purposeinplay/payload-ai-translate 0.1.0

package/dist/views/TranslationHub/BulkTranslate.types.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Shared types for the bulk-translate UI surfaces.
+ *
+ * These mirror the response shapes documented in
+ * `Plan-2026-05-27-bulk-translate.md` for the
+ * `/api/translation-hub/bulk-translate*` endpoints. The endpoints are
+ * implemented in parallel; until they land each consumer should treat a
+ * 404 as "no active batch" / "preflight unavailable".
+ */
+/**
+ * Terminal vs non-terminal status helpers — kept as exported constants
+ * so the UI logic can be tested in isolation without re-deriving the
+ * lifecycle anywhere.
+ */
+export declare const BULK_TRANSLATE_TERMINAL_STATUSES: readonly ["success", "failed", "partial", "reverted", "cancelled"];
+export declare const BULK_TRANSLATE_ACTIVE_STATUSES: readonly ["queued", "running", "cancelling"];
+export type BulkTranslateBatchStatus = (typeof BULK_TRANSLATE_ACTIVE_STATUSES)[number] | (typeof BULK_TRANSLATE_TERMINAL_STATUSES)[number];
+export declare function isTerminalStatus(s: BulkTranslateBatchStatus | undefined | null): boolean;
+export declare function isActiveStatus(s: BulkTranslateBatchStatus | undefined | null): boolean;
+/** Per-collection progress row used by the in-flight monitor. */
+export interface BulkTranslateCollectionProgress {
+    slug: string;
+    label: string;
+    total: number;
+    completed: number;
+    failed: number;
+}
+/** Response of GET /api/translation-hub/bulk-translate/active. */
+export interface BulkTranslateActiveResponse {
+    /** Null when no active or recently-terminal batch exists. */
+    batch: BulkTranslateBatchSummary | null;
+}
+export interface BulkTranslateBatchSummary {
+    id: string;
+    status: BulkTranslateBatchStatus;
+    mode: 'changed' | 'force' | 'canary';
+    totalUnits: number;
+    completedUnits: number;
+    failedUnits: number;
+    estimatedCostUsd?: number;
+    actualCostUsd?: number;
+    createdAt: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    /** P50 ETA in seconds — backend computes from running batch metrics. */
+    etaSeconds?: number | null;
+    collections: BulkTranslateCollectionProgress[];
+    /** Set on the batch row 24h after completion to gate the Revert action. */
+    revertExpiresAt?: string | null;
+    revertedAt?: string | null;
+    triggeredByEmail?: string | null;
+    /** 1.2.8: stringified user id — drives the editor ownership chip. */
+    triggeredByUserId?: string | null;
+}
+/** Response of GET /api/translation-hub/bulk-translate/preflight. */
+export interface BulkTranslatePreflightResponse {
+    scope: {
+        collections: string[];
+        globals: string[];
+        locales: string[];
+        sourceLocale: string;
+    };
+    documents: {
+        /** Total documents that WOULD be enqueued (after diff-skip if mode=changed). */
+        total: number;
+        /** Per-collection breakdown (label + counts). */
+        perCollection: Array<{
+            slug: string;
+            label: string;
+            changed: number;
+            total: number;
+        }>;
+    };
+    /**
+     * Best-effort cost estimate. May be `undefined` during the cold-cache
+     * window — UI shows skeleton + 10s retry CTA in that state.
+     */
+    estimatedCostUsd?: number;
+    /** USD cap state at the moment preflight ran. */
+    dailySpend: {
+        spentUsd: number;
+        capUsd: number;
+        /** ISO string of next reset (midnight UTC). */
+        resetsAt: string;
+    };
+    /** Whether the consumer's plugin config has `bulk.requireTotp: true`. */
+    requireTotp: boolean;
+    /** Whether the requesting user has TOTP enrolled (for fallback UX). */
+    totpEnrolled: boolean;
+}
+/** Response of GET /api/translation-hub/bulk-translate/:id/failures. */
+export interface BulkTranslateFailureRow {
+    unitId: string;
+    collection: string;
+    documentId: string;
+    documentTitle?: string | null;
+    locale: string;
+    failureCode?: string | null;
+    failureMessage: string;
+    attempts: number;
+}
+/** Response of GET /api/translation-hub/bulk-translate (list endpoint). */
+export interface BulkTranslateListResponse {
+    batches: BulkTranslateBatchSummary[];
+    nextCursor: string | null;
+    total: number;
+}
+/** Per-unit row returned by GET /api/translation-hub/bulk-translate/:id/status */
+export interface BatchJobSummary {
+    unitId: string;
+    collection: string;
+    documentId: string;
+    locale: string;
+    /** Unit-level status — distinct from batch-level status. */
+    status: 'pending' | 'running' | 'success' | 'failed' | 'skipped' | 'reverted';
+    attempts: number;
+    failureCode: string | null;
+    failureMessage: string | null;
+    costUsd: number;
+    startedAt: string | null;
+    completedAt: string | null;
+    /**
+     * AI call time in milliseconds — excludes throttle wait. UI renders
+     * this as the per-unit "Duration" column. `null` on legacy rows.
+     */
+    processingDurationMs: number | null;
+}
+/** Unit-level count breakdown in the status drill-down response. */
+export interface BatchUnitCounts {
+    total: number;
+    pending: number;
+    running: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    reverted: number;
+}
+/**
+ * Per-collection aggregate counts. Keyed by collection / global slug.
+ * Driven by the tree-grouped DrillDown — bucket headers render from
+ * these totals, not from the paginated `jobs` page (which would only
+ * reflect "how many of the loaded units are in this bucket").
+ */
+export interface BatchUnitCountsByCollection {
+    [collection: string]: {
+        isGlobal: boolean;
+        total: number;
+        pending: number;
+        running: number;
+        succeeded: number;
+        failed: number;
+        skipped: number;
+        reverted: number;
+        /**
+         * v1.2.7: filter-aware doc counts per bucket. Keyed by the UI filter
+         * chip name (`all`, `pending`, `running`, `completed`, `failed`,
+         * `skipped`, `reverted`). Each value is the number of DISTINCT
+         * documents in this bucket that have at least one unit in the
+         * matching state. A doc with one failed + one succeeded locale shows
+         * in BOTH `failed` and `completed`. `all === totalDocs`. Drives the
+         * bucket-header count when an active filter pill is set.
+         */
+        docCountsByStatus: {
+            all: number;
+            pending: number;
+            running: number;
+            completed: number;
+            failed: number;
+            skipped: number;
+            reverted: number;
+        };
+        /** Distinct documentIds in this bucket (count of unique docs). */
+        totalDocs: number;
+        /**
+         * Wall-clock from this bucket's first unit start to its last unit
+         * completion (editor-perceived "time we spent translating this
+         * collection"). Null when the bucket has no completed units yet.
+         */
+        collectionSpanMs: number | null;
+        /**
+         * Sum of `processingDurationMs` across this bucket — pure AI
+         * compute time. Null when no v1.2.5+ units have populated the
+         * column yet.
+         */
+        aiActiveMs: number | null;
+        /**
+         * `collectionSpanMs − aiActiveMs`, clamped ≥0. Surfaced as a
+         * paired "AI active / Queue wait" sub-line on the bucket header
+         * per UX recommendation — distinguishes "the AI was slow" from
+         * "we were rate-limited." Null when either source is null.
+         */
+        queueWaitMs: number | null;
+        distinctFailureCodes: number;
+        topFailureCodes: Array<{
+            code: string;
+            count: number;
+        }>;
+    };
+}
+/** Response of GET /api/translation-hub/bulk-translate/:id/status */
+export interface BulkTranslateStatusResponse {
+    data: {
+        batchId: string;
+        status: string;
+        mode: string;
+        canaryLimit: number | null;
+        estimatedCostUsd: number | null;
+        actualCostUsd: number;
+        counts: BatchUnitCounts;
+        /** 1.3.0+: per-collection totals. Empty object on old responses. */
+        countsByCollection?: BatchUnitCountsByCollection;
+        jobs: BatchJobSummary[];
+        nextCursor: string | null;
+        snapshot: {
+            providerKey: string | null;
+            modelId: string | null;
+            sourceLocale: string | null;
+        };
+        timestamps: {
+            enqueuedAt: string | null;
+            startedAt: string | null;
+            completedAt: string | null;
+            cancelledAt: string | null;
+            revertedAt: string | null;
+        };
+        triggeredByUserId: string | null;
+        triggeredByEmail: string | null;
+        failures: Record<string, unknown> | null;
+    };
+}
+/** Filter state managed by the FilterBar. */
+export interface BulkRunsFilterState {
+    /** Comma-separated status values or aliases (active/terminal). */
+    status: string;
+    mode: string;
+    triggeredBy: string;
+    since: string;
+    until: string;
+    hasFailures: boolean;
+}
+/** Time-range choice for the SummaryStrip. */
+export type BulkRunsTimeRange = '7d' | '30d' | 'all';

package/dist/views/TranslationHub/BulkTranslate.types.js

@@ -0,0 +1,36 @@
+/**
+ * Shared types for the bulk-translate UI surfaces.
+ *
+ * These mirror the response shapes documented in
+ * `Plan-2026-05-27-bulk-translate.md` for the
+ * `/api/translation-hub/bulk-translate*` endpoints. The endpoints are
+ * implemented in parallel; until they land each consumer should treat a
+ * 404 as "no active batch" / "preflight unavailable".
+ */ /**
+ * Terminal vs non-terminal status helpers — kept as exported constants
+ * so the UI logic can be tested in isolation without re-deriving the
+ * lifecycle anywhere.
+ */ export const BULK_TRANSLATE_TERMINAL_STATUSES = [
+    'success',
+    'failed',
+    'partial',
+    'reverted',
+    'cancelled'
+];
+export const BULK_TRANSLATE_ACTIVE_STATUSES = [
+    'queued',
+    'running',
+    'cancelling'
+];
+export function isTerminalStatus(s) {
+    if (!s) {
+        return false;
+    }
+    return BULK_TRANSLATE_TERMINAL_STATUSES.includes(s);
+}
+export function isActiveStatus(s) {
+    if (!s) {
+        return false;
+    }
+    return BULK_TRANSLATE_ACTIVE_STATUSES.includes(s);
+}

package/dist/views/TranslationHub/BulkTranslateFailureDrawer.d.ts

@@ -0,0 +1,19 @@
+import type React from 'react';
+import type { BulkTranslateCollectionProgress } from './BulkTranslate.types.js';
+interface Props {
+    basePath: string;
+    batchId: string;
+    /**
+     * Parent batch status. Threaded into `categorizeFailure` so a row
+     * that failed while the batch was being cancelled (NEW-12) gets the
+     * `cancelled-mid-flight` copy instead of the generic config-error
+     * misclassification.
+     */
+    batchStatus: string;
+    collection: BulkTranslateCollectionProgress;
+    onClose: () => void;
+}
+/** Truncate an error message for the row display. Exported for tests. */
+export declare function truncateError(msg: string, maxLen?: number): string;
+export declare const BulkTranslateFailureDrawer: React.FC<Props>;
+export {};

package/dist/views/TranslationHub/BulkTranslateFailureDrawer.js

@@ -0,0 +1,332 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { categorizeFailure } from '../../lib/error-messages.js';
+import { docHref } from '../shared/docHref.js';
+import { EditorErrorChip } from '../shared/EditorError.js';
+import { readResponseError } from '../shared/fetch-error-body.js';
+import { useFocusTrap } from './useFocusTrap.js';
+const OVERLAY_STYLE = {
+    position: 'fixed',
+    top: 0,
+    right: 0,
+    bottom: 0,
+    width: '100%',
+    maxWidth: '480px',
+    background: 'var(--theme-elevation-0)',
+    borderLeft: '1px solid var(--theme-elevation-150)',
+    boxShadow: '-10px 0 30px rgba(0,0,0,0.15)',
+    zIndex: 200,
+    display: 'flex',
+    flexDirection: 'column'
+};
+const HEADER_STYLE = {
+    padding: '1rem 1.5rem',
+    borderBottom: '1px solid var(--theme-elevation-150)',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between'
+};
+const ROW_STYLE = {
+    display: 'grid',
+    gridTemplateColumns: '1fr 60px 40px',
+    gap: '0.75rem',
+    padding: '0.6rem 1.5rem',
+    borderBottom: '1px solid var(--theme-elevation-100)',
+    alignItems: 'start',
+    fontSize: '0.8125rem'
+};
+/** Truncate an error message for the row display. Exported for tests. */ export function truncateError(msg, maxLen = 80) {
+    if (msg.length <= maxLen) {
+        return msg;
+    }
+    return `${msg.slice(0, maxLen - 1)}…`;
+}
+export const BulkTranslateFailureDrawer = ({ basePath, batchId, batchStatus, collection, onClose })=>{
+    const drawerRef = useRef(null);
+    const [rows, setRows] = useState(null);
+    const [error, setError] = useState(null);
+    const [retryingAll, setRetryingAll] = useState(false);
+    const [retryingUnit, setRetryingUnit] = useState(null);
+    useFocusTrap(drawerRef, {
+        enabled: true,
+        onEscape: onClose
+    });
+    useEffect(()=>{
+        let cancelled = false;
+        (async ()=>{
+            try {
+                const params = new URLSearchParams({
+                    collection: collection.slug
+                });
+                const res = await fetch(`${basePath}/api/translation-hub/bulk-translate/${batchId}/failures?${params}`, {
+                    credentials: 'include'
+                });
+                if (cancelled) {
+                    return;
+                }
+                if (!res.ok) {
+                    throw new Error(await readResponseError(res));
+                }
+                const json = await res.json();
+                setRows(json.rows ?? []);
+            } catch (e) {
+                if (!cancelled) {
+                    setError(e instanceof Error ? e.message : String(e));
+                }
+            }
+        })();
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        basePath,
+        batchId,
+        collection.slug
+    ]);
+    async function onRetryUnit(unitId) {
+        setRetryingUnit(unitId);
+        try {
+            const res = await fetch(`${basePath}/api/translation-hub/bulk-translate/${batchId}/retry`, {
+                method: 'POST',
+                credentials: 'include',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    unitIds: [
+                        unitId
+                    ]
+                })
+            });
+            if (!res.ok) {
+                throw new Error(await readResponseError(res));
+            }
+            // Optimistic remove — server will re-add via poll if it lands in
+            // failed again.
+            setRows((prev)=>(prev ?? []).filter((r)=>r.unitId !== unitId));
+        } catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        } finally{
+            setRetryingUnit(null);
+        }
+    }
+    async function onRetryAll() {
+        setRetryingAll(true);
+        setError(null);
+        try {
+            const res = await fetch(`${basePath}/api/translation-hub/bulk-translate/${batchId}/retry`, {
+                method: 'POST',
+                credentials: 'include',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    collection: collection.slug
+                })
+            });
+            if (!res.ok) {
+                throw new Error(await readResponseError(res));
+            }
+            setRows([]);
+        } catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        } finally{
+            setRetryingAll(false);
+        }
+    }
+    return /*#__PURE__*/ _jsxs("div", {
+        "aria-label": `Failed translations for ${collection.label}`,
+        "data-testid": "bulk-translate-failure-drawer",
+        ref: drawerRef,
+        role: "dialog",
+        style: OVERLAY_STYLE,
+        children: [
+            /*#__PURE__*/ _jsxs("header", {
+                style: HEADER_STYLE,
+                children: [
+                    /*#__PURE__*/ _jsxs("div", {
+                        children: [
+                            /*#__PURE__*/ _jsxs("h3", {
+                                style: {
+                                    margin: 0,
+                                    fontSize: '1rem',
+                                    color: 'var(--theme-elevation-1000)'
+                                },
+                                children: [
+                                    collection.label,
+                                    " — failed translations"
+                                ]
+                            }),
+                            /*#__PURE__*/ _jsxs("p", {
+                                style: {
+                                    margin: '0.15rem 0 0',
+                                    fontSize: '0.75rem',
+                                    color: 'var(--theme-elevation-500)'
+                                },
+                                children: [
+                                    collection.failed,
+                                    " failed · ",
+                                    collection.total,
+                                    " total"
+                                ]
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("button", {
+                        "aria-label": "Close failure drawer",
+                        onClick: onClose,
+                        style: {
+                            background: 'transparent',
+                            border: 'none',
+                            color: 'var(--theme-elevation-700)',
+                            cursor: 'pointer',
+                            fontSize: '1.25rem',
+                            lineHeight: 1
+                        },
+                        type: "button",
+                        children: "×"
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsx("div", {
+                style: {
+                    padding: '0.75rem 1.5rem',
+                    borderBottom: '1px solid var(--theme-elevation-150)'
+                },
+                children: /*#__PURE__*/ _jsx("button", {
+                    "data-testid": "bulk-translate-retry-all",
+                    disabled: retryingAll || rows !== null && rows.length === 0,
+                    onClick: onRetryAll,
+                    style: {
+                        background: 'transparent',
+                        border: 'none',
+                        color: 'var(--theme-success-500, #16a34a)',
+                        textDecoration: 'underline',
+                        cursor: retryingAll || rows !== null && rows.length === 0 ? 'not-allowed' : 'pointer',
+                        fontSize: '0.8125rem',
+                        padding: 0
+                    },
+                    type: "button",
+                    children: retryingAll ? 'Retrying…' : `Retry all failed in ${collection.label}`
+                })
+            }),
+            error ? /*#__PURE__*/ _jsx("p", {
+                style: {
+                    margin: '0.75rem 1.5rem',
+                    color: 'var(--theme-error-500, #b91c1c)',
+                    fontSize: '0.8125rem'
+                },
+                children: error
+            }) : null,
+            /*#__PURE__*/ _jsx("div", {
+                style: {
+                    flex: 1,
+                    overflowY: 'auto'
+                },
+                children: rows === null ? /*#__PURE__*/ _jsx("p", {
+                    style: {
+                        padding: '1rem 1.5rem',
+                        color: 'var(--theme-elevation-500)',
+                        fontSize: '0.8125rem',
+                        margin: 0
+                    },
+                    children: "Loading failures…"
+                }) : rows.length === 0 ? /*#__PURE__*/ _jsx("p", {
+                    style: {
+                        padding: '1rem 1.5rem',
+                        color: 'var(--theme-elevation-500)',
+                        fontSize: '0.8125rem',
+                        margin: 0
+                    },
+                    children: "No failures."
+                }) : rows.map((row)=>{
+                    const rowDocHref = docHref(basePath, collection.slug, row.documentId, row.locale);
+                    return /*#__PURE__*/ _jsxs("div", {
+                        style: ROW_STYLE,
+                        children: [
+                            /*#__PURE__*/ _jsxs("div", {
+                                children: [
+                                    /*#__PURE__*/ _jsx("div", {
+                                        style: {
+                                            color: 'var(--theme-elevation-1000)'
+                                        },
+                                        children: /*#__PURE__*/ _jsx("a", {
+                                            href: rowDocHref,
+                                            rel: "noopener noreferrer",
+                                            style: {
+                                                color: 'var(--theme-success-500, #16a34a)',
+                                                textDecoration: 'none'
+                                            },
+                                            target: "_blank",
+                                            title: `Open ${row.documentTitle ?? row.documentId} in ${row.locale}`,
+                                            children: row.documentTitle ?? row.documentId
+                                        })
+                                    }),
+                                    /*#__PURE__*/ _jsx("div", {
+                                        style: {
+                                            color: 'var(--theme-elevation-500)',
+                                            fontSize: '0.75rem',
+                                            marginTop: '0.15rem'
+                                        },
+                                        title: row.failureMessage,
+                                        children: /*#__PURE__*/ _jsx(EditorErrorChip, {
+                                            code: // NEW-12 (v1.2.6): unified path through
+                                            // `categorizeFailure` so the chip respects the
+                                            // parent batch's cancel state — a row that hit
+                                            // a real error while the batch was being
+                                            // cancelled renders as "Stopped mid-run", not
+                                            // "Translation system is not set up".
+                                            categorizeFailure({
+                                                failureCode: row.failureCode,
+                                                failureMessage: row.failureMessage,
+                                                batchStatus,
+                                                attemptCount: row.attempts
+                                            }).editorCode,
+                                            context: {
+                                                locale: row.locale
+                                            },
+                                            title: row.failureMessage
+                                        })
+                                    })
+                                ]
+                            }),
+                            /*#__PURE__*/ _jsx("span", {
+                                style: {
+                                    display: 'inline-block',
+                                    padding: '0.15rem 0.4rem',
+                                    background: 'var(--theme-elevation-100)',
+                                    borderRadius: '4px',
+                                    fontSize: '0.7rem',
+                                    color: 'var(--theme-elevation-700)',
+                                    alignSelf: 'start',
+                                    fontFamily: 'monospace'
+                                },
+                                children: row.locale
+                            }),
+                            /*#__PURE__*/ _jsx("button", {
+                                "aria-label": `Retry ${row.documentTitle ?? row.documentId} ${row.locale}`,
+                                "data-testid": `bulk-translate-retry-${row.unitId}`,
+                                disabled: retryingUnit === row.unitId,
+                                onClick: ()=>onRetryUnit(row.unitId),
+                                style: {
+                                    background: 'transparent',
+                                    border: '1px solid var(--theme-elevation-300)',
+                                    borderRadius: '4px',
+                                    color: 'var(--theme-elevation-700)',
+                                    cursor: retryingUnit === row.unitId ? 'not-allowed' : 'pointer',
+                                    padding: '0.2rem 0.4rem',
+                                    fontSize: '0.75rem',
+                                    alignSelf: 'start'
+                                },
+                                type: "button",
+                                title: "Retry",
+                                children: "↺"
+                            })
+                        ]
+                    }, row.unitId);
+                })
+            })
+        ]
+    });
+};

package/dist/views/TranslationHub/BulkTranslateMonitor.d.ts

@@ -0,0 +1,28 @@
+import type React from 'react';
+import type { BulkTranslateBatchSummary } from './BulkTranslate.types.js';
+/**
+ * In-flight monitor surface. Driven by the parent's poll loop — the
+ * parent (`Hub.client.tsx`) owns the `useBulkTranslateActive` hook
+ * and passes the latest `batch` snapshot down. This keeps the
+ * trigger and the monitor on the SAME data source (matters for
+ * multi-admin sync, F-UX-05).
+ */
+interface Props {
+    basePath: string;
+    batch: BulkTranslateBatchSummary;
+    /** True after 3 consecutive failed polls. Surface offline banner. */
+    isOffline: boolean;
+    /** Refetch trigger for the offline-banner "retry now" button. */
+    onRetry: () => void;
+}
+/**
+ * Format an ETA seconds value to "~Nm" / "~Nh Mm". Exported for tests.
+ */
+export declare function formatEta(seconds: number | null | undefined): string;
+/**
+ * Cancellation interim copy (F-UX-04). Returns null when batch isn't
+ * cancelling so the UI can early-return.
+ */
+export declare function deriveCancellationLabel(batch: Pick<BulkTranslateBatchSummary, 'status' | 'totalUnits' | 'completedUnits' | 'failedUnits'>): string | null;
+export declare const BulkTranslateMonitor: React.FC<Props>;
+export {};