@purposeinplay/payload-ai-translate 0.1.0

package/dist/endpoints/translate.js

@@ -0,0 +1,376 @@
+import { translateDocument, translateGlobal } from '../api.js';
+import { describeAuthRejection } from '../lib/auth-diagnostics.js';
+import { collectBlocksConfig, extractTranslationUnits } from '../lib/content-extractor.js';
+import { getEffectiveExcludePatternsForSurface, getExcludedFieldPaths, getGlobalKillSwitches, isPathExcluded, isSurfaceDisabledByAdmin } from '../lib/effective-locales.js';
+import { resolveTranslatableFields } from '../lib/field-resolver.js';
+import { findByIdNoFallback } from '../lib/payload-read.js';
+import { createJob, getActiveJobForDoc } from '../lib/progress-store.js';
+function resolveContext(arg, url) {
+    if (typeof arg === 'object' && arg !== null) return arg;
+    // String arg or undefined → derive from URL.
+    // Collection: /api/{slug}/ai-translate
+    // Global: /api/globals/{slug}/ai-translate
+    try {
+        const segments = new URL(url).pathname.split('/').filter(Boolean);
+        const apiIndex = segments.indexOf('api');
+        if (apiIndex >= 0) {
+            if (segments[apiIndex + 1] === 'globals' && segments[apiIndex + 2]) {
+                return {
+                    kind: 'global',
+                    slug: segments[apiIndex + 2]
+                };
+            }
+            if (segments[apiIndex + 1]) {
+                return {
+                    kind: 'collection',
+                    slug: arg ?? segments[apiIndex + 1]
+                };
+            }
+        }
+    } catch  {
+    // fall through
+    }
+    return {
+        kind: 'collection',
+        slug: typeof arg === 'string' ? arg : ''
+    };
+}
+export const getTranslateHandler = (arg)=>async (req)=>{
+        try {
+            if (!req.user) {
+                return Response.json({
+                    error: 'Unauthorized',
+                    diagnostic: describeAuthRejection(req)
+                }, {
+                    status: 401
+                });
+            }
+            const config = req.payload.config?.custom?.aiTranslate;
+            if (config.access?.translate) {
+                const allowed = await config.access.translate({
+                    req
+                });
+                if (!allowed) {
+                    return Response.json({
+                        error: 'Forbidden'
+                    }, {
+                        status: 403
+                    });
+                }
+            }
+            // Plugin-wide manual-translate kill switch (v1.2.8). When admin
+            // flipped `globalManualTranslateEnabled` off, every manual entry
+            // point — Translate dialog AND per-field button — is refused with
+            // a friendly 403. Auto and Bulk are unaffected. The dialog +
+            // button hide themselves in the client based on the same flag in
+            // the client-config response, but the server gate is the source
+            // of truth.
+            const globalKillSwitches = await getGlobalKillSwitches(req.payload, config);
+            if (!globalKillSwitches.manualEnabled) {
+                return Response.json({
+                    error: 'Manual Translate is paused site-wide. An admin can re-enable it in Translation Settings.'
+                }, {
+                    status: 403
+                });
+            }
+            // BUG-08 fix: honor the per-surface `enabled` kill-switch on manual
+            // translate too. Pre-fix this gate was automation-only; editors
+            // could manual-translate a surface the admin had explicitly turned
+            // off. Admins who want "manual yes, auto no" should use the sibling
+            // `autoOnPublish` flag instead, which remains automation-only.
+            const ctxForGate = resolveContext(arg, req.url ?? '');
+            const isDisabled = await isSurfaceDisabledByAdmin(req.payload, config, ctxForGate.slug);
+            if (isDisabled) {
+                return Response.json({
+                    error: 'Translation is turned off for this content type. Ask an admin to enable it in the translation settings.'
+                }, {
+                    status: 403
+                });
+            }
+            let body;
+            try {
+                body = typeof req.json === 'function' ? await req.json() : {};
+            } catch  {
+                return Response.json({
+                    error: 'Invalid JSON body'
+                }, {
+                    status: 400
+                });
+            }
+            const { id, ids, targetLocales, targetPolicy, fields, async: asyncMode, draft: bodyDraft, writeMode, confirmCost } = body;
+            const draft = bodyDraft ?? true;
+            const ctx = resolveContext(arg, req.url ?? '');
+            // Validate caller-supplied target locales against the plugin's
+            // configured `targetLocales`. Without this, an invalid locale code
+            // (e.g. `"xx"` from a typo or a client that ships ahead of config)
+            // still reaches the LLM — the model guesses a language, charges
+            // tokens, and Payload silently drops the write because the locale
+            // isn't registered. Validate up front and 400 instead.
+            if (targetLocales && Array.isArray(targetLocales)) {
+                const allowed = new Set(config.targetLocales);
+                const invalid = targetLocales.filter((l)=>!allowed.has(l));
+                if (invalid.length > 0) {
+                    return Response.json({
+                        error: `Invalid target locale(s): ${invalid.map((l)=>`"${l}"`).join(', ')}. Configured targetLocales: ${config.targetLocales.map((l)=>`"${l}"`).join(', ')}`
+                    }, {
+                        status: 400
+                    });
+                }
+            }
+            const effectiveLocales = targetLocales ?? config.targetLocales;
+            // Cost guard: pre-flight an estimate when the projected work is large
+            // (multi-doc batch, or many locales × one doc). Compares to the
+            // configured `bulkConfirmUsdThreshold` and returns 402 unless the
+            // caller acknowledges with `confirmCost: true`. Per-doc translation
+            // is bounded by `perDocCharCeiling` inside the API; this is the
+            // multi-doc / multi-locale fanout guard that was previously
+            // declared in config but never enforced.
+            if (!confirmCost && ctx.kind === 'collection' && config.provider.estimate) {
+                const isBulk = (ids?.length ?? 0) > 1;
+                const wideFanout = effectiveLocales.length > 3;
+                if (isBulk || wideFanout) {
+                    try {
+                        const estimate = await estimateRequestCost({
+                            req,
+                            config,
+                            ctx,
+                            ids: ids ?? (id !== undefined ? [
+                                id
+                            ] : []),
+                            targetLocales: effectiveLocales,
+                            draft
+                        });
+                        if (estimate.estimatedCostUsd !== undefined && estimate.estimatedCostUsd > config.costLimits.bulkConfirmUsdThreshold) {
+                            return Response.json({
+                                error: 'Estimated cost exceeds bulkConfirmUsdThreshold',
+                                estimate: {
+                                    estimatedCostUsd: estimate.estimatedCostUsd,
+                                    documentCount: estimate.documentCount,
+                                    localeCount: effectiveLocales.length,
+                                    threshold: config.costLimits.bulkConfirmUsdThreshold
+                                },
+                                hint: 'Re-send with `confirmCost: true` to acknowledge and proceed.'
+                            }, {
+                                status: 402
+                            });
+                        }
+                    } catch  {
+                    // Estimate failure shouldn't block translation — fall through
+                    // to the normal path. The provider's per-call limits still
+                    // apply as a backstop.
+                    }
+                }
+            }
+            // Globals don't take id — they're singletons identified by slug.
+            if (ctx.kind === 'global') {
+                if (asyncMode) {
+                    const jobId = createJob(ctx.slug, ctx.slug, effectiveLocales);
+                    // Fire-and-forget. The progress endpoint's SSE stream pushes
+                    // updates as `updateJob` ticks land.
+                    void translateGlobal(req.payload, {
+                        global: ctx.slug,
+                        targetLocales,
+                        targetPolicy,
+                        fields,
+                        req,
+                        jobId,
+                        writeMode
+                    }).catch((err)=>{
+                        req.payload.logger?.error?.(`[ai-translate] Background translateGlobal failed for ${ctx.slug}: ${err instanceof Error ? err.message : 'Unknown error'}`);
+                    });
+                    return Response.json({
+                        results: [
+                            {
+                                jobId,
+                                succeeded: [],
+                                failed: []
+                            }
+                        ]
+                    }, {
+                        status: 202
+                    });
+                }
+                const result = await translateGlobal(req.payload, {
+                    global: ctx.slug,
+                    targetLocales,
+                    targetPolicy,
+                    fields,
+                    req,
+                    writeMode
+                });
+                return Response.json({
+                    results: [
+                        result
+                    ]
+                }, {
+                    status: 200
+                });
+            }
+            if (!id && (!ids || ids.length === 0)) {
+                return Response.json({
+                    error: 'Either "id" or "ids" must be provided'
+                }, {
+                    status: 400
+                });
+            }
+            if (asyncMode && id) {
+                // Coalesce concurrent same-doc async requests: if another
+                // translation is already running for this (collection, id) pair,
+                // return its jobId instead of spawning a second LLM call. The
+                // client can subscribe to the existing job's SSE stream. This
+                // prevents the 2× cost from rapid duplicate clicks of a
+                // per-field translate button or two admins racing on the same
+                // doc.
+                const existing = getActiveJobForDoc(ctx.slug, id);
+                if (existing) {
+                    return Response.json({
+                        results: [
+                            {
+                                jobId: existing.jobId,
+                                succeeded: [],
+                                failed: [],
+                                coalesced: true
+                            }
+                        ]
+                    }, {
+                        status: 202
+                    });
+                }
+                const jobId = createJob(ctx.slug, id, effectiveLocales);
+                void translateDocument(req.payload, {
+                    collection: ctx.slug,
+                    id,
+                    targetLocales,
+                    targetPolicy,
+                    fields,
+                    req,
+                    jobId,
+                    draft,
+                    writeMode
+                }).catch((err)=>{
+                    req.payload.logger?.error?.(`[ai-translate] Background translateDocument failed for ${ctx.slug}/${String(id)}: ${err instanceof Error ? err.message : 'Unknown error'}`);
+                });
+                return Response.json({
+                    results: [
+                        {
+                            jobId,
+                            succeeded: [],
+                            failed: []
+                        }
+                    ]
+                }, {
+                    status: 202
+                });
+            }
+            let results;
+            if (id) {
+                const result = await translateDocument(req.payload, {
+                    collection: ctx.slug,
+                    id,
+                    targetLocales,
+                    targetPolicy,
+                    fields,
+                    req,
+                    draft,
+                    writeMode
+                });
+                results = [
+                    result
+                ];
+            } else {
+                results = await Promise.all(ids.map((docId)=>translateDocument(req.payload, {
+                        collection: ctx.slug,
+                        id: docId,
+                        targetLocales,
+                        targetPolicy,
+                        fields,
+                        req,
+                        draft,
+                        writeMode
+                    })));
+            }
+            return Response.json({
+                results
+            }, {
+                status: 200
+            });
+        } catch (error) {
+            const message = error instanceof Error ? error.message : 'Internal server error';
+            return Response.json({
+                error: message
+            }, {
+                status: 500
+            });
+        }
+    };
+/**
+ * Pre-flight cost estimate used by the `bulkConfirmUsdThreshold` guard.
+ * Mirrors the `/ai-translate/estimate` endpoint's calculation but
+ * inlined to avoid the round-trip — the caller already has a valid
+ * authenticated request, the document IDs, and the configured provider.
+ *
+ * Returns `estimatedCostUsd: undefined` if the provider doesn't
+ * implement `estimate()`. Caller treats `undefined` as "no guard
+ * possible" and proceeds (the per-call / per-doc limits still apply).
+ */ async function estimateRequestCost(params) {
+    const { req, config, ctx, ids, targetLocales, draft } = params;
+    if (ctx.kind !== 'collection') return {
+        estimatedCostUsd: undefined,
+        documentCount: 0
+    };
+    const collections = req.payload.config?.collections ?? [];
+    const collectionConfig = collections.find((c)=>c.slug === ctx.slug);
+    if (!collectionConfig) return {
+        estimatedCostUsd: undefined,
+        documentCount: 0
+    };
+    const collectionFields = collectionConfig.fields;
+    let translatableFields = resolveTranslatableFields(collectionFields);
+    // Admin per-surface exclusions also apply to the internal cost
+    // estimate (bulkConfirmUsdThreshold guard) so the user doesn't get
+    // a confirmation prompt sized against fields that won't actually
+    // be translated.
+    const adminExcludedPaths = await getExcludedFieldPaths(req.payload, config, ctx.slug);
+    if (adminExcludedPaths.size > 0) {
+        translatableFields = translatableFields.filter((f)=>!isPathExcluded(f.path, adminExcludedPaths));
+    }
+    const blocksConfig = collectBlocksConfig(collectionFields);
+    const excludePatterns = await getEffectiveExcludePatternsForSurface(req.payload, config, ctx.slug);
+    const allItems = [];
+    for (const docId of ids){
+        const doc = await findByIdNoFallback(req.payload, ctx.slug, docId, config.sourceLocale, {
+            draft
+        });
+        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
+            });
+        }
+    }
+    if (allItems.length === 0 || !config.provider.estimate) {
+        return {
+            estimatedCostUsd: undefined,
+            documentCount: ids.length
+        };
+    }
+    const mockRequest = {
+        items: allItems,
+        sourceLocale: config.sourceLocale,
+        targetLocale: targetLocales[0] ?? '',
+        context: {
+            collectionSlug: ctx.slug,
+            fieldPath: '*'
+        }
+    };
+    const estimate = await config.provider.estimate(mockRequest);
+    // Multiply by locale count — provider estimates a single locale pass.
+    const totalCost = estimate.estimatedCostUsd !== undefined ? estimate.estimatedCostUsd * targetLocales.length : undefined;
+    return {
+        estimatedCostUsd: totalCost,
+        documentCount: ids.length
+    };
+}

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

@@ -0,0 +1,140 @@
+import type { Payload, PayloadRequest } from 'payload';
+import type { AITranslatePluginConfig, BulkTranslateConfig } from '../../types.js';
+/**
+ * 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 declare function isAdminUser(user: PayloadRequest['user'] | undefined): boolean;
+/**
+ * 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 declare function isEditorOrAdmin(user: PayloadRequest['user'] | undefined): boolean;
+/**
+ * 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 declare function ownsBatch(user: PayloadRequest['user'] | undefined, batch: {
+    triggeredByUserId?: string | number | null;
+} | null | undefined): boolean;
+/**
+ * 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 declare function forbiddenOwnershipResponse(): Response;
+export type ErrorBody = {
+    error: {
+        code: string;
+        message: string;
+        fields?: Record<string, string>;
+    };
+};
+/**
+ * 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 declare function errorResponse(code: string, message: string, status: number, fields?: Record<string, string>): Response;
+/**
+ * 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 declare function unauthorizedResponse(req: PayloadRequest): Response;
+/**
+ * Decision #13 v2 + F-SEC-TOTP-BYPASS: TOTP is friction, not the
+ * primary security boundary. The daily USD cap is the real
+ * enforcement. We validate the supplied code against the TOTP plugin
+ * if one is wired up; if the plugin isn't installed, we log a warn
+ * and skip the check rather than failing closed (the consumer may be
+ * a single-admin setup with no TOTP enrollment).
+ *
+ * Returns `{ ok: true }` when the code is valid OR the plugin isn't
+ * installed AND `requireTotp` was set to `true`. Returns
+ * `{ ok: false, ... }` with a structured reason otherwise.
+ *
+ * The actual TOTP code verification reads the auth-collection's
+ * `totp.secret` (encrypted) + delegates to `verifyTOTPToken`. We
+ * resolve those lazily so the ai-translate plugin doesn't take a
+ * hard dependency on the totp plugin's exports.
+ */
+export type TotpResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: 'missing' | 'invalid' | 'plugin_unavailable';
+    message: string;
+};
+export declare function verifyTotpCode(payload: Payload, userId: string | number, totpCode: string | undefined, options: {
+    required: boolean;
+    allowSkipWhenUnavailable: boolean;
+}): Promise<TotpResult>;
+export declare function getAiTranslateConfig(payload: Payload): AITranslatePluginConfig | undefined;
+export declare function getBulkConfig(payload: Payload): BulkTranslateConfig | undefined;
+/**
+ * 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 declare function readJsonBody<T>(req: PayloadRequest): Promise<{
+    ok: true;
+    body: T;
+} | {
+    ok: false;
+    res: Response;
+}>;
+/**
+ * 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 declare function encodeCursor(offset: number): string;
+export declare function decodeCursor(cursor: string | undefined): number;
+/**
+ * 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 declare function writeBulkAuditEntry(payload: Payload, params: {
+    userId: string | number;
+    userEmail?: string;
+    action: string;
+    batchId: string;
+    metadata?: Record<string, unknown>;
+}): Promise<void>;