@purposeinplay/payload-ai-translate 0.1.0

package/dist/usage-collection.js

@@ -0,0 +1,377 @@
+import { DEFAULT_USAGE_COLLECTION_SLUG } from './defaults.js';
+/**
+ * Factory for the auto-registered `translation-usage` collection.
+ *
+ * The plugin pushes this collection onto `config.collections` when
+ * `usageTracking.enabled` is true. Every translation job — succeeded or
+ * failed — writes one row from inside `lib/persist-usage.ts`. Cost data
+ * is treated as admin-only by default: `admin.hidden` keeps the entry
+ * out of the editor nav, and `access.read` blocks API reads even via
+ * direct URL.
+ *
+ * Mirrors the audit-log plugin's `createAuditLogsCollection` pattern.
+ */ export function createUsageCollection(readAccess, collectionSlug) {
+    const slug = collectionSlug ?? DEFAULT_USAGE_COLLECTION_SLUG;
+    const defaultAdminRead = ({ req })=>req?.user?.roles?.includes('admin') ?? 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: 'Translation Usage',
+            plural: 'Translation Usage'
+        },
+        admin: {
+            useAsTitle: 'jobId',
+            group: 'System',
+            // Hide from non-admins entirely so editors don't see cost data in the
+            // nav. The collection is also blocked at the API layer via access.read.
+            hidden: ({ user })=>!user?.roles?.includes('admin'),
+            description: 'One row per translation job (collection or global). Populated automatically by the plugin after each translate run — succeeded, failed, or partial. Empty until the first translate fires; rows are read-only and never created from the UI.',
+            defaultColumns: [
+                'createdAt',
+                'kind',
+                'slug',
+                'documentId',
+                'status',
+                'estimatedCostUsd',
+                'model'
+            ]
+        },
+        access: {
+            read: readAccess ?? defaultAdminRead,
+            create: ()=>false,
+            update: ()=>false,
+            delete: ()=>false
+        },
+        graphQL: false,
+        timestamps: true,
+        fields: [
+            {
+                name: 'kind',
+                type: 'select',
+                required: true,
+                index: true,
+                options: [
+                    {
+                        label: 'Collection',
+                        value: 'collection'
+                    },
+                    {
+                        label: 'Global',
+                        value: 'global'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'jobId',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'slug',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Collection slug or global slug.'
+                }
+            },
+            {
+                name: 'documentId',
+                type: 'text',
+                index: true,
+                admin: {
+                    readOnly: true,
+                    description: 'For globals this equals the slug.'
+                }
+            },
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                index: true,
+                options: [
+                    {
+                        label: 'Succeeded',
+                        value: 'succeeded'
+                    },
+                    {
+                        label: 'Failed',
+                        value: 'failed'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'sourceLocale',
+                type: 'text',
+                required: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'targetLocales',
+                type: 'array',
+                admin: {
+                    readOnly: true,
+                    description: 'One row per target locale. `status` and `error` capture which locales failed and why; the top-level `error` field is now just an aggregate count.'
+                },
+                fields: [
+                    {
+                        name: 'locale',
+                        type: 'text',
+                        required: true
+                    },
+                    {
+                        name: 'status',
+                        type: 'select',
+                        options: [
+                            {
+                                label: 'Succeeded',
+                                value: 'succeeded'
+                            },
+                            {
+                                label: 'Failed',
+                                value: 'failed'
+                            }
+                        ],
+                        admin: {
+                            readOnly: true
+                        }
+                    },
+                    {
+                        name: 'error',
+                        type: 'text',
+                        admin: {
+                            readOnly: true,
+                            description: 'Verbatim provider error message for the first failed field in this locale. Empty when locale succeeded.'
+                        }
+                    },
+                    {
+                        name: 'errorCode',
+                        type: 'text',
+                        admin: {
+                            readOnly: true,
+                            description: 'Editor-facing code (1.2.5+) that the Translation Hub uses to render a friendly message. Empty on legacy rows; UI falls back to a generic message.'
+                        }
+                    },
+                    {
+                        name: 'failedFields',
+                        type: 'array',
+                        admin: {
+                            readOnly: true
+                        },
+                        fields: [
+                            {
+                                name: 'path',
+                                type: 'text',
+                                required: true
+                            }
+                        ]
+                    }
+                ]
+            },
+            {
+                name: 'succeededCount',
+                type: 'number',
+                required: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Total field × locale results marked success. Includes hash-skipped fields. Use fieldsTranslated / fieldsHashSkipped for the breakdown.'
+                }
+            },
+            {
+                name: 'failedCount',
+                type: 'number',
+                required: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Counts field × locale results, not distinct locales.'
+                }
+            },
+            {
+                // Field-locale entries that actually hit the LLM. Excludes
+                // hash-skipped entries (source unchanged since last translate).
+                // `succeededCount = fieldsTranslated + fieldsHashSkipped`.
+                name: 'fieldsTranslated',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    description: 'Field × locale entries that actually called the LLM this run.'
+                }
+            },
+            {
+                // Field-locale entries where the source content hash matched the
+                // last-translated source hash → no LLM call (cost-saving skip).
+                // Detected via `characterCount === 0 && durationMs === 0` in
+                // FieldLocaleResult coming back from translate-for-locale.
+                name: 'fieldsHashSkipped',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    description: 'Field × locale entries skipped because the source content was unchanged since the last translation — no LLM call.'
+                }
+            },
+            {
+                // Field-locale entries the manual-edit guard kept out of the
+                // write because the target locale value diverged from the
+                // plugin\'s lastWrittenHash (assumed manual edit).
+                name: 'fieldsPreserved',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    description: 'Field × locale entries preserved because the target locale value was manually edited since the last plugin write.'
+                }
+            },
+            {
+                // Field-locale entries where the LLM echoed source verbatim or
+                // returned output that failed validation. The source value is
+                // kept; the field is not written.
+                name: 'fieldsSoftSkipped',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    description: 'Field × locale entries soft-skipped (LLM echoed source or returned invalid output).'
+                }
+            },
+            {
+                // Detail rows for soft-skipped fields. Useful for editors to
+                // know WHY a field stayed in source rather than seeing a single
+                // aggregate number.
+                name: 'softSkippedFields',
+                type: 'array',
+                admin: {
+                    readOnly: true
+                },
+                fields: [
+                    {
+                        name: 'path',
+                        type: 'text',
+                        required: true
+                    },
+                    {
+                        name: 'locale',
+                        type: 'text',
+                        required: true
+                    },
+                    {
+                        name: 'reason',
+                        type: 'text'
+                    },
+                    {
+                        name: 'reasonCode',
+                        type: 'text',
+                        admin: {
+                            readOnly: true,
+                            description: 'Editor-facing code (1.2.5+) that the Translation Hub uses to render a friendly message for this soft-skipped field. Empty on legacy rows.'
+                        }
+                    },
+                    {
+                        // The actual source-locale text the AI declined to translate.
+                        // Lets editors see WHAT was kept (e.g. "Wheel Of", "VIP") without
+                        // opening the doc — they can usually decide "yes that's a brand,
+                        // leave it" or "no, that needed translation" from the value alone.
+                        // Empty on legacy rows persisted before 1.2.8.
+                        name: 'sourceValue',
+                        type: 'text',
+                        admin: {
+                            readOnly: true,
+                            description: "Source-locale value the AI kept as-is. Surfaced in the Hub so editors don't need to open the doc to decide whether the skip was correct."
+                        }
+                    }
+                ]
+            },
+            {
+                // Detail rows for fields the manual-edit guard preserved. Lets
+                // editors see WHICH fields are being protected (without this,
+                // they only see a count and can't audit whether the right fields
+                // are guarded). No `reason` — the reason is always "target
+                // value diverges from plugin's lastWrittenHash."
+                name: 'preservedFields',
+                type: 'array',
+                admin: {
+                    readOnly: true
+                },
+                fields: [
+                    {
+                        name: 'path',
+                        type: 'text',
+                        required: true
+                    },
+                    {
+                        name: 'locale',
+                        type: 'text',
+                        required: true
+                    }
+                ]
+            },
+            {
+                name: 'inputTokens',
+                type: 'number',
+                required: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'outputTokens',
+                type: 'number',
+                required: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'estimatedCostUsd',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    components: {
+                        // Sub-dollar costs (gpt-4o-mini, claude-haiku) round to 0 with the
+                        // default Number cell. Format as a small-precision currency so a
+                        // 10c translation doesn't read as "$0".
+                        Cell: '@purposeinplay/payload-ai-translate/client#EstimatedCostCell'
+                    }
+                }
+            },
+            {
+                name: 'model',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'durationMs',
+                type: 'number',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'error',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            }
+        ]
+    };
+}

package/dist/views/BulkRunsHub/BatchRow.d.ts

@@ -0,0 +1,32 @@
+import type React from 'react';
+import type { BulkTranslateBatchSummary } from '../TranslationHub/BulkTranslate.types.js';
+/**
+ * Renders the batch progress cell as either an empty-state label or a
+ * "X / Y" fraction. Extracted as a pure helper so BR-4 ("0 / 0" shown
+ * for empty batches reads ambiguous) can be pinned with a unit test
+ * — see `__tests__/BatchRow.helpers.test.ts`.
+ *
+ *   - totalUnits === 0 → `{ kind: 'empty' }` and the cell renders the
+ *     italic "No units enqueued" copy (typically a cancelled-before-
+ *     start run or an empty-scope selection).
+ *   - totalUnits > 0   → `{ kind: 'fraction', completed, total }`.
+ */
+export type BatchProgressDescriptor = {
+    kind: 'empty';
+} | {
+    kind: 'fraction';
+    completed: number;
+    total: number;
+    percent: number;
+};
+export declare function describeBatchProgress(completedUnits: number, totalUnits: number): BatchProgressDescriptor;
+interface BatchRowProps {
+    basePath: string;
+    batch: BulkTranslateBatchSummary;
+    isExpanded: boolean;
+    onToggle: () => void;
+    onAfterAction: () => void;
+    colCount: number;
+}
+export declare const BatchRow: React.FC<BatchRowProps>;
+export {};