@purposeinplay/payload-ai-translate 0.1.0

package/dist/endpoints/translation-hub/revert.js

@@ -0,0 +1,405 @@
+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 { resolveTranslatableFields } from '../../lib/field-resolver.js';
+import { createScopedLogger } from '../../lib/logger.js';
+import { hashLocalizedSchema } from '../../lib/snapshot-select.js';
+import { errorResponse, forbiddenOwnershipResponse, isEditorOrAdmin, ownsBatch, readJsonBody, unauthorizedResponse, verifyTotpCode, writeBulkAuditEntry } from './_helpers.js';
+import { extractBatchId } from './status.js';
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+const REVERTABLE_TERMINAL = new Set([
+    'success',
+    'partial'
+]);
+const IN_FLIGHT = new Set([
+    'queued',
+    'running',
+    'cancelling'
+]);
+/**
+ * `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 const getBulkTranslateRevertHandler = (options = {})=>async (req)=>{
+        const batchesSlug = options.batchesCollectionSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+        const unitsSlug = options.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+        const windowMs = options.windowMs ?? 24 * 60 * 60 * 1000;
+        const pageSize = options.pageSize ?? 100;
+        if (!req.user) {
+            return unauthorizedResponse(req);
+        }
+        if (!isEditorOrAdmin(req.user)) {
+            return errorResponse('forbidden', "You don't have permission to revert a bulk-translation batch. Contact an admin.", 403);
+        }
+        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 body = parsed.body;
+        // ----- TOTP gate (Decision #33 — mandatory, not config-gated) -----
+        const totpResult = await verifyTotpCode(req.payload, req.user.id, body.totpCode, {
+            required: true,
+            // Revert is destructive — refuse if TOTP plugin is unavailable
+            // (better to fail loud than allow an unauthenticated revert).
+            allowSkipWhenUnavailable: false
+        });
+        if (!totpResult.ok) {
+            const status = totpResult.code === 'missing' ? 400 : 401;
+            return errorResponse('totp_' + totpResult.code, totpResult.message, status);
+        }
+        // ----- Load batch + state checks -----
+        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.revert',
+                batchId
+            });
+            log.event('warn', 'hub.revert.batch-read.failed', {
+                err,
+                endpoint: 'hub.revert',
+                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 revert a run they triggered. Admins pass.
+        // Revert is destructive so this gate is critical — without it an
+        // editor could roll back another editor's completed work.
+        if (!ownsBatch(req.user, batch)) {
+            return forbiddenOwnershipResponse();
+        }
+        if (IN_FLIGHT.has(batch.status)) {
+            return errorResponse('invalid_state', 'The run is still in progress. Cancel it first, then revert.', 409, {
+                status: batch.status
+            });
+        }
+        if (!REVERTABLE_TERMINAL.has(batch.status)) {
+            return errorResponse('invalid_state', 'Only completed or partial runs can be reverted — this run is in a different state.', 409, {
+                status: batch.status
+            });
+        }
+        if (!batch.completedAt) {
+            return errorResponse('invalid_state', "This run is missing a completion timestamp, so the system can't check if it's still revertable. Contact engineering.", 409);
+        }
+        const completedAtMs = new Date(batch.completedAt).getTime();
+        if (!Number.isFinite(completedAtMs)) {
+            return errorResponse('invalid_state', "This run's completion timestamp is unreadable. Contact engineering.", 409);
+        }
+        const ageMs = Date.now() - completedAtMs;
+        if (ageMs > windowMs) {
+            const hoursAgo = Math.floor(ageMs / 3_600_000);
+            const windowHours = Math.floor(windowMs / 3_600_000);
+            return errorResponse('window_expired', `The ${windowHours}-hour window to undo this run has passed (it ran ${hoursAgo} hours ago). Contact engineering if you need to restore earlier content.`, 409, {
+                hoursElapsed: String(hoursAgo),
+                hoursWindow: String(windowHours)
+            });
+        }
+        // ----- Compute current schema hashes per collection (Decision #34) -----
+        const currentSchemaHashByCollection = computeCurrentSchemaHashes(req.payload);
+        // ----- Paginate units and revert -----
+        const warnings = [];
+        let revertedUnits = 0;
+        let skippedUnits = 0;
+        const affectedCollections = new Set();
+        const affectedGlobals = new Set();
+        const pluginGlobals = new Set((req.payload.config?.globals ?? []).map((g)=>g.slug));
+        let page = 1;
+        // eslint-disable-next-line no-constant-condition
+        while(true){
+            const result = await req.payload.find({
+                collection: unitsSlug,
+                where: {
+                    and: [
+                        {
+                            batchId: {
+                                equals: batchId
+                            }
+                        },
+                        {
+                            status: {
+                                equals: 'success'
+                            }
+                        }
+                    ]
+                },
+                page,
+                limit: pageSize,
+                depth: 0,
+                overrideAccess: true
+            });
+            const docs = result.docs;
+            for (const u of docs){
+                const unit = {
+                    id: u.id,
+                    collection: String(u.collection ?? ''),
+                    documentId: String(u.documentId ?? ''),
+                    locale: String(u.locale ?? ''),
+                    preRunSnapshot: u.preRunSnapshot && typeof u.preRunSnapshot === 'object' ? u.preRunSnapshot : null,
+                    snapshotLocale: typeof u.snapshotLocale === 'string' ? u.snapshotLocale : null,
+                    schemaHash: typeof u.schemaHash === 'string' ? u.schemaHash : null
+                };
+                const outcome = await revertSingleUnit({
+                    payload: req.payload,
+                    unit,
+                    unitsSlug,
+                    currentSchemaHashByCollection,
+                    force: body.force === true,
+                    pluginGlobals
+                });
+                if (outcome.reverted) {
+                    revertedUnits += 1;
+                    if (pluginGlobals.has(unit.collection)) {
+                        affectedGlobals.add(unit.collection);
+                    } else {
+                        affectedCollections.add(unit.collection);
+                    }
+                } else {
+                    skippedUnits += 1;
+                    if (outcome.warning) warnings.push(outcome.warning);
+                }
+            }
+            if (!result.hasNextPage) break;
+            page += 1;
+        }
+        // ----- Mark batch reverted -----
+        const revertedAt = new Date().toISOString();
+        try {
+            await req.payload.update({
+                collection: batchesSlug,
+                id: batchId,
+                data: {
+                    status: 'reverted',
+                    revertedAt,
+                    revertedByUserId: String(req.user.id)
+                },
+                overrideAccess: true
+            });
+        } catch (err) {
+            req.payload.logger?.error?.(`[ai-translate] revert: failed to mark batch ${batchId} reverted: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ----- Audit log (Decision #33) -----
+        const userEmail = typeof req.user.email === 'string' ? req.user.email : undefined;
+        await writeBulkAuditEntry(req.payload, {
+            userId: req.user.id,
+            userEmail,
+            action: 'bulk-translate.revert',
+            batchId,
+            metadata: {
+                revertedUnits,
+                skippedUnits,
+                warnings: warnings.length,
+                force: body.force === true,
+                affectedCollections: Array.from(affectedCollections),
+                affectedGlobals: Array.from(affectedGlobals)
+            }
+        });
+        // ----- Terminal revalidate sweep -----
+        await fireRevalidateSweep(req.payload, affectedCollections, affectedGlobals);
+        return Response.json({
+            data: {
+                batchId,
+                revertedUnits,
+                skippedUnits,
+                warnings,
+                revertedAt
+            }
+        });
+    };
+function computeCurrentSchemaHashes(payload) {
+    const out = new Map();
+    for (const c of payload.config?.collections ?? []){
+        try {
+            const fields = resolveTranslatableFields(c.fields);
+            out.set(c.slug, hashLocalizedSchema(fields));
+        } catch  {
+        // skip; the per-unit check will see a missing entry and warn
+        }
+    }
+    for (const g of payload.config?.globals ?? []){
+        try {
+            const fields = resolveTranslatableFields(g.fields);
+            out.set(g.slug, hashLocalizedSchema(fields));
+        } catch  {
+        // skip
+        }
+    }
+    return out;
+}
+export async function revertSingleUnit(params) {
+    const { payload, unit, unitsSlug, currentSchemaHashByCollection, force, pluginGlobals } = params;
+    if (!unit.preRunSnapshot || Object.keys(unit.preRunSnapshot).length === 0) {
+        return {
+            reverted: false,
+            warning: {
+                unitId: String(unit.id),
+                collection: unit.collection,
+                documentId: unit.documentId,
+                locale: unit.locale,
+                reason: 'no_snapshot',
+                message: 'No pre-run snapshot captured for this unit.'
+            }
+        };
+    }
+    // v1.2.12 — HARD gate, deliberately NOT overridable by `force`.
+    // Snapshots written before v1.2.12 were captured from the
+    // SOURCE-locale enumeration read and shared across every target
+    // locale of the doc; replaying one stamps source-language content
+    // over the translation it claims to restore (2026-06-11 prod
+    // incident: a batch revert turned every target locale English).
+    // Only a snapshot the worker captured FROM this unit's own locale
+    // may ever be written back to it.
+    if (unit.snapshotLocale !== unit.locale) {
+        return {
+            reverted: false,
+            warning: {
+                unitId: String(unit.id),
+                collection: unit.collection,
+                documentId: unit.documentId,
+                locale: unit.locale,
+                reason: 'snapshot_locale_mismatch',
+                message: unit.snapshotLocale === null ? 'Snapshot predates v1.2.12 and holds source-locale values — reverting would overwrite this translation with source-language content. Not revertable.' : `Snapshot holds "${unit.snapshotLocale}" values but this unit targets "${unit.locale}" — refusing to write cross-locale content.`
+            }
+        };
+    }
+    const currentHash = currentSchemaHashByCollection.get(unit.collection);
+    if (!force && currentHash && unit.schemaHash && currentHash !== unit.schemaHash) {
+        return {
+            reverted: false,
+            warning: {
+                unitId: String(unit.id),
+                collection: unit.collection,
+                documentId: unit.documentId,
+                locale: unit.locale,
+                reason: 'schema_drift',
+                message: 'Schema of localized translatable fields changed since snapshot. Re-run with force: true to override.'
+            }
+        };
+    }
+    // Restore the snapshot. We pass `context.aiTranslateInternal=true`
+    // to mark the write as machine-generated (audit-log will tag the
+    // entry `source: 'ai-translate'` rather than `user`) and
+    // `disableRevalidate=true` to suppress per-doc revalidation — we
+    // fire a single terminal sweep at the end of the revert.
+    try {
+        if (pluginGlobals.has(unit.collection)) {
+            await payload.updateGlobal({
+                slug: unit.collection,
+                locale: unit.locale,
+                data: unit.preRunSnapshot,
+                context: {
+                    aiTranslateInternal: true,
+                    disableRevalidate: true
+                },
+                overrideAccess: true
+            });
+        } else {
+            await payload.update({
+                collection: unit.collection,
+                id: unit.documentId,
+                locale: unit.locale,
+                data: unit.preRunSnapshot,
+                context: {
+                    aiTranslateInternal: true,
+                    disableRevalidate: true
+                },
+                overrideAccess: true
+            });
+        }
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isMissing = /not found/i.test(message);
+        return {
+            reverted: false,
+            warning: {
+                unitId: String(unit.id),
+                collection: unit.collection,
+                documentId: unit.documentId,
+                locale: unit.locale,
+                reason: isMissing ? 'doc_deleted' : 'restore_failed',
+                message
+            }
+        };
+    }
+    try {
+        await payload.update({
+            collection: unitsSlug,
+            id: unit.id,
+            data: {
+                status: 'reverted'
+            },
+            overrideAccess: true
+        });
+    } catch (err) {
+        // Unit-row update failure shouldn't drop us into a warning — the
+        // real-world write succeeded. Log and move on.
+        payload.logger?.warn?.(`[ai-translate] revert: failed to mark unit ${unit.id} reverted: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        reverted: true
+    };
+}
+async function fireRevalidateSweep(payload, collections, globals) {
+    // The plugin doesn't take a hard dependency on Next.js — instead,
+    // we attempt to dynamically import `next/cache` and call
+    // `revalidateTag` for each affected surface. This is best-effort:
+    // running in a non-Next environment (e.g. tests, Payload CLI) is
+    // simply a no-op.
+    let revalidateTag;
+    try {
+        const mod = await import('next/cache');
+        revalidateTag = mod.revalidateTag;
+    } catch  {
+        return;
+    }
+    if (!revalidateTag) return;
+    for (const slug of collections){
+        try {
+            revalidateTag(`${slug}-sitemap`);
+            revalidateTag(slug);
+        } catch (err) {
+            payload.logger?.warn?.(`[ai-translate] revert: revalidateTag(${slug}) failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    for (const slug of globals){
+        try {
+            revalidateTag(slug);
+        } catch (err) {
+            payload.logger?.warn?.(`[ai-translate] revert: revalidateTag(${slug}) failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

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

@@ -0,0 +1,45 @@
+import type { PayloadHandler } from 'payload';
+export type BatchJobSummary = {
+    unitId: string;
+    collection: string;
+    documentId: string;
+    locale: string;
+    status: string;
+    attempts: number;
+    failureCode: string | null;
+    failureMessage: string | null;
+    costUsd: number;
+    startedAt: string | null;
+    completedAt: string | null;
+    /**
+     * AI call time in milliseconds, summed across all batches for this
+     * unit's locale. Excludes token-bucket wait + rate-limit backoff —
+     * those happen before the SDK call and are not counted here.
+     * `null` on legacy rows where the column wasn't populated.
+     */
+    processingDurationMs: number | null;
+};
+export interface BulkStatusHandlerOptions {
+    batchesCollectionSlug?: string;
+    unitsCollectionSlug?: string;
+}
+/**
+ * `GET /api/translation-hub/bulk-translate/:id/status`
+ *
+ * Returns batch metadata + aggregate counts by unit status + a
+ * paginated drill-down list of units (filterable by status).
+ *
+ * Query params:
+ *   - `cursor` — opaque cursor returned by the previous page
+ *   - `limit` — page size (default 20, max 100)
+ *   - `status` — filter to one unit status (`failed` is the typical
+ *     value for the failure drill-down UI)
+ */
+export declare const getBulkTranslateStatusHandler: (options?: BulkStatusHandlerOptions) => PayloadHandler;
+/**
+ * Extracts the batch id from a URL of the shape
+ * `/api/translation-hub/bulk-translate/<id>/status`. Defensive across
+ * URL variants Payload may give us — we look for the segment between
+ * `bulk-translate` and `status`.
+ */
+export declare function extractBatchId(url: string): string | undefined;