@purposeinplay/payload-ai-translate 0.1.0

package/dist/bulk-translate-batches-collection.d.ts

@@ -0,0 +1,29 @@
+import type { Access, CollectionConfig } from 'payload';
+export declare const DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG = "bulk-translate-batches";
+/**
+ * Sidecar collection for the bulk-translate feature (plugin v1.2.0+).
+ * One row per bulk run. Persists the trigger context (who, when, scope,
+ * model snapshot), aggregate counts (total / running / completed /
+ * failed / skipped), and lifecycle timestamps (queued, started,
+ * completed, cancelled, reverted) so admins can reconstruct any bulk
+ * operation after the fact.
+ *
+ * `read` access defaults to `admin` role explicitly (Decision #31 in
+ * the bulk-translate design doc) — the `triggeredByEmail`,
+ * `triggerReason`, and `failures` fields can carry sensitive
+ * operational context that editor-role users should not see.
+ *
+ * Status semantics:
+ *   - `queued`     : row exists, coordinator task enqueued but not started
+ *   - `running`    : coordinator is enumerating / fan-out in progress
+ *   - `completed`  : every unit reached `success`
+ *   - `partial`    : terminal — some succeeded, some failed
+ *   - `failed`     : terminal — no successes
+ *   - `cancelled`  : terminal — cancel endpoint hit before completion
+ *   - `reverted`   : terminal — revert endpoint replayed pre-run snapshots
+ *
+ * Model/provider/sourceLocale are snapshotted at enqueue time
+ * (Decision #5) so an admin toggling settings mid-run does not bisect
+ * the batch across configurations.
+ */
+export declare function createBulkTranslateBatchesCollection(readAccess?: Access, slug?: string): CollectionConfig;

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

@@ -0,0 +1,404 @@
+export const DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG = 'bulk-translate-batches';
+/**
+ * Sidecar collection for the bulk-translate feature (plugin v1.2.0+).
+ * One row per bulk run. Persists the trigger context (who, when, scope,
+ * model snapshot), aggregate counts (total / running / completed /
+ * failed / skipped), and lifecycle timestamps (queued, started,
+ * completed, cancelled, reverted) so admins can reconstruct any bulk
+ * operation after the fact.
+ *
+ * `read` access defaults to `admin` role explicitly (Decision #31 in
+ * the bulk-translate design doc) — the `triggeredByEmail`,
+ * `triggerReason`, and `failures` fields can carry sensitive
+ * operational context that editor-role users should not see.
+ *
+ * Status semantics:
+ *   - `queued`     : row exists, coordinator task enqueued but not started
+ *   - `running`    : coordinator is enumerating / fan-out in progress
+ *   - `completed`  : every unit reached `success`
+ *   - `partial`    : terminal — some succeeded, some failed
+ *   - `failed`     : terminal — no successes
+ *   - `cancelled`  : terminal — cancel endpoint hit before completion
+ *   - `reverted`   : terminal — revert endpoint replayed pre-run snapshots
+ *
+ * Model/provider/sourceLocale are snapshotted at enqueue time
+ * (Decision #5) so an admin toggling settings mid-run does not bisect
+ * the batch across configurations.
+ */ export function createBulkTranslateBatchesCollection(readAccess, slug = DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG) {
+    const isAdminDefault = ({ req })=>{
+        const user = req.user;
+        const roles = user?.roles;
+        if (Array.isArray(roles) && roles.includes('admin')) {
+            return true;
+        }
+        return false;
+    };
+    // 1.2.8: read opened to editor+admin so the Translation Hub's Recent
+    // translations table can fetch batches for editors. Cost / model /
+    // token fields are masked at the field level below so editors see
+    // attribution + status but not provider economics. Delete / update
+    // stay admin-only — mutations route through the hub endpoints
+    // (cancel / retry / revert) which layer ownership checks on top.
+    const isEditorOrAdminDefault = ({ req })=>{
+        const user = req.user;
+        const roles = user?.roles;
+        if (!Array.isArray(roles)) {
+            return false;
+        }
+        return roles.includes('admin') || roles.includes('editor');
+    };
+    // Field-level read access for the cost / model surface. Admins see
+    // everything; editors see nothing on these fields. Returning `false`
+    // here strips the field from the API response (Payload contract) —
+    // not just hides it client-side.
+    const fieldAdminOnlyRead = ({ req })=>{
+        // Field access is boolean-only (a `Where` clause cannot scope a field),
+        // so coerce the collection-level Access result to a strict boolean here.
+        // Matches the documented intent: only literal admin access reveals the
+        // field; anything else strips it from the API response.
+        return isAdminDefault({
+            req
+        }) === true;
+    };
+    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 Batch',
+            plural: 'Bulk Translate Batches'
+        },
+        admin: {
+            group: 'Translation',
+            useAsTitle: 'id',
+            defaultColumns: [
+                'id',
+                'status',
+                'mode',
+                'totalUnits',
+                'completedUnits',
+                'failedUnits',
+                'estimatedCostUsd',
+                'actualCostUsd',
+                'startedAt'
+            ],
+            hidden: ({ user })=>{
+                const roles = user?.roles;
+                return !(Array.isArray(roles) && roles.includes('admin'));
+            },
+            description: 'One row per bulk-translation run. Persists scope, snapshotted model/provider, cost estimates, and aggregate progress. Use this to audit who ran a bulk operation, when, and what the outcome was. Per-(doc, locale) detail lives in `Bulk Translate Units`.'
+        },
+        access: {
+            // 1.2.8: defaults to editor+admin so the Hub Recent translations
+            // table populates for editors. Consumers can still override via
+            // `readAccess` if they want a stricter policy.
+            read: readAccess ?? isEditorOrAdminDefault,
+            create: ()=>false,
+            update: ()=>false,
+            delete: isAdminDefault
+        },
+        fields: [
+            {
+                name: 'scope',
+                type: 'json',
+                required: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Scope filter resolved at enqueue: `{ collections, globals, locales, excludeCollections, documentIds }`. Used by retry-failed / revert to re-resolve membership.'
+                }
+            },
+            {
+                name: 'mode',
+                type: 'select',
+                required: true,
+                options: [
+                    {
+                        label: 'Changed (diff-only)',
+                        value: 'changed'
+                    },
+                    {
+                        label: 'Force re-translate',
+                        value: 'force'
+                    },
+                    {
+                        label: 'Canary (limited sample)',
+                        value: 'canary'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'canaryLimit',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    condition: (data)=>data?.mode === 'canary',
+                    description: 'Number of (doc, locale) units the canary fan-out is capped at. Selection is random-stratified across configured collections.'
+                }
+            },
+            // Snapshotted provider/model/source-locale at enqueue time
+            // (Decision #5 + F-DA-MODEL-SWAP). The active OpenRouter model
+            // can change while a batch drains; snapshotting here pins the
+            // batch's behavior to what the admin saw in the pre-flight modal.
+            {
+                name: 'snapshotProviderKey',
+                type: 'text',
+                required: true,
+                admin: {
+                    readOnly: true
+                },
+                // 1.2.8: provider key is operational telemetry — admins only.
+                access: {
+                    read: fieldAdminOnlyRead
+                }
+            },
+            {
+                name: 'snapshotModelId',
+                type: 'text',
+                required: true,
+                admin: {
+                    readOnly: true
+                },
+                // 1.2.8: model is operational telemetry — admins only.
+                access: {
+                    read: fieldAdminOnlyRead
+                }
+            },
+            {
+                name: 'snapshotSourceLocale',
+                type: 'text',
+                required: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'estimatedCostUsd',
+                type: 'number',
+                required: true,
+                admin: {
+                    readOnly: true
+                },
+                // 1.2.8: USD figures hidden from editors — cost is admin-only.
+                access: {
+                    read: fieldAdminOnlyRead
+                }
+            },
+            {
+                name: 'actualCostUsd',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                },
+                access: {
+                    read: fieldAdminOnlyRead
+                }
+            },
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                index: true,
+                defaultValue: 'queued',
+                options: [
+                    {
+                        label: 'Queued',
+                        value: 'queued'
+                    },
+                    {
+                        label: 'Running',
+                        value: 'running'
+                    },
+                    {
+                        label: 'Cancelling',
+                        value: 'cancelling'
+                    },
+                    // Terminal success vocab is `'success'` (matches units
+                    // collection + BulkTranslateBatchStatus type union). Pre-1.2.4
+                    // wrote `'completed'` here; lib/bulk-translate-migrations.ts
+                    // ships an idempotent data migration helper.
+                    {
+                        label: 'Completed',
+                        value: 'success'
+                    },
+                    {
+                        label: 'Partial (some failed)',
+                        value: 'partial'
+                    },
+                    {
+                        label: 'Failed',
+                        value: 'failed'
+                    },
+                    {
+                        label: 'Cancelled',
+                        value: 'cancelled'
+                    },
+                    {
+                        label: 'Reverted',
+                        value: 'reverted'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'totalUnits',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'completedUnits',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'failedUnits',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'skippedUnits',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            // Identity carried as `(userId, email)` rather than a relation so
+            // the audit trail survives user-record deletion. F-BIZ-07.
+            {
+                name: 'triggeredByUserId',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'triggeredByEmail',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'triggerReason',
+                type: 'textarea',
+                admin: {
+                    readOnly: true,
+                    description: 'Optional admin-supplied rationale for the run. Surfaces in audit and helps reconstruct intent post-hoc.'
+                }
+            },
+            {
+                name: 'cancelledByUserId',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'cancelledAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'revertedByUserId',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'revertedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            },
+            // Two distinct timestamps:
+            //   - enqueuedAt: when the batch row was created (always set)
+            //   - startedAt: when the coordinator task first ran (may
+            //     lag the enqueue by up to the cron tick interval; null
+            //     until then). Both readonly in admin; written by the
+            //     enqueue endpoint and coordinator respectively.
+            {
+                name: 'enqueuedAt',
+                type: 'date',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'startedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'completedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            },
+            // Coordinator's enumeration cursor — persists across cron ticks so
+            // a crash mid-enumeration resumes from the last persisted point
+            // rather than re-enqueueing every doc (which would deduplicate
+            // via the partial unique index but waste cron cycles).
+            {
+                name: 'lastEnumerationCursor',
+                type: 'json',
+                admin: {
+                    readOnly: true,
+                    description: 'Internal coordinator state. Pagination cursor for the per-collection enumeration loop.'
+                }
+            },
+            // Soft lease lock: a coordinator updates this at the start of
+            // every tick (and clears it at finishTick when finished=true).
+            // If a second coordinator starts a tick and finds the lock
+            // updated within the lease window, it exits early — prevents
+            // the exponential trampoline fan-out that Round-5 pr-reviewer
+            // flagged when admin retries + queue duplicate-delivery race.
+            {
+                name: 'coordinatorActiveAt',
+                type: 'date',
+                admin: {
+                    readOnly: true,
+                    description: 'Internal lock. Coordinator heartbeat — updated each tick. A second coordinator finding this fresh within the lease window exits to avoid duplicate trampoline fan-out.'
+                }
+            },
+            {
+                name: 'failures',
+                type: 'json',
+                admin: {
+                    readOnly: true,
+                    description: 'Aggregated failure summary: `{ errorClass: count }`. Per-unit detail lives in `Bulk Translate Units`.'
+                }
+            }
+        ]
+    };
+}

package/dist/bulk-translate-units-collection.d.ts

@@ -0,0 +1,35 @@
+import type { Access, CollectionConfig } from 'payload';
+export declare 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 declare function createBulkTranslateUnitsCollection(readAccess?: Access, slug?: string, batchesCollectionSlug?: string): CollectionConfig;