@purposeinplay/payload-ai-translate 0.1.0

package/dist/bulk-translate-units-collection.js

@@ -0,0 +1,310 @@
+export const DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG = 'bulk-translate-units';
+/**
+ * Per-(collection, documentId, locale) work item for a bulk translate
+ * batch. Plugin v1.2.0+.
+ *
+ * Source of truth for unit-level state in a bulk run. Read by:
+ *   1. The `shouldSkipDocument`-equivalent check at task-entry and the
+ *      per-doc retry endpoint (Decision #19 v2): "is there already a
+ *      pending/running unit for this (collection, doc, locale) in some
+ *      other in-flight batch?". A partial unique index on
+ *      `(collection, document_id, locale) WHERE status IN
+ *      ('pending','running')` enforces the invariant in Postgres
+ *      regardless of application-layer races (F-DA-TOCTOU).
+ *   2. The revert action: paginates over `success` units, reads
+ *      `preRunSnapshot` + `schemaHash`, restores the pre-run value.
+ *   3. The Hub monitor UI's drill-down view of failed units.
+ *
+ * `preRunSnapshot` is jsonb and stores ONLY the localized translatable
+ * fields, captured via Payload `select` (Decision #30 + F-SEC-SNAPSHOT).
+ * Never the full document — that would leak `password` / `email` /
+ * `roles` and other `excludeFields` content into a queryable
+ * collection.
+ *
+ * Read access is locked to `admin` role only (Decision #31, unchanged
+ * in 1.2.8). The snapshot column contains pre-translation source
+ * content which, even scoped to translatable fields, may include
+ * unpublished drafts editor-role users should not see. Editors who
+ * need unit-level drill-down (e.g., per-locale outcomes, failure
+ * reasons) read through the shaped `/api/translation-hub/bulk-translate/:id`
+ * (`status` endpoint, 1.2.8 opened to editor+admin) and `/failures`
+ * endpoints — those serialize a redacted view that excludes
+ * `preRunSnapshot` entirely.
+ */ export function createBulkTranslateUnitsCollection(readAccess, slug = DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG, batchesCollectionSlug = 'bulk-translate-batches') {
+    const isAdminDefault = ({ req })=>{
+        const user = req.user;
+        const roles = user?.roles;
+        if (Array.isArray(roles) && roles.includes('admin')) return true;
+        return false;
+    };
+    return {
+        slug,
+        // System rows are never edited in the admin document view, so
+        // Payload's document-locking buys nothing here — and its lock check
+        // costs a second pool connection inside every update transaction
+        // (core's checkDocumentLockStatus runs a find without `req`). Under
+        // concurrent updates (e.g. dismiss-all on alerts) that exhausted the
+        // pool and deadlocked a consumer in prod on 2026-06-10.
+        lockDocuments: false,
+        labels: {
+            singular: 'Bulk Translate Unit',
+            plural: 'Bulk Translate Units'
+        },
+        admin: {
+            group: 'Translation',
+            useAsTitle: 'id',
+            defaultColumns: [
+                'batchId',
+                'collection',
+                'documentId',
+                'locale',
+                'status',
+                'attempts',
+                'failureCode',
+                'completedAt'
+            ],
+            hidden: ({ user })=>{
+                const roles = user?.roles;
+                return !Array.isArray(roles) || !roles.includes('admin');
+            },
+            description: 'Per-(doc, locale) work item for a bulk-translate batch. One row per translation unit. Status transitions: pending → running → success | failed | skipped. Reverted units track replay of pre-run snapshots.'
+        },
+        access: {
+            read: readAccess ?? isAdminDefault,
+            create: ()=>false,
+            update: ()=>false,
+            delete: isAdminDefault
+        },
+        fields: [
+            {
+                name: 'batchId',
+                type: 'relationship',
+                relationTo: batchesCollectionSlug,
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'collection',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'documentId',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'locale',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                index: true,
+                defaultValue: 'pending',
+                options: [
+                    {
+                        label: 'Pending (queued)',
+                        value: 'pending'
+                    },
+                    {
+                        label: 'Running',
+                        value: 'running'
+                    },
+                    {
+                        label: 'Success',
+                        value: 'success'
+                    },
+                    {
+                        label: 'Failed',
+                        value: 'failed'
+                    },
+                    {
+                        label: 'Skipped (no change)',
+                        value: 'skipped'
+                    },
+                    {
+                        label: 'Reverted',
+                        value: 'reverted'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'attempts',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            // Classifies the failure for retry policy + UI drill-down. The
+            // worker maps known errors to these classes; unknown errors fall
+            // back to `unknown`. Permanent classes never auto-retry.
+            {
+                name: 'failureCode',
+                type: 'select',
+                options: [
+                    {
+                        label: 'Transient — rate-limited',
+                        value: 'transient.rate_limited'
+                    },
+                    {
+                        label: 'Transient — provider 5xx',
+                        value: 'transient.provider'
+                    },
+                    {
+                        label: 'Transient — crashed (janitor)',
+                        value: 'transient.crashed'
+                    },
+                    {
+                        label: 'Permanent — schema invalid',
+                        value: 'permanent.schema'
+                    },
+                    {
+                        label: 'Permanent — too large',
+                        value: 'permanent.too_large'
+                    },
+                    {
+                        label: 'Permanent — auth/config',
+                        value: 'permanent.config'
+                    },
+                    {
+                        label: 'Permanent — doc deleted',
+                        value: 'permanent.deleted'
+                    },
+                    {
+                        label: 'Unknown',
+                        value: 'unknown'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'failureMessage',
+                type: 'textarea',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'preRunSnapshot',
+                type: 'json',
+                admin: {
+                    readOnly: true,
+                    description: 'TARGET-locale values of ONLY the localized translatable fields, captured by the worker just before its first write for this unit (v1.2.12+). Used by revert. Never the full doc — see F-SEC-SNAPSHOT. Rows written before v1.2.12 hold SOURCE-locale values (captured at enqueue) and are refused by revert — replaying them stamped source-language content over translated locales.'
+                }
+            },
+            {
+                // v1.2.12: which locale's values `preRunSnapshot` holds. Revert
+                // requires snapshotLocale === locale; legacy rows (null) are
+                // refused — their snapshots were captured from the SOURCE-locale
+                // enumeration read and replaying them destroys translations.
+                name: 'snapshotLocale',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            // Hash of the localized translatable fields' schema at snapshot
+            // time. Revert refuses if schema-hash differs at restore time
+            // unless the admin sets `force: true` (Decision #34 +
+            // F-DA-REVERT-SCHEMA). Prevents silent data drift when a field
+            // is renamed or removed between snapshot and revert.
+            {
+                name: 'schemaHash',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'costUsd',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'startedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true,
+                    description: 'When the worker handler entered for this unit. Includes any pending-queue wait the unit served before being picked up.'
+                }
+            },
+            {
+                name: 'completedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true,
+                    description: 'When the worker handler finished (success or terminal failure).'
+                }
+            },
+            {
+                // Real translation-call duration in milliseconds. Captured around
+                // the `translateApi.translateDocument(...)` call inside the worker —
+                // excludes token-bucket wait, provider rate-limit backoff, and
+                // queue scheduling. This is what the editor cares about: "how long
+                // did the AI actually spend on this." `completedAt - startedAt`
+                // includes throttle wait and is reported separately as
+                // wallclock-in-worker for engineering.
+                name: 'processingDurationMs',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    description: 'Time the AI translation call itself took, in milliseconds. Excludes throttle / rate-limit wait — that gets folded into the difference between startedAt and completedAt instead.'
+                }
+            }
+        ],
+        indexes: [
+            // Composite index for the shouldSkipDocument-equivalent lookup at
+            // task entry + retry endpoint. The application-layer query is:
+            //   findFirst WHERE collection=? AND documentId=? AND status IN
+            //   ('pending','running')
+            // A partial unique index on the same predicate is added via raw
+            // SQL migration (F-DA-PARTIAL-IDX) — Payload's index generator
+            // doesn't emit partial uniqueness today.
+            //
+            // TODO(migration): hand-write the partial unique index as part
+            // of the v1.2.0 migrations bundle. Exact SQL:
+            //
+            //   CREATE UNIQUE INDEX bulk_translate_units_active_dedup
+            //     ON bulk_translate_units (collection, document_id, locale)
+            //     WHERE status IN ('pending','running');
+            //
+            // Note the three-column uniqueness — `(collection, doc, locale)`,
+            // not `(collection, doc)`. Allows different locales for the same
+            // doc to run concurrently while serializing per-locale writes.
+            {
+                fields: [
+                    'collection',
+                    'documentId',
+                    'status'
+                ]
+            }
+        ]
+    };
+}

package/dist/client/estimated-cost-cell.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+type EstimatedCostCellProps = {
+    cellData?: number | null;
+};
+export declare function EstimatedCostCell({ cellData }: EstimatedCostCellProps): React.JSX.Element;
+export {};

package/dist/client/estimated-cost-cell.js

@@ -0,0 +1,12 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { formatCost } from '../views/shared/format.js';
+export function EstimatedCostCell({ cellData }) {
+    if (cellData === null || cellData === undefined) return /*#__PURE__*/ _jsx("span", {
+        children: "—"
+    });
+    return /*#__PURE__*/ _jsx("span", {
+        children: formatCost(cellData)
+    });
+}

package/dist/client/excluded-fields-field.d.ts

@@ -0,0 +1,45 @@
+import type React from 'react';
+type Props = {
+    /**
+     * Field path Payload assigns at render time, e.g.
+     * `perCollection.0.excludedFieldPaths`. We strip the trailing
+     * segment to address the sibling `slug` field of the same row.
+     */
+    path: string;
+};
+/**
+ * Custom admin component for `perCollection[i].excludedFieldPaths`.
+ *
+ * Stores an exclude-list (top-level field paths the admin opted OUT of
+ * translation). Rendered as a grouped list — one checkbox per
+ * top-level field on the surface. Unchecking a top-level field
+ * excludes EVERY descendant path under it (prefix-match in
+ * `isPathExcluded`).
+ *
+ * Design rationale:
+ *
+ * 1. **Editor mental model.** Editors think in terms of the fields
+ *    they see in the doc editor ("Layout", "Meta"), not internal dot-
+ *    paths. The earlier flat list of paths like
+ *    `layout.columns.link.label` was technically correct but useless
+ *    for non-developers.
+ * 2. **One checkbox per top-level field.** Coarse but predictable:
+ *    "uncheck Layout" → nothing under `layout.*` is translated.
+ *    Per-leaf exclusions are still expressible via direct DB writes
+ *    or future per-field controls if needed; the common case is
+ *    coverage at the section level.
+ * 3. **Disclosure of details.** A collapsible "Show 14 sub-paths"
+ *    affordance reveals every descendant path the resolver found, so
+ *    a developer / careful editor can verify what's actually
+ *    affected. Read-only — not interactive.
+ * 4. **Exclude-list semantics.** Default = empty array = translate
+ *    everything. New localized fields added later start "checked"
+ *    automatically.
+ *
+ * Sibling slug derivation: Payload doesn't give the component direct
+ * access to its row neighbours, so we strip the trailing
+ * `.excludedFieldPaths` segment from `path` and append `.slug` to
+ * address the sibling.
+ */
+export declare function ExcludedFieldsField({ path }: Props): React.JSX.Element;
+export {};