@purposeinplay/payload-ai-translate 0.1.0

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

@@ -0,0 +1,297 @@
+import { describeAuthRejection } from '../../lib/auth-diagnostics.js';
+// ---------------------------------------------------------------------------
+// Auth helpers
+// ---------------------------------------------------------------------------
+/**
+ * Pre-1.2.8: every translation-hub endpoint was admin-only (Decision
+ * #31). v1.2.8 opens trigger + read endpoints to editor-role users so
+ * content editors can run bulk translation without needing an admin
+ * to fire it for them. Admin-only access is preserved for
+ * configuration / cost-limit / force-reset surfaces; per-batch
+ * mutations (cancel / retry / revert) are gated by `ownsBatch` so
+ * one editor cannot disrupt another's run.
+ *
+ * Defaults to checking for the literal `'admin'` role. Consumers using
+ * a different role naming convention should wrap this in their plugin
+ * config's `bulk.requireTotp`/audit-role surfaces; the surface here
+ * intentionally stays narrow.
+ */ export function isAdminUser(user) {
+    if (!user) return false;
+    const roles = user?.roles;
+    if (!Array.isArray(roles)) return false;
+    return roles.includes('admin');
+}
+/**
+ * Returns `true` for admin OR editor roles. Used by the editor-open
+ * endpoints (enqueue / active / status / preflight / list / failures)
+ * — the per-batch mutation endpoints layer `ownsBatch` on top of this.
+ *
+ * `editor` is the conventional role name for content editors across
+ * the wild-payload-cms-style consumers; consumers using a different
+ * role naming convention should add the synonym to the membership
+ * list rather than re-implementing the check.
+ */ export function isEditorOrAdmin(user) {
+    if (!user) return false;
+    const roles = user?.roles;
+    if (!Array.isArray(roles)) return false;
+    return roles.includes('admin') || roles.includes('editor');
+}
+/**
+ * Ownership check for per-batch mutations (cancel / retry-failed /
+ * revert). Admins always pass — they own the world. Editors must be
+ * the user who triggered the batch (matched on `triggeredByUserId`).
+ *
+ * The batch record may carry `triggeredByUserId` as either `string`
+ * (the canonical persisted form — see `enqueue.ts:266`) or `number`
+ * depending on the auth collection's id type. Compare stringified to
+ * sidestep that.
+ */ export function ownsBatch(user, batch) {
+    if (!user || !batch) return false;
+    if (isAdminUser(user)) return true;
+    const userId = user?.id;
+    if (userId == null || batch.triggeredByUserId == null) return false;
+    return String(userId) === String(batch.triggeredByUserId);
+}
+/**
+ * Structured 403 for "you can do this kind of action, but not on
+ * THIS batch (you didn't trigger it)". Distinct from the 401
+ * `unauthorizedResponse` (cookie / CSRF failure) and from the 403
+ * we'd return for an editor hitting an admin-only endpoint — the
+ * `code` lets the UI render the right copy.
+ */ export function forbiddenOwnershipResponse() {
+    return Response.json({
+        error: {
+            code: 'forbidden_ownership',
+            message: 'You can only modify bulk runs you started. Ask the editor who triggered this run, or contact an admin.'
+        }
+    }, {
+        status: 403
+    });
+}
+/**
+ * Structured error JSON used across the translation-hub endpoints.
+ * Mirrors the shape an `api-designer` would draft for a public API —
+ * `code` is the stable machine-readable identifier (UI surfaces
+ * key off it), `message` is human-readable, `fields` carries per-
+ * field validation hints when relevant.
+ */ export function errorResponse(code, message, status, fields) {
+    const body = {
+        error: fields ? {
+            code,
+            message,
+            fields
+        } : {
+            code,
+            message
+        }
+    };
+    return Response.json(body, {
+        status
+    });
+}
+/**
+ * Structured 401 with a `diagnostic` field naming why auth was rejected —
+ * almost always a CSRF allowlist mismatch when the page was opened via the
+ * `Network:` URL Next prints in dev. Without this, the response is a
+ * silent "Unauthorized" and the next investigator wastes 30 min on JWTs.
+ */ export function unauthorizedResponse(req) {
+    const diagnostic = describeAuthRejection(req);
+    return Response.json({
+        error: {
+            code: 'unauthorized',
+            message: 'Authentication required.',
+            diagnostic
+        }
+    }, {
+        status: 401
+    });
+}
+export async function verifyTotpCode(payload, userId, totpCode, options) {
+    if (!options.required) {
+        return {
+            ok: true
+        };
+    }
+    if (!totpCode || typeof totpCode !== 'string' || totpCode.length === 0) {
+        return {
+            ok: false,
+            code: 'missing',
+            message: 'An authentication code is required. Enter the 6-digit code from your authenticator app.'
+        };
+    }
+    // Lazy import — totp plugin may not be installed in the consumer's
+    // app. If the dynamic import fails (or the module shape changes),
+    // we treat it as plugin_unavailable.
+    let verifyFn = ()=>({
+            valid: false
+        });
+    let decryptFn = (s)=>s;
+    try {
+        // Use a string variable to make the import path opaque to the
+        // bundler — the plugin must remain optional at install time.
+        const totpCrypto = '../../../../totp/crypto/totp';
+        const cryptoMod = await import(totpCrypto);
+        const helpers = '../../../../totp/utilities/helpers';
+        const helpersMod = await import(helpers);
+        if (typeof cryptoMod.verifyTOTPToken !== 'function' || typeof helpersMod.decryptSecret !== 'function' || typeof helpersMod.isTOTPEncryptionConfigured !== 'function' || !helpersMod.isTOTPEncryptionConfigured()) {
+            throw new Error('totp_unavailable');
+        }
+        verifyFn = cryptoMod.verifyTOTPToken;
+        decryptFn = helpersMod.decryptSecret;
+    } catch  {
+        payload.logger?.warn?.('[ai-translate] bulk-translate: TOTP plugin not detected; skipping TOTP check (requireTotp was true).');
+        return options.allowSkipWhenUnavailable ? {
+            ok: true
+        } : {
+            ok: false,
+            code: 'plugin_unavailable',
+            message: "Two-factor authentication is required but isn't available in this environment. Contact engineering."
+        };
+    }
+    // Look up the user's TOTP secret. The auth collection slug varies
+    // per consumer — read it from payload.config (Payload exposes
+    // `config.admin.user` as the auth collection slug).
+    const authSlug = payload.config.admin?.user ?? 'users';
+    let user;
+    try {
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+        user = await payload.findByID({
+            collection: authSlug,
+            id: userId,
+            overrideAccess: true
+        });
+    } catch  {
+        user = undefined;
+    }
+    const totpField = user?.totp ?? undefined;
+    if (!totpField?.enabled || typeof totpField.secret !== 'string') {
+        return {
+            ok: false,
+            code: 'plugin_unavailable',
+            message: "Two-factor authentication isn't set up for your account. Go to Account → Security to enrol your authenticator app."
+        };
+    }
+    let plainSecret;
+    try {
+        plainSecret = decryptFn(totpField.secret);
+    } catch  {
+        return {
+            ok: false,
+            code: 'plugin_unavailable',
+            message: 'Your two-factor authentication setup is unreadable on the server. Contact engineering.'
+        };
+    }
+    const result = verifyFn(plainSecret, totpCode, totpField.lastCounter);
+    if (!result.valid) {
+        return {
+            ok: false,
+            code: 'invalid',
+            message: 'The authentication code was incorrect. Check your authenticator app and try again.'
+        };
+    }
+    return {
+        ok: true
+    };
+}
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+export function getAiTranslateConfig(payload) {
+    return payload.config?.custom?.aiTranslate;
+}
+export function getBulkConfig(payload) {
+    const cfg = getAiTranslateConfig(payload);
+    return cfg?.bulk;
+}
+// ---------------------------------------------------------------------------
+// Body parsing
+// ---------------------------------------------------------------------------
+/**
+ * Reads a JSON body using the same `req.json()` pattern existing
+ * handlers in this directory rely on. Returns either the parsed body
+ * or an `errorResponse` Response object so the handler can `return`
+ * it directly.
+ *
+ * Returning a Response (instead of throwing) keeps the handler
+ * flat — no try/catch around an awaited body read at every call
+ * site.
+ */ export async function readJsonBody(req) {
+    try {
+        if (typeof req.json !== 'function') {
+            return {
+                ok: true,
+                body: {}
+            };
+        }
+        const body = await req.json();
+        return {
+            ok: true,
+            body: body ?? {}
+        };
+    } catch  {
+        return {
+            ok: false,
+            res: errorResponse('invalid_json', 'Invalid JSON body', 400)
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Pagination cursor — opaque base64 of `{ offset: number }`
+// ---------------------------------------------------------------------------
+/**
+ * The status endpoint paginates unit drill-down via opaque cursors.
+ * The internal representation is `{ offset }` — base64-encoded so
+ * clients can't poke at it and depend on internal shape. Cheap and
+ * stable; switching to a row-id cursor later is a non-breaking change
+ * because the surface is opaque.
+ */ export function encodeCursor(offset) {
+    return Buffer.from(JSON.stringify({
+        offset
+    }), 'utf-8').toString('base64');
+}
+export function decodeCursor(cursor) {
+    if (!cursor) return 0;
+    try {
+        const raw = Buffer.from(cursor, 'base64').toString('utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.offset === 'number' && Number.isFinite(parsed.offset) && parsed.offset >= 0) {
+            return Math.floor(parsed.offset);
+        }
+    } catch  {
+    // fall through
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Audit-log entry (best-effort)
+// ---------------------------------------------------------------------------
+/**
+ * Decision #33 mandates an audit-log entry on revert. We don't take a
+ * hard dependency on `auditLogPlugin` — instead we write directly to
+ * the audit-logs collection if it exists. Best-effort: failures are
+ * logged but don't abort the action.
+ */ export async function writeBulkAuditEntry(payload, params) {
+    const collections = payload.config?.collections ?? [];
+    const auditSlug = collections.find((c)=>c.slug === 'audit-logs')?.slug;
+    if (!auditSlug) return;
+    try {
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+        await payload.create({
+            collection: auditSlug,
+            data: {
+                authorEmail: params.userEmail ?? String(params.userId),
+                action: params.action,
+                type: 'audit',
+                source: 'bulk-translate',
+                collectionSlug: 'bulk-translate-batches',
+                documentId: params.batchId,
+                documentTitle: `bulk-translate-${params.batchId}`,
+                user: params.userId,
+                changes: params.metadata ?? null
+            },
+            overrideAccess: true
+        });
+    } catch (err) {
+        payload.logger?.warn?.(`[ai-translate] bulk-translate: audit-log write failed for ${params.action} on batch ${params.batchId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { PayloadHandler } from 'payload';
+export interface BulkActiveHandlerOptions {
+    batchesCollectionSlug?: string;
+    unitsCollectionSlug?: string;
+    /**
+     * Window after a batch's `completedAt` during which the terminal card
+     * still shows on the Hub. Defaults to 24 hours, mirroring Decision #28.
+     */
+    terminalVisibilityMs?: number;
+}
+/**
+ * `GET /api/translation-hub/bulk-translate/active`
+ *
+ * Returns the most relevant batch for the Hub: an in-flight batch
+ * (queued / running / cancelling) takes precedence; otherwise we
+ * return the most recently-terminal batch within the 24h visibility
+ * window so the operator can review or revert it.
+ *
+ * Response shape: `{ batch: BulkTranslateBatchSummary | null }`.
+ */
+export declare const getBulkTranslateActiveHandler: (options?: BulkActiveHandlerOptions) => PayloadHandler;

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

@@ -0,0 +1,220 @@
+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 { computeLiveBatchCount } from '../../lib/batch-counts.js';
+import { getDrizzle, slugToTable } from '../../lib/bulk-translate-migrations.js';
+import { createScopedLogger } from '../../lib/logger.js';
+import { errorResponse, isEditorOrAdmin, unauthorizedResponse } from './_helpers.js';
+const DEFAULT_TERMINAL_VISIBILITY_MS = 24 * 60 * 60 * 1000;
+/**
+ * `GET /api/translation-hub/bulk-translate/active`
+ *
+ * Returns the most relevant batch for the Hub: an in-flight batch
+ * (queued / running / cancelling) takes precedence; otherwise we
+ * return the most recently-terminal batch within the 24h visibility
+ * window so the operator can review or revert it.
+ *
+ * Response shape: `{ batch: BulkTranslateBatchSummary | null }`.
+ */ export const getBulkTranslateActiveHandler = (options = {})=>async (req)=>{
+        const batchesSlug = options.batchesCollectionSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+        const unitsSlug = options.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+        const visibilityMs = options.terminalVisibilityMs ?? DEFAULT_TERMINAL_VISIBILITY_MS;
+        if (!req.user) {
+            return unauthorizedResponse(req);
+        }
+        if (!isEditorOrAdmin(req.user)) {
+            return errorResponse('forbidden', "You don't have permission to view bulk-translation status. Contact an admin.", 403);
+        }
+        // Prefer the most recent active batch. Active here = anything that
+        // isn't terminal — a single tenant typically only has one in flight
+        // (the coordinator's lease lock enforces this), so the limit=1 sort
+        // is enough.
+        let active;
+        try {
+            const result = await req.payload.find({
+                collection: batchesSlug,
+                where: {
+                    status: {
+                        in: [
+                            'queued',
+                            'running',
+                            'cancelling'
+                        ]
+                    }
+                },
+                sort: '-enqueuedAt',
+                limit: 1,
+                depth: 0,
+                overrideAccess: true
+            });
+            active = result.docs[0];
+        } catch (err) {
+            const log = createScopedLogger(req.payload, {
+                component: 'hub.active'
+            });
+            log.event('warn', 'hub.active.batch-read.failed', {
+                err,
+                endpoint: 'hub.active',
+                phase: 'in-flight'
+            });
+            active = undefined;
+        }
+        // No active batch — look for the most recent terminal batch within
+        // the visibility window so the operator can still see / revert it.
+        let chosen = active;
+        if (!chosen) {
+            const cutoff = new Date(Date.now() - visibilityMs).toISOString();
+            try {
+                const result = await req.payload.find({
+                    collection: batchesSlug,
+                    where: {
+                        and: [
+                            {
+                                status: {
+                                    in: [
+                                        'success',
+                                        'failed',
+                                        'partial',
+                                        'reverted',
+                                        'cancelled'
+                                    ]
+                                }
+                            },
+                            {
+                                completedAt: {
+                                    greater_than: cutoff
+                                }
+                            }
+                        ]
+                    },
+                    sort: '-completedAt',
+                    limit: 1,
+                    depth: 0,
+                    overrideAccess: true
+                });
+                chosen = result.docs[0];
+            } catch (err) {
+                const log = createScopedLogger(req.payload, {
+                    component: 'hub.active'
+                });
+                log.event('warn', 'hub.active.batch-read.failed', {
+                    err,
+                    endpoint: 'hub.active',
+                    phase: 'terminal-window'
+                });
+                chosen = undefined;
+            }
+        }
+        if (!chosen) {
+            return Response.json({
+                batch: null
+            });
+        }
+        const collections = await aggregateCollectionsBreakdown(req.payload, unitsSlug, String(chosen.id));
+        // Live counts — bypass cached `completedUnits` / `failedUnits` on
+        // the batch row which drift on retries. See `lib/batch-counts.ts`.
+        const live = await computeLiveBatchCount(req.payload, unitsSlug, String(chosen.id));
+        const completedAtMs = chosen.completedAt ? Date.parse(chosen.completedAt) : null;
+        const revertExpiresAt = completedAtMs !== null ? new Date(completedAtMs + visibilityMs).toISOString() : null;
+        return Response.json({
+            batch: {
+                id: String(chosen.id),
+                status: chosen.status,
+                mode: chosen.mode,
+                totalUnits: live.total > 0 ? live.total : Number(chosen.totalUnits ?? 0),
+                completedUnits: live.completed,
+                failedUnits: live.failed,
+                estimatedCostUsd: chosen.estimatedCostUsd !== undefined ? Number(chosen.estimatedCostUsd) : undefined,
+                actualCostUsd: chosen.actualCostUsd !== undefined ? Number(chosen.actualCostUsd) : undefined,
+                createdAt: chosen.createdAt ?? chosen.enqueuedAt ?? new Date(0).toISOString(),
+                startedAt: chosen.startedAt ?? null,
+                completedAt: chosen.completedAt ?? null,
+                etaSeconds: null,
+                collections,
+                revertExpiresAt,
+                revertedAt: chosen.revertedAt ?? null,
+                triggeredByEmail: chosen.triggeredByEmail ?? null,
+                // 1.2.8: editor-facing chip needs the raw user id to compare
+                // against the viewer's id and decide whether to say "Your bulk
+                // run" or "Bulk run by alice@…".
+                triggeredByUserId: chosen.triggeredByUserId != null ? String(chosen.triggeredByUserId) : null
+            }
+        });
+    };
+/**
+ * Per-collection progress for the in-flight monitor. We aggregate by
+ * counting unit rows per `collection` value; the labels are echoed
+ * back as the slug since the endpoint has no view of collection
+ * `labels` (the UI maps slug → human label client-side).
+ */ async function aggregateCollectionsBreakdown(payload, unitsSlug, batchId) {
+    const buckets = new Map();
+    const tally = (slug, status, n)=>{
+        if (!slug) return;
+        const bucket = buckets.get(slug) ?? {
+            total: 0,
+            completed: 0,
+            failed: 0
+        };
+        bucket.total += n;
+        if (status === 'success') bucket.completed += n;
+        if (status === 'failed') bucket.failed += n;
+        buckets.set(slug, bucket);
+    };
+    // Fast path: GROUP BY on Postgres. This endpoint is polled every 5s
+    // by every open Hub tab — and (terminal-visibility) for a full 24h
+    // after a run completes. The previous fetch-all pulled every unit
+    // row INCLUDING the `pre_run_snapshot` jsonb on each poll; on prod-
+    // sized batches that alone was seconds of DB + JSON.parse work per
+    // poll (2026-06-10 outage amplifier).
+    let aggregated = false;
+    if (/^\d+$/.test(batchId)) {
+        const db = getDrizzle(payload);
+        if (db) {
+            try {
+                const res = await db.execute(`SELECT collection, status, count(*) AS n
+             FROM ${slugToTable(unitsSlug)}
+            WHERE batch_id_id = ${batchId}
+            GROUP BY 1, 2`);
+                for (const row of res?.rows ?? []){
+                    tally(String(row.collection ?? ''), String(row.status ?? ''), Number(row.n ?? 0));
+                }
+                aggregated = true;
+            } catch (err) {
+                payload.logger?.warn?.(`[ai-translate] active: grouped breakdown SQL failed, falling back to row scan: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (!aggregated) {
+        // Fallback: projected row scan — (collection, status) only, so the
+        // snapshot jsonb never leaves the database.
+        let page = 1;
+        // eslint-disable-next-line no-constant-condition
+        while(true){
+            const result = await payload.find({
+                collection: unitsSlug,
+                where: {
+                    batchId: {
+                        equals: batchId
+                    }
+                },
+                page,
+                limit: 5000,
+                depth: 0,
+                select: {
+                    collection: true,
+                    status: true
+                },
+                overrideAccess: true
+            });
+            for (const row of result.docs){
+                tally(String(row.collection ?? ''), String(row.status ?? ''), 1);
+            }
+            if (!result.hasNextPage) break;
+            page += 1;
+        }
+    }
+    return Array.from(buckets.entries()).map(([slug, b])=>({
+            slug,
+            label: slug,
+            ...b
+        }));
+}

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

@@ -0,0 +1,22 @@
+import type { PayloadHandler } from 'payload';
+export interface BulkCancelHandlerOptions {
+    batchesCollectionSlug?: string;
+    unitsCollectionSlug?: string;
+    /** Payload jobs collection slug. Default `'payload-jobs'`. */
+    jobsCollectionSlug?: string;
+}
+/**
+ * `POST /api/translation-hub/bulk-translate/:id/cancel`
+ *
+ * Transitions a queued/running batch to `cancelling`. The coordinator
+ * and worker tasks honor the new status at their next checkpoint
+ * (coordinator reads `batch.status` at the top of every tick; worker
+ * reads at terminal write). In-flight LLM calls finish naturally —
+ * we don't try to interrupt them mid-stream.
+ *
+ * Queued payload-jobs rows for this batch are best-effort cancelled
+ * here (we update them to a terminal state so the runner skips them).
+ * Some Payload versions expose a jobs API for this; we fall back to a
+ * direct update on the queued rows when the API isn't available.
+ */
+export declare const getBulkTranslateCancelHandler: (options?: BulkCancelHandlerOptions) => PayloadHandler;