@purposeinplay/payload-ai-translate 0.1.0

package/dist/tasks/bulk-translate-doc-task.d.ts

@@ -0,0 +1,142 @@
+import type { Payload, TaskConfig } from 'payload';
+import { createScopedLogger } from '../lib/logger.js';
+import type { BulkTranslateConfig } from '../types.js';
+export declare const BULK_TRANSLATE_DOC_TASK_SLUG = "bulk-translate-doc";
+/**
+ * Worker task that drives a single (collection, doc, locale) unit
+ * from `pending` → `success | failed | skipped`. Strictly serial
+ * within a unit; the coordinator owns fan-out.
+ *
+ * Lifecycle:
+ *   1. Mark unit `running`, increment attempts, stamp startedAt.
+ *   2. F-DA-TOCTOU scenario B skip-check: another batch may have
+ *      a concurrent active unit for the same tuple. If yes, mark
+ *      `skipped` with reason `concurrent_batch` and stop.
+ *   3. Resolve `(collection, documentId)` to a translation call.
+ *      Globals are detected by checking `payload.config?.globals`
+ *      for the slug; everything else is treated as a collection.
+ *   4. On success → mark `success`, capture estimated cost, bump
+ *      batch.completedUnits + batch.actualCostUsd.
+ *   5. On failure → classify error to a `failureCode` per the
+ *      design's class taxonomy, decide retry-or-terminal based on
+ *      attempts count.
+ *   6. If all units terminal, transition the batch.
+ */
+type WorkerTaskInput = {
+    unitId: string;
+};
+type TranslateApiFns = {
+    translateDocument: (payload: Payload, options: {
+        collection: string;
+        id: string | number;
+        targetLocales?: string[];
+        req?: unknown;
+        /**
+         * v1.2.5: when true, the translate path bypasses hash-skip + the
+         * manual-edit preserve guard. The worker passes this when the
+         * parent batch was enqueued with `mode: 'force'` so the UI's
+         * "Force re-translate" checkbox is honoured. See translate.ts +
+         * TranslateDocumentOptions.force.
+         */
+        force?: boolean;
+    }) => Promise<unknown>;
+    translateGlobal: (payload: Payload, options: {
+        global: string;
+        targetLocales?: string[];
+        req?: unknown;
+        /** See translateDocument.force above. */
+        force?: boolean;
+    }) => Promise<unknown>;
+};
+export type FailureCode = 'transient.rate_limited' | 'transient.provider' | 'transient.crashed' | 'permanent.schema' | 'permanent.too_large' | 'permanent.config' | 'permanent.deleted' | 'unknown';
+export interface BulkWorkerOptions {
+    /** Slug override for the units collection. */
+    unitsCollectionSlug?: string;
+    /** Slug override for the batches collection. */
+    batchesCollectionSlug?: string;
+    /**
+     * Maximum number of attempts before a transient failure becomes
+     * permanent (`transient.crashed` final terminal). Default 3.
+     */
+    maxAttempts?: number;
+    /**
+     * Translate API injection point — defaults to the plugin's exported
+     * `translateDocument`/`translateGlobal`. Tests pass mocks instead of
+     * vi.mock-ing the entire `../api` module.
+     */
+    translateApi?: TranslateApiFns;
+    /** Bulk callbacks fired on terminal batch transitions. */
+    callbacks?: Pick<BulkTranslateConfig, 'onBatchComplete' | 'onBatchFailed'>;
+    /**
+     * Decision #11 / N5 — security allowlist. The bulk worker's unit row
+     * has a free-text `collection` field; an attacker with write access
+     * to `bulk-translate-units` could craft a unit with `collection:
+     * 'users'` and the worker would call `translateDocument` with
+     * `overrideAccess: true`, rewriting localized fields on the users
+     * table. Plugin auto-wires this from `options.collections`.
+     *
+     * Empty list disables the check for back-compat with consumers
+     * wiring the worker manually outside the plugin.
+     */
+    allowedCollections?: readonly string[];
+    /** Same security gate as `allowedCollections`, applied to global slugs. */
+    allowedGlobals?: readonly string[];
+}
+export declare function buildBulkTranslateDocTask(options?: BulkWorkerOptions): TaskConfig<{
+    input: WorkerTaskInput;
+    output: {
+        ok: true;
+        status: 'success' | 'failed' | 'skipped' | 'pending';
+    };
+}>;
+export type WorkerRunParams = {
+    payload: Payload;
+    unitId: string;
+    unitsSlug: string;
+    batchesSlug: string;
+    maxAttempts: number;
+    translateApi: TranslateApiFns;
+    callbacks?: Pick<BulkTranslateConfig, 'onBatchComplete' | 'onBatchFailed'>;
+    /**
+     * Security allowlists (Decision #11 / N5). When non-empty, the
+     * worker rejects units whose `collection` / `global` is not in the
+     * list. Empty = back-compat (no enforcement).
+     */
+    allowedCollections?: readonly string[];
+    allowedGlobals?: readonly string[];
+    /** Optional Payload-request override (worker forwards `disableRevalidate`). */
+    req?: unknown;
+    /** Test override for the unit's `startedAt` timestamp. */
+    now?: () => Date;
+};
+export type WorkerRunResult = {
+    status: 'success' | 'failed' | 'skipped' | 'pending';
+    failureCode?: FailureCode;
+    failureMessage?: string;
+    costUsd?: number;
+};
+export declare function runWorkerForUnit(params: WorkerRunParams): Promise<WorkerRunResult>;
+/**
+ * Maps a thrown error to a `failureCode`. Order matters — more
+ * specific patterns win. Defaults to `unknown` for anything we can't
+ * recognise so the row stays visible in the admin drill-down rather
+ * than disappearing into a generic 'failed'.
+ *
+ * Classes per design doc Decision §worker §error-classification:
+ *   - transient.rate_limited: 429 / explicit rate-limit
+ *   - transient.provider:     5xx / fetch timeout
+ *   - permanent.schema:       NoObjectGeneratedError (Vercel AI SDK
+ *                             throws this when the model returns
+ *                             malformed structured output)
+ *   - permanent.too_large:    cost-guard PER_DOC_CEILING/PER_CALL_LIMIT
+ *   - permanent.config:       401 / 403 / auth
+ *   - permanent.deleted:      "Document not found" from findByIdNoFallback
+ *   - unknown:                default
+ */
+export declare function classifyError(err: unknown): FailureCode;
+/**
+ * Check whether every unit in the batch is in a terminal state. If
+ * yes, transition the batch and fire the callback.
+ */
+export declare function maybeTransitionBatch(payload: Payload, batchesSlug: string, unitsSlug: string, batchId: string, callbacks?: Pick<BulkTranslateConfig, 'onBatchComplete' | 'onBatchFailed'>, parentLog?: ReturnType<typeof createScopedLogger>): Promise<void>;
+export {};