@purposeinplay/payload-ai-translate 0.1.0

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

@@ -0,0 +1,529 @@
+import { DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG } from '../../bulk-translate-batches-collection.js';
+import { collectBlocksConfig, extractTranslationUnits } from '../../lib/content-extractor.js';
+import { checkAndIncrementDailySpend } from '../../lib/daily-spend-cap.js';
+import { getEffectiveExcludePatternsForSurface, getGlobalKillSwitches } from '../../lib/effective-locales.js';
+import { resolveTranslatableFields } from '../../lib/field-resolver.js';
+import { findByIdNoFallback } from '../../lib/payload-read.js';
+import { DEFAULT_SETTINGS_GLOBAL_SLUG } from '../../settings-global.js';
+import { BULK_TRANSLATE_COORDINATOR_SLUG } from '../../tasks/bulk-translate-coordinator.js';
+import { errorResponse, getAiTranslateConfig, isEditorOrAdmin, readJsonBody, unauthorizedResponse, verifyTotpCode } from './_helpers.js';
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+/**
+ * `POST /api/translation-hub/bulk-translate` — enqueue a bulk run.
+ *
+ * Flow (see Design-2026-05-27-bulk-translate.md §4 PR2):
+ *   1. Auth — admin role (Decision #31).
+ *   2. TOTP friction — gated by `bulk.requireTotp` (Decision #13 v2).
+ *      Friction-not-boundary: the daily USD cap is the real guard.
+ *   3. Body validation — discriminated by `mode`.
+ *   4. Concurrency refusal — one bulk run at a time per Decision #2.
+ *   5. Cost estimate — sum provider's `estimate()` across the resolved
+ *      doc list. Hard-reject if `undefined` (Decision #29). Canary
+ *      mode skips estimation — too cheap to matter.
+ *   6. Daily cap — `checkAndIncrementDailySpend` (Decision #14).
+ *   7. Snapshot pinned config — `{ providerKey, modelId, sourceLocale }`
+ *      captured at enqueue (Decision #5).
+ *   8. Create batch row → queue coordinator task → 202.
+ */ export const getBulkTranslateEnqueueHandler = (options = {})=>async (req)=>{
+        const batchesSlug = options.batchesCollectionSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+        const coordinatorTaskSlug = options.coordinatorTaskSlug ?? BULK_TRANSLATE_COORDINATOR_SLUG;
+        if (!req.user) {
+            return unauthorizedResponse(req);
+        }
+        if (!isEditorOrAdmin(req.user)) {
+            return errorResponse('forbidden', "You don't have permission to start a bulk translation. Contact an admin.", 403);
+        }
+        const config = getAiTranslateConfig(req.payload);
+        if (!config) {
+            return errorResponse('not_configured', "The translation system isn't set up for this site. Contact engineering.", 500);
+        }
+        // Bulk engine is on whenever the consumer passes a `bulk` block
+        // and hasn't explicitly opted out (`enabled: false`). Mirrors the
+        // boot-time gate in `plugin.ts`.
+        const bulkConfig = config.bulk;
+        if (!bulkConfig || bulkConfig.enabled === false) {
+            return errorResponse('not_configured', "Bulk translation isn't enabled for this site. Contact engineering.", 403);
+        }
+        // Plugin-wide bulk-translate kill switch (v1.2.8). When admin
+        // flipped `globalBulkTranslateEnabled` off in the settings global,
+        // NEW bulk runs are rejected here. In-flight runs that were
+        // already enqueued continue to completion — the worker
+        // (`bulk-translate-doc-task`) does not poll this flag, so this
+        // gate is "block new enqueues only" by design. Manual Translate
+        // and auto-translate are unaffected.
+        const killSwitches = await getGlobalKillSwitches(req.payload, config);
+        if (!killSwitches.bulkEnabled) {
+            return errorResponse('bulk_translate_disabled', 'Bulk Translate is paused site-wide. An admin can re-enable it in Translation Settings. Any run that was already in progress will continue to completion.', 403);
+        }
+        const parsed = await readJsonBody(req);
+        if (!parsed.ok) return parsed.res;
+        const body = parsed.body;
+        const validationError = validateEnqueueBody(body, config);
+        if (validationError) return validationError;
+        // ----- TOTP gate (Decision #13 v2) -----
+        // Accept both `totpCode` (canonical) and `totp` (UI alias) — the
+        // modal sends the shorter name.
+        const totpCode = body.totpCode ?? body.totp;
+        const totpResult = await verifyTotpCode(req.payload, req.user.id, totpCode, {
+            required: bulkConfig.requireTotp === true,
+            // Skip when TOTP plugin isn't installed — Decision #13 v2
+            // explicitly downgrades TOTP to friction-not-boundary; the
+            // daily USD cap is the real enforcement and applies below.
+            allowSkipWhenUnavailable: true
+        });
+        if (!totpResult.ok) {
+            const status = totpResult.code === 'missing' ? 400 : 401;
+            return errorResponse('totp_' + totpResult.code, totpResult.message, status);
+        }
+        // ----- Concurrency refusal (Decision #2) -----
+        const inFlight = await findInFlightBatchForUser(req.payload, batchesSlug, String(req.user.id));
+        if (inFlight) {
+            return errorResponse('concurrent_batch', 'A translation run is already in progress. Cancel the current run before starting a new one.', 409, {
+                existingBatchId: String(inFlight.id)
+            });
+        }
+        // ----- Resolve scope → document list -----
+        const resolvedScope = resolveScope(body.scope, config, bulkConfig);
+        if (resolvedScope.collections.length === 0 && resolvedScope.globals.length === 0) {
+            return errorResponse('empty_scope', 'The selected scope contains nothing to translate — pick at least one collection or global.', 400, {
+                scope: 'empty'
+            });
+        }
+        // ----- Cost estimate (Decision #29: hard-reject undefined) -----
+        // Canary mode skips estimation (Decision #26: small fixed sample).
+        let estimatedCostUsd;
+        let estimatedDocs = 0;
+        if (body.mode === 'canary') {
+            estimatedCostUsd = 0; // free pass — canary is bounded by canaryLimit
+            estimatedDocs = body.canaryLimit ?? bulkConfig.canaryDefaultSize ?? 10;
+        } else {
+            const estimate = await estimateBatchCost(req.payload, config, resolvedScope);
+            if (estimate.estimatedCostUsd === undefined) {
+                return errorResponse('cost_unavailable', "A cost estimate couldn't be calculated for the current AI model. The run is blocked as a safety measure — contact engineering to check the model's pricing configuration.", 402);
+            }
+            estimatedCostUsd = estimate.estimatedCostUsd;
+            estimatedDocs = estimate.documentCount;
+        }
+        // ----- Daily cap (Decision #14) -----
+        const capResult = await checkAndIncrementDailySpend(req.payload, estimatedCostUsd, {
+            capUsd: bulkConfig.dailyUsdCap
+        });
+        if (!capResult.allowed) {
+            // Fire onCapExceeded so consumers can page on-call before the
+            // cap silently locks out the day.
+            try {
+                await bulkConfig.onCapExceeded?.({
+                    todaySpentUsd: capResult.todaySpentUsd,
+                    capUsd: capResult.capUsd,
+                    rejectedEstimateUsd: estimatedCostUsd,
+                    requestPath: 'bulk-endpoint'
+                });
+            } catch  {
+            // Best-effort hook — never block the response on a consumer
+            // callback exception.
+            }
+            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)
+            });
+        }
+        // ----- Snapshot pinned config (Decision #5) -----
+        const snapshot = await snapshotActiveProviderConfig(req.payload, config);
+        // ----- Create batch row -----
+        const enqueuedAt = new Date().toISOString();
+        const userEmail = typeof req.user.email === 'string' ? req.user.email : undefined;
+        const totalLocales = resolvedScope.locales.length;
+        const totalUnits = estimatedDocs * Math.max(1, totalLocales);
+        const batch = await req.payload.create({
+            collection: batchesSlug,
+            data: {
+                scope: {
+                    collections: resolvedScope.collections,
+                    globals: resolvedScope.globals,
+                    locales: resolvedScope.locales,
+                    excludeCollections: resolvedScope.excludeCollections,
+                    documentIds: resolvedScope.documentIdsFlat,
+                    sourceLocale: snapshot.sourceLocale,
+                    mode: body.mode,
+                    canaryLimit: body.mode === 'canary' ? body.canaryLimit ?? bulkConfig.canaryDefaultSize ?? 10 : undefined
+                },
+                mode: body.mode,
+                canaryLimit: body.mode === 'canary' ? body.canaryLimit ?? bulkConfig.canaryDefaultSize ?? 10 : undefined,
+                snapshotProviderKey: snapshot.providerKey,
+                snapshotModelId: snapshot.modelId,
+                snapshotSourceLocale: snapshot.sourceLocale,
+                estimatedCostUsd,
+                actualCostUsd: 0,
+                status: 'queued',
+                totalUnits,
+                completedUnits: 0,
+                failedUnits: 0,
+                skippedUnits: 0,
+                triggeredByUserId: String(req.user.id),
+                triggeredByEmail: userEmail,
+                triggerReason: body.triggerReason,
+                enqueuedAt
+            },
+            overrideAccess: true
+        });
+        // ----- Queue coordinator -----
+        try {
+            await req.payload.jobs.queue({
+                task: coordinatorTaskSlug,
+                input: {
+                    batchId: String(batch.id)
+                }
+            });
+        } catch (err) {
+            // Coordinator queue failed — mark batch failed immediately so
+            // the user gets a real error rather than a phantom queued row.
+            await req.payload.update({
+                collection: batchesSlug,
+                id: batch.id,
+                data: {
+                    status: 'failed',
+                    completedAt: new Date().toISOString(),
+                    failures: {
+                        queue_error: 1,
+                        message: err instanceof Error ? err.message : String(err)
+                    }
+                },
+                overrideAccess: true
+            });
+            return errorResponse('queue_failed', "The translation run couldn't be started. Try again, or contact engineering if it keeps happening.", 500);
+        }
+        const batchId = String(batch.id);
+        return Response.json({
+            data: {
+                batchId,
+                status: 'queued',
+                statusUrl: `/api/translation-hub/bulk-translate/${batchId}/status`,
+                estimatedCostUsd,
+                estimatedDocs,
+                totalUnits,
+                enqueuedAt
+            }
+        }, {
+            status: 202
+        });
+    };
+function validateEnqueueBody(body, config) {
+    if (!body || typeof body !== 'object') {
+        return errorResponse('invalid_body', 'Request body must be an object.', 400);
+    }
+    // Default scope to empty object when omitted. `resolveScope()` fills
+    // it in from the plugin config — clicking "Bulk Translate" from the
+    // Hub with no narrowing means "everything tracked", and the UI
+    // shouldn't need to re-state the plugin's collection list.
+    if (!body.scope) {
+        body.scope = {};
+    }
+    if (typeof body.scope !== 'object') {
+        return errorResponse('invalid_body', '`scope` must be an object when provided.', 400, {
+            scope: 'invalid'
+        });
+    }
+    const mode = body.mode;
+    if (mode !== 'changed' && mode !== 'force' && mode !== 'canary') {
+        return errorResponse('invalid_body', 'mode must be one of: changed | force | canary.', 400, {
+            mode: 'invalid'
+        });
+    }
+    if (mode === 'canary') {
+        const limit = body.canaryLimit;
+        if (limit !== undefined && (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0)) {
+            return errorResponse('invalid_body', 'canaryLimit must be a positive number when provided.', 400, {
+                canaryLimit: 'invalid'
+            });
+        }
+    }
+    // Validate locales against the plugin's configured `targetLocales`.
+    // The coordinator already filters source-locale matches, so we only
+    // gate against typos / locales the plugin can't translate to.
+    const locales = body.scope.locales;
+    if (locales !== undefined) {
+        if (!Array.isArray(locales)) {
+            return errorResponse('invalid_body', 'scope.locales must be an array of locale codes.', 400, {
+                'scope.locales': 'invalid'
+            });
+        }
+        const allowed = new Set(config.targetLocales);
+        const invalid = locales.filter((l)=>!allowed.has(l));
+        if (invalid.length > 0) {
+            return errorResponse('invalid_locale', `Locale(s) not configured in plugin.targetLocales: ${invalid.join(', ')}.`, 400, {
+                'scope.locales': 'invalid'
+            });
+        }
+        // An explicit empty list is a contradiction, not a default — a run
+        // that translates into zero locales can't mean anything. Reject it
+        // rather than silently falling back to all targetLocales.
+        if (locales.length === 0) {
+            return errorResponse('invalid_body', 'scope.locales must contain at least one locale when provided.', 400, {
+                'scope.locales': 'empty'
+            });
+        }
+    }
+    for (const key of [
+        'collections',
+        'globals',
+        'excludeCollections'
+    ]){
+        const v = body.scope[key];
+        if (v !== undefined && (!Array.isArray(v) || v.some((s)=>typeof s !== 'string'))) {
+            return errorResponse('invalid_body', `scope.${key} must be an array of strings when provided.`, 400, {
+                [`scope.${key}`]: 'invalid'
+            });
+        }
+    }
+    if (body.scope.documentIds !== undefined) {
+        if (typeof body.scope.documentIds !== 'object' || body.scope.documentIds === null || Array.isArray(body.scope.documentIds)) {
+            return errorResponse('invalid_body', 'scope.documentIds must be a record of collection → string[].', 400, {
+                'scope.documentIds': 'invalid'
+            });
+        }
+        for (const [collection, ids] of Object.entries(body.scope.documentIds)){
+            if (!Array.isArray(ids) || ids.some((id)=>typeof id !== 'string')) {
+                return errorResponse('invalid_body', `scope.documentIds.${collection} must be a string[].`, 400, {
+                    [`scope.documentIds.${collection}`]: 'invalid'
+                });
+            }
+        }
+    }
+    return null;
+}
+export function resolveScope(scope, config, bulk) {
+    const pluginCollections = config.collections ?? [];
+    const pluginGlobals = config.globals ?? [];
+    const pluginExcludes = new Set(bulk.excludeCollections ?? []);
+    // ABSENT means "everything the plugin tracks" (back-compat default);
+    // an EXPLICIT array — including an empty one — means exactly what the
+    // caller selected. The previous `length > 0` check collapsed "the user
+    // deselected every global" into "unspecified", so a run scoped to a
+    // single collection silently fanned out to all globals (and vice
+    // versa for collections).
+    const requestedCollections = Array.isArray(scope.collections) ? scope.collections : pluginCollections;
+    const requestedGlobals = Array.isArray(scope.globals) ? scope.globals : pluginGlobals;
+    const excludeCollections = new Set([
+        ...scope.excludeCollections ?? [],
+        ...pluginExcludes
+    ]);
+    // Filter by both the requested set AND the plugin's tracked
+    // collections — a caller can't bulk-translate a collection the
+    // plugin doesn't know about (and shouldn't be able to). Plugin-
+    // tracked-only also closes the security N5 doppelganger here.
+    const trackedCollections = new Set(pluginCollections);
+    const trackedGlobals = new Set(pluginGlobals);
+    const collectionsList = requestedCollections.filter((c)=>trackedCollections.has(c) && !excludeCollections.has(c));
+    const globalsList = requestedGlobals.filter((g)=>trackedGlobals.has(g));
+    const locales = scope.locales && scope.locales.length > 0 ? scope.locales : [
+        ...config.targetLocales
+    ];
+    // Flatten documentIds map → flat array of ids the coordinator can
+    // consume. We don't preserve the collection→ids mapping in the
+    // batch row's scope.documentIds because the coordinator currently
+    // accepts only a flat list (matches its existing semantics —
+    // documents-explicit mode walks the same collection it's enumerating).
+    let documentIdsFlat = [];
+    if (scope.documentIds) {
+        for (const [coll, ids] of Object.entries(scope.documentIds)){
+            if (!collectionsList.includes(coll)) continue;
+            documentIdsFlat = documentIdsFlat.concat(ids);
+        }
+    }
+    return {
+        collections: collectionsList,
+        globals: globalsList,
+        locales,
+        excludeCollections: Array.from(excludeCollections),
+        documentIdsFlat
+    };
+}
+async function findInFlightBatchForUser(payload, batchesSlug, userId) {
+    const result = await payload.find({
+        collection: batchesSlug,
+        where: {
+            and: [
+                {
+                    triggeredByUserId: {
+                        equals: userId
+                    }
+                },
+                {
+                    status: {
+                        in: [
+                            'queued',
+                            'running',
+                            'cancelling'
+                        ]
+                    }
+                }
+            ]
+        },
+        limit: 1,
+        depth: 0,
+        overrideAccess: true
+    });
+    const doc = result.docs[0];
+    return doc;
+}
+/**
+ * Enumerate the scope's docs, run the provider's `estimate()` once
+ * with the aggregated items, multiply by locale count. Mirrors the
+ * pattern in `translate.ts:estimateRequestCost` but at batch scale.
+ *
+ * Returns `estimatedCostUsd: undefined` only when the provider has no
+ * `estimate()` method — the enqueue handler then hard-rejects per
+ * Decision #29.
+ */ export async function estimateBatchCost(payload, config, scope) {
+    if (!config.provider.estimate) {
+        return {
+            estimatedCostUsd: undefined,
+            documentCount: 0
+        };
+    }
+    const allItems = [];
+    let documentCount = 0;
+    for (const collectionSlug of scope.collections){
+        const collections = payload.config?.collections ?? [];
+        const collectionConfig = collections.find((c)=>c.slug === collectionSlug);
+        if (!collectionConfig) continue;
+        const translatableFields = resolveTranslatableFields(collectionConfig.fields);
+        const blocksConfig = collectBlocksConfig(collectionConfig.fields);
+        const excludePatterns = await getEffectiveExcludePatternsForSurface(payload, config, collectionSlug);
+        // If documentIdsFlat is non-empty, only estimate those docs in
+        // this collection. Otherwise paginate the whole collection.
+        const idsForThisCollection = scope.documentIdsFlat;
+        const docs = [];
+        if (idsForThisCollection.length > 0) {
+            for (const id of idsForThisCollection){
+                const doc = await findByIdNoFallback(payload, collectionSlug, id, config.sourceLocale, {
+                    draft: true
+                });
+                if (doc) docs.push(doc);
+            }
+        } else {
+            // Paginate. Cap at 500 docs per collection to bound the
+            // estimate's wall-clock — the enqueue handler is request-
+            // scoped and a 5000-doc estimate would push past serverless
+            // limits.
+            const maxDocsPerCollection = 500;
+            let page = 1;
+            const limit = 100;
+            while(docs.length < maxDocsPerCollection){
+                const result = await payload.find({
+                    collection: collectionSlug,
+                    page,
+                    limit,
+                    depth: 0,
+                    locale: config.sourceLocale,
+                    overrideAccess: true,
+                    draft: true
+                });
+                docs.push(...result.docs);
+                if (!result.hasNextPage) break;
+                page += 1;
+            }
+        }
+        for (const doc of docs){
+            const units = extractTranslationUnits(doc, translatableFields, excludePatterns, blocksConfig);
+            for (const unit of units){
+                allItems.push({
+                    id: unit.id,
+                    text: unit.text,
+                    kind: unit.kind
+                });
+            }
+            documentCount += 1;
+        }
+    }
+    for (const globalSlug of scope.globals){
+        const globals = payload.config?.globals ?? [];
+        const globalConfig = globals.find((g)=>g.slug === globalSlug);
+        if (!globalConfig) continue;
+        const translatableFields = resolveTranslatableFields(globalConfig.fields);
+        const blocksConfig = collectBlocksConfig(globalConfig.fields);
+        const excludePatterns = await getEffectiveExcludePatternsForSurface(payload, config, globalSlug);
+        let doc;
+        try {
+            doc = await payload.findGlobal({
+                slug: globalSlug,
+                locale: config.sourceLocale,
+                fallbackLocale: null,
+                overrideAccess: true
+            });
+        } catch  {
+            doc = undefined;
+        }
+        if (!doc) continue;
+        const units = extractTranslationUnits(doc, translatableFields, excludePatterns, blocksConfig);
+        for (const unit of units){
+            allItems.push({
+                id: unit.id,
+                text: unit.text,
+                kind: unit.kind
+            });
+        }
+        documentCount += 1;
+    }
+    if (allItems.length === 0) {
+        // No content to translate. Return 0 cost (the batch will land
+        // as `completed` with `totalUnits=0`).
+        return {
+            estimatedCostUsd: 0,
+            documentCount
+        };
+    }
+    const mockRequest = {
+        items: allItems,
+        sourceLocale: config.sourceLocale,
+        targetLocale: scope.locales[0] ?? '',
+        context: {
+            collectionSlug: scope.collections[0] ?? '',
+            fieldPath: '*'
+        }
+    };
+    const estimate = await config.provider.estimate(mockRequest);
+    const totalCost = estimate.estimatedCostUsd !== undefined ? estimate.estimatedCostUsd * Math.max(1, scope.locales.length) : undefined;
+    return {
+        estimatedCostUsd: totalCost,
+        documentCount
+    };
+}
+/**
+ * Decision #5 + F-DA-MODEL-SWAP: pin the active `{provider, model,
+ * sourceLocale}` into the batch row at enqueue. Mid-run admin toggles
+ * must not bisect a batch across configurations.
+ *
+ * Resolution order matches `api.ts:resolveProvider`:
+ *   1. `translation-settings.activeProvider` keyed into `config.providers`
+ *   2. fallback to `config.provider`
+ */ async function snapshotActiveProviderConfig(payload, config) {
+    let providerKey = 'default';
+    let activeProvider = config.provider;
+    if (config.providers && Object.keys(config.providers).length > 0) {
+        const settingsSlug = config.settings?.globalSlug ?? DEFAULT_SETTINGS_GLOBAL_SLUG;
+        try {
+            const settings = await payload.findGlobal({
+                slug: settingsSlug,
+                depth: 0,
+                overrideAccess: true
+            });
+            const active = settings?.activeProvider;
+            if (active && config.providers[active]) {
+                providerKey = active;
+                activeProvider = config.providers[active];
+            }
+        } catch  {
+        // Settings global not present — fall back to default below.
+        }
+    }
+    const modelId = typeof activeProvider.model === 'string' && activeProvider.model.length > 0 ? activeProvider.model : 'unknown';
+    return {
+        providerKey,
+        modelId,
+        sourceLocale: config.sourceLocale
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { PayloadHandler } from 'payload';
+export interface BulkFailuresHandlerOptions {
+    unitsCollectionSlug?: string;
+}
+/**
+ * `GET /api/translation-hub/bulk-translate/:id/failures`
+ *
+ * Paginated drill-down of failed units in a batch. Used by the failure
+ * drawer in the terminal card. Response shape:
+ *   { rows: BulkTranslateFailureRow[], nextCursor: string | null }
+ */
+export declare const getBulkTranslateFailuresHandler: (options?: BulkFailuresHandlerOptions) => PayloadHandler;

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

@@ -0,0 +1,67 @@
+import { DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG } from '../../bulk-translate-units-collection.js';
+import { decodeCursor, encodeCursor, errorResponse, isEditorOrAdmin, unauthorizedResponse } from './_helpers.js';
+import { extractBatchId } from './status.js';
+/**
+ * `GET /api/translation-hub/bulk-translate/:id/failures`
+ *
+ * Paginated drill-down of failed units in a batch. Used by the failure
+ * drawer in the terminal card. Response shape:
+ *   { rows: BulkTranslateFailureRow[], nextCursor: string | null }
+ */ export const getBulkTranslateFailuresHandler = (options = {})=>async (req)=>{
+        const unitsSlug = options.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+        if (!req.user) {
+            return unauthorizedResponse(req);
+        }
+        if (!isEditorOrAdmin(req.user)) {
+            return errorResponse('forbidden', "You don't have permission to view failure details. 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 url = new URL(req.url ?? 'http://localhost');
+        const cursor = url.searchParams.get('cursor') ?? undefined;
+        const limitRaw = url.searchParams.get('limit');
+        let limit = limitRaw ? Number.parseInt(limitRaw, 10) : 25;
+        if (!Number.isFinite(limit) || limit <= 0) limit = 25;
+        if (limit > 100) limit = 100;
+        const offset = decodeCursor(cursor);
+        const page = Math.floor(offset / limit) + 1;
+        const result = await req.payload.find({
+            collection: unitsSlug,
+            where: {
+                and: [
+                    {
+                        batchId: {
+                            equals: batchId
+                        }
+                    },
+                    {
+                        status: {
+                            equals: 'failed'
+                        }
+                    }
+                ]
+            },
+            sort: 'createdAt',
+            page,
+            limit,
+            depth: 0,
+            overrideAccess: true
+        });
+        const rows = result.docs.map((u)=>({
+                unitId: String(u.id),
+                collection: String(u.collection ?? ''),
+                documentId: String(u.documentId ?? ''),
+                documentTitle: null,
+                locale: String(u.locale ?? ''),
+                failureCode: typeof u.failureCode === 'string' ? u.failureCode : null,
+                failureMessage: typeof u.failureMessage === 'string' ? u.failureMessage : '',
+                attempts: Number(u.attempts ?? 0)
+            }));
+        const nextCursor = rows.length === limit ? encodeCursor(offset + limit) : null;
+        return Response.json({
+            rows,
+            nextCursor
+        });
+    };

package/dist/endpoints/translation-hub/force-reset.d.ts

@@ -0,0 +1,20 @@
+import type { PayloadHandler } from 'payload';
+export interface BulkForceResetHandlerOptions {
+    batchesCollectionSlug?: string;
+    unitsCollectionSlug?: string;
+}
+/**
+ * `POST /api/translation-hub/bulk-translate/:id/force-reset`
+ *
+ * Recovery action — F-SEC-CRON-RESET. Marks every `running` unit in
+ * the batch as `failed` with `failureCode: 'transient.crashed'` and
+ * the batch itself as `failed`. Used by on-call when the worker /
+ * coordinator stalled and the normal janitor sweep hasn't picked it
+ * up.
+ *
+ * Auth: admin only — explicitly NO TOTP gate (this is a recovery
+ * action; admins must be able to unblock production without a TOTP
+ * dance if their mobile device is unavailable). The daily USD cap
+ * already enforced spending bounds for the batch in question.
+ */
+export declare const getBulkTranslateForceResetHandler: (options?: BulkForceResetHandlerOptions) => PayloadHandler;