@purposeinplay/payload-ai-translate 0.1.0

package/dist/endpoints/translation-hub/retry-failed.js

@@ -0,0 +1,235 @@
+import { DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG } from '../../bulk-translate-batches-collection.js';
+import { DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG } from '../../bulk-translate-units-collection.js';
+import { checkAndIncrementDailySpend } from '../../lib/daily-spend-cap.js';
+import { createScopedLogger } from '../../lib/logger.js';
+import { BULK_TRANSLATE_DOC_TASK_SLUG } from '../../tasks/bulk-translate-coordinator.js';
+import { errorResponse, forbiddenOwnershipResponse, getAiTranslateConfig, isEditorOrAdmin, ownsBatch, readJsonBody, unauthorizedResponse } from './_helpers.js';
+import { extractBatchId } from './status.js';
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+const TERMINAL_STATUSES_FOR_RETRY = new Set([
+    'success',
+    'partial',
+    'failed'
+]);
+/**
+ * `POST /api/translation-hub/bulk-translate/:id/retry-failed`
+ *
+ * Re-enqueues all `failed` units for the batch back to `pending`.
+ * Refuses when the batch is non-terminal — there's no semantic way
+ * to "retry failed" while units are still running.
+ *
+ * Daily-cap is re-checked (F-SEC-TOTP-BYPASS — the cap applies to all
+ * translate paths, not just first-enqueue).
+ */ export const getBulkTranslateRetryFailedHandler = (options = {})=>async (req)=>{
+        const batchesSlug = options.batchesCollectionSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+        const unitsSlug = options.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+        const workerSlug = options.workerTaskSlug ?? BULK_TRANSLATE_DOC_TASK_SLUG;
+        if (!req.user) {
+            return unauthorizedResponse(req);
+        }
+        if (!isEditorOrAdmin(req.user)) {
+            return errorResponse('forbidden', "You don't have permission to retry failed units. Contact an admin.", 403);
+        }
+        const config = getAiTranslateConfig(req.payload);
+        const bulkConfig = config?.bulk ?? {
+            enabled: false
+        };
+        const batchId = extractBatchId(req.url ?? '');
+        if (!batchId) {
+            return errorResponse('invalid_batch_id', 'Batch ID could not be parsed from the request URL.', 400);
+        }
+        const parsed = await readJsonBody(req);
+        if (!parsed.ok) return parsed.res;
+        const collectionFilter = typeof parsed.body.collection === 'string' && parsed.body.collection.length > 0 ? parsed.body.collection : null;
+        const documentIdFilter = typeof parsed.body.documentId === 'string' && parsed.body.documentId.length > 0 ? parsed.body.documentId : null;
+        const skipErrorCodes = Array.isArray(parsed.body.skipErrorCodes) ? new Set(parsed.body.skipErrorCodes.filter((s)=>typeof s === 'string')) : new Set();
+        let batch;
+        try {
+            batch = await req.payload.findByID({
+                collection: batchesSlug,
+                id: batchId,
+                overrideAccess: true,
+                depth: 0
+            });
+        } catch (err) {
+            const log = createScopedLogger(req.payload, {
+                component: 'hub.retry-failed',
+                batchId
+            });
+            log.event('warn', 'hub.retry-failed.batch-read.failed', {
+                err,
+                endpoint: 'hub.retry-failed',
+                batchId
+            });
+            batch = undefined;
+        }
+        if (!batch) {
+            return errorResponse('not_found', 'This translation run no longer exists. Refresh the page.', 404);
+        }
+        // 1.2.8: editor can only retry a run they triggered. Admins pass.
+        // See ownership-leak rationale in cancel.ts.
+        if (!ownsBatch(req.user, batch)) {
+            return forbiddenOwnershipResponse();
+        }
+        if (!TERMINAL_STATUSES_FOR_RETRY.has(batch.status)) {
+            return errorResponse('invalid_state', 'The run is still in progress. Wait for it to finish before retrying failed documents.', 409, {
+                status: batch.status
+            });
+        }
+        // ----- Fetch failed units, apply skip + collection + doc filters -----
+        const failedUnits = await loadAllFailedUnits(req.payload, unitsSlug, batchId);
+        const skipped = [];
+        const toRetry = [];
+        for (const u of failedUnits){
+            // Per-bucket retry: when the caller pinned a collection, exclude
+            // failed units in other collections / globals from this retry.
+            if (collectionFilter && u.collection !== collectionFilter) {
+                continue;
+            }
+            // Per-doc retry: when the caller pinned a documentId, exclude
+            // failed units for other docs in the same collection.
+            if (documentIdFilter && u.documentId !== documentIdFilter) {
+                continue;
+            }
+            if (u.failureCode && skipErrorCodes.has(u.failureCode)) {
+                skipped.push(String(u.id));
+                continue;
+            }
+            toRetry.push(u);
+        }
+        if (toRetry.length === 0) {
+            return Response.json({
+                data: {
+                    batchId,
+                    retriedJobs: 0,
+                    skippedJobs: skipped.length
+                }
+            });
+        }
+        // ----- Daily cap re-check -----
+        // Sum the per-unit cost estimate. Units carry `costUsd` populated
+        // on the previous attempt (0 for ones that failed before billing
+        // — those re-run for free per cap arithmetic). When NO unit has
+        // a known cost we still call the cap helper with 0; that keeps the
+        // accounting honest without forcing a fresh batch-level estimate
+        // (Decision #29 doesn't apply to retries — we already have observed
+        // history).
+        const estimatedRetryCost = toRetry.reduce((sum, u)=>sum + (typeof u.costUsd === 'number' ? u.costUsd : 0), 0);
+        const capResult = await checkAndIncrementDailySpend(req.payload, estimatedRetryCost, {
+            capUsd: bulkConfig.dailyUsdCap
+        });
+        if (!capResult.allowed) {
+            try {
+                await bulkConfig.onCapExceeded?.({
+                    todaySpentUsd: capResult.todaySpentUsd,
+                    capUsd: capResult.capUsd,
+                    rejectedEstimateUsd: estimatedRetryCost,
+                    requestPath: 'bulk-endpoint'
+                });
+            } catch  {
+            // Best-effort hook — never block the response on callback.
+            }
+            return errorResponse(capResult.reason === 'cap_exceeded' ? 'daily_cap_exceeded' : 'invalid_estimate', capResult.message, 402, {
+                todaySpentUsd: String(capResult.todaySpentUsd),
+                remainingUsd: String(capResult.remainingUsd),
+                capUsd: String(capResult.capUsd)
+            });
+        }
+        // ----- Re-enqueue -----
+        let retriedJobs = 0;
+        for (const u of toRetry){
+            try {
+                await req.payload.update({
+                    collection: unitsSlug,
+                    id: u.id,
+                    data: {
+                        status: 'pending',
+                        attempts: (u.attempts ?? 0) + 0,
+                        failureCode: null,
+                        failureMessage: null,
+                        completedAt: null
+                    },
+                    overrideAccess: true
+                });
+                await req.payload.jobs.queue({
+                    task: workerSlug,
+                    input: {
+                        unitId: String(u.id)
+                    }
+                });
+                retriedJobs += 1;
+            } catch (err) {
+                req.payload.logger?.warn?.(`[ai-translate] retry-failed: failed to requeue unit ${u.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // ----- Reset batch to running so transitions resume -----
+        if (retriedJobs > 0) {
+            try {
+                await req.payload.update({
+                    collection: batchesSlug,
+                    id: batchId,
+                    data: {
+                        status: 'running',
+                        completedAt: null
+                    },
+                    overrideAccess: true
+                });
+            } catch (err) {
+                req.payload.logger?.warn?.(`[ai-translate] retry-failed: failed to reset batch ${batchId} status: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return Response.json({
+            data: {
+                batchId,
+                retriedJobs,
+                skippedJobs: skipped.length
+            }
+        });
+    };
+async function loadAllFailedUnits(payload, unitsSlug, batchId) {
+    // Paginate to bound memory. 1000 per page is well below Payload's
+    // default heap budget and works for realistic batch sizes
+    // (~10k units would page 10 times).
+    const out = [];
+    const limit = 1000;
+    let page = 1;
+    // eslint-disable-next-line no-constant-condition
+    while(true){
+        const result = await payload.find({
+            collection: unitsSlug,
+            where: {
+                and: [
+                    {
+                        batchId: {
+                            equals: batchId
+                        }
+                    },
+                    {
+                        status: {
+                            equals: 'failed'
+                        }
+                    }
+                ]
+            },
+            page,
+            limit,
+            depth: 0,
+            overrideAccess: true
+        });
+        for (const doc of result.docs){
+            out.push({
+                id: doc.id,
+                attempts: typeof doc.attempts === 'number' ? doc.attempts : 0,
+                failureCode: typeof doc.failureCode === 'string' ? doc.failureCode : null,
+                costUsd: typeof doc.costUsd === 'number' ? doc.costUsd : 0,
+                collection: typeof doc.collection === 'string' ? doc.collection : undefined,
+                documentId: typeof doc.documentId === 'string' ? doc.documentId : undefined
+            });
+        }
+        if (!result.hasNextPage) break;
+        page += 1;
+    }
+    return out;
+}

package/dist/endpoints/translation-hub/revert.d.ts

@@ -0,0 +1,88 @@
+import type { PayloadHandler } from 'payload';
+export interface BulkRevertBody {
+    /** Required — TOTP is mandatory regardless of plugin config (Decision #33). */
+    totpCode?: string;
+    /**
+     * Bypass the schema-drift refusal when set to `true`. Decision #34
+     * + F-DA-REVERT-SCHEMA: revert refuses on schema mismatch unless
+     * the admin explicitly opts in. Use with caution — restoring data
+     * against a renamed/removed field can corrupt the doc.
+     */
+    force?: boolean;
+}
+export interface BulkRevertWarning {
+    unitId: string;
+    collection: string;
+    documentId: string;
+    locale: string;
+    reason: 'schema_drift' | 'no_snapshot' | 'snapshot_locale_mismatch' | 'restore_failed' | 'doc_deleted';
+    message?: string;
+}
+export interface BulkRevertHandlerOptions {
+    batchesCollectionSlug?: string;
+    unitsCollectionSlug?: string;
+    /**
+     * Wall-clock window after `completedAt` during which revert is
+     * permitted (Decision #33). Defaults to 24h.
+     */
+    windowMs?: number;
+    /**
+     * Page size for the unit iteration. Default 100 — bounded so the
+     * handler stays within serverless memory budgets per F-DA-REVERT-OOM.
+     */
+    pageSize?: number;
+}
+/**
+ * `POST /api/translation-hub/bulk-translate/:id/revert`
+ *
+ * Restores the pre-run snapshot of every `success` unit in the batch.
+ * Decision #22 v2 / F-DA-REVERT: the snapshot is a nested-object
+ * payload directly passable to `payload.update({ data: snapshot })`.
+ *
+ * Refusal cases:
+ *   - non-revertable batch status (must be `completed | partial`).
+ *   - batch is currently in-flight (`queued | running | cancelling`).
+ *   - batch's `completedAt` is more than `windowMs` ago.
+ *   - TOTP required regardless of plugin config (Decision #33).
+ *
+ * Per-unit warnings (don't abort the run):
+ *   - `schema_drift` — schema hash differs and `force !== true`.
+ *   - `no_snapshot` — unit has no `preRunSnapshot` (older row).
+ *   - `restore_failed` — `payload.update` threw.
+ *   - `doc_deleted` — the source doc was deleted post-bulk; nothing
+ *     to revert against.
+ *
+ * Writes are flagged via `context: { aiTranslateInternal: true,
+ * disableRevalidate: true }` so:
+ *   - audit-log marks them `source: 'ai-translate'` (avoids confusing
+ *     editor with 1000 "user updated" entries for a revert).
+ *   - the plugin's allowlist-spread at translate.ts:483 + the
+ *     consumer's revalidate hooks honor the disable flag — we'll
+ *     fire a terminal revalidate sweep at the end.
+ */
+export declare const getBulkTranslateRevertHandler: (options?: BulkRevertHandlerOptions) => PayloadHandler;
+export type RevertUnitRow = {
+    id: string | number;
+    collection: string;
+    documentId: string;
+    locale: string;
+    preRunSnapshot: Record<string, unknown> | null;
+    /** Locale whose values `preRunSnapshot` holds (v1.2.12+; null on legacy rows). */
+    snapshotLocale: string | null;
+    schemaHash: string | null;
+};
+export type RevertOutcome = {
+    reverted: true;
+} | {
+    reverted: false;
+    warning?: BulkRevertWarning;
+};
+export type RevertSingleParams = {
+    payload: import('payload').Payload;
+    unit: RevertUnitRow;
+    unitsSlug: string;
+    currentSchemaHashByCollection: Map<string, string>;
+    force: boolean;
+    pluginGlobals: Set<string>;
+};
+export declare function revertSingleUnit(params: RevertSingleParams): Promise<RevertOutcome>;