@purposeinplay/payload-ai-translate 0.1.0

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

@@ -0,0 +1,233 @@
+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 { getDrizzle, slugToTable } from '../../lib/bulk-translate-migrations.js';
+import { createScopedLogger } from '../../lib/logger.js';
+import { errorResponse, forbiddenOwnershipResponse, isEditorOrAdmin, ownsBatch, unauthorizedResponse } from './_helpers.js';
+import { extractBatchId } from './status.js';
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+const TERMINAL_STATUSES = new Set([
+    'success',
+    'partial',
+    'failed',
+    'cancelled',
+    'reverted'
+]);
+/**
+ * `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 const getBulkTranslateCancelHandler = (options = {})=>async (req)=>{
+        const batchesSlug = options.batchesCollectionSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+        const unitsSlug = options.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+        const jobsSlug = options.jobsCollectionSlug ?? 'payload-jobs';
+        if (!req.user) {
+            return unauthorizedResponse(req);
+        }
+        if (!isEditorOrAdmin(req.user)) {
+            return errorResponse('forbidden', "You don't have permission to cancel 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);
+        }
+        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.cancel',
+                batchId
+            });
+            log.event('warn', 'hub.cancel.batch-read.failed', {
+                err,
+                endpoint: 'hub.cancel',
+                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 cancel a run they triggered. Admins always
+        // pass (see `ownsBatch`). The check is intentionally AFTER the
+        // not_found case so editors can't probe for the existence of other
+        // editors' batches via 403-vs-404 timing.
+        if (!ownsBatch(req.user, batch)) {
+            return forbiddenOwnershipResponse();
+        }
+        if (TERMINAL_STATUSES.has(batch.status) || batch.status === 'cancelling') {
+            const isCancelling = batch.status === 'cancelling';
+            return errorResponse('invalid_state', isCancelling ? 'This run is already being cancelled — no action needed.' : "This run has already ended — there's nothing to cancel.", 409, {
+                status: batch.status
+            });
+        }
+        // ----- Flip status to cancelling -----
+        try {
+            await req.payload.update({
+                collection: batchesSlug,
+                id: batchId,
+                data: {
+                    status: 'cancelling',
+                    cancelledByUserId: String(req.user.id),
+                    cancelledAt: new Date().toISOString()
+                },
+                overrideAccess: true
+            });
+        } catch (err) {
+            req.payload.logger?.warn?.(`[ai-translate] cancel: failed to mark batch cancelling for ${batchId}: ${err instanceof Error ? err.message : String(err)}`);
+            return errorResponse('cancel_failed', "The run couldn't be cancelled right now. Refresh the page and try again, or contact engineering.", 500);
+        }
+        // ----- Cancel queued payload-jobs rows for this batch -----
+        // We can't be surgical without a jsonb path query (see Spike 2);
+        // instead, we look up the units that are still `pending` (and have
+        // not yet been dequeued) and mark them as `skipped`. The worker
+        // task's first-action terminal-state guard makes any race here
+        // safe — if a worker did dequeue between our read + write, it
+        // sees the unit is no longer `pending` and exits.
+        let cancelledJobs = 0;
+        let inFlightJobs = 0;
+        try {
+            // Fast path: one set-based UPDATE on Postgres. The previous
+            // per-row loop held the HTTP request open for ~15ms × pending
+            // units — on a 10k-unit batch that's ~2.5 minutes, past every
+            // LB timeout, while units claimed mid-loop kept translating.
+            // The single statement is atomic w.r.t. the worker's claim
+            // (claim flips pending→running; whichever lands first wins and
+            // the other side sees a terminal/claimed row and backs off).
+            let sweptInBulk = false;
+            if (/^\d+$/.test(batchId)) {
+                const db = getDrizzle(req.payload);
+                if (db) {
+                    try {
+                        const res = await db.execute(`UPDATE ${slugToTable(unitsSlug)}
+                  SET status = 'skipped',
+                      failure_message = 'cancelled_by_admin',
+                      completed_at = now(),
+                      updated_at = now()
+                WHERE batch_id_id = ${batchId}
+                  AND status = 'pending'`);
+                        cancelledJobs = Number(res?.rowCount ?? 0);
+                        sweptInBulk = true;
+                    } catch (err) {
+                        req.payload.logger?.warn?.(`[ai-translate] cancel: set-based pending sweep failed for batch ${batchId}, falling back to per-row: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+            if (!sweptInBulk) {
+                // Non-Postgres adapters / non-numeric ids: per-row fallback.
+                const pending = await req.payload.find({
+                    collection: unitsSlug,
+                    where: {
+                        and: [
+                            {
+                                batchId: {
+                                    equals: batchId
+                                }
+                            },
+                            {
+                                status: {
+                                    equals: 'pending'
+                                }
+                            }
+                        ]
+                    },
+                    limit: 10_000,
+                    depth: 0,
+                    overrideAccess: true
+                });
+                for (const unit of pending.docs){
+                    try {
+                        await req.payload.update({
+                            collection: unitsSlug,
+                            id: unit.id,
+                            data: {
+                                status: 'skipped',
+                                failureMessage: 'cancelled_by_admin',
+                                completedAt: new Date().toISOString()
+                            },
+                            overrideAccess: true
+                        });
+                        cancelledJobs += 1;
+                    } catch  {
+                    // Per-unit failure — best-effort cancel.
+                    }
+                }
+            }
+            const running = await req.payload.count({
+                collection: unitsSlug,
+                where: {
+                    and: [
+                        {
+                            batchId: {
+                                equals: batchId
+                            }
+                        },
+                        {
+                            status: {
+                                equals: 'running'
+                            }
+                        }
+                    ]
+                },
+                overrideAccess: true
+            });
+            inFlightJobs = running.totalDocs;
+        } catch (err) {
+            req.payload.logger?.warn?.(`[ai-translate] cancel: best-effort unit cleanup failed for batch ${batchId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // v1.2.5: short-circuit batch transition when there are no
+        // in-flight workers. Pre-1.2.5 the batch stayed in `cancelling`
+        // forever in this case — `maybeTransitionBatch` is fired by
+        // workers as they finish, but if 0 workers are running there's
+        // nothing to fire it. The result was a "stuck cancelling" state
+        // that only `/force-reset` could clear. Now we flip directly to
+        // `cancelled` here. When `inFlightJobs > 0` we leave the batch in
+        // `cancelling` and rely on the (now-fixed) `maybeTransitionBatch`
+        // path to flip it once the last in-flight unit lands.
+        if (inFlightJobs === 0) {
+            try {
+                await req.payload.update({
+                    collection: batchesSlug,
+                    id: batchId,
+                    data: {
+                        status: 'cancelled',
+                        completedAt: new Date().toISOString()
+                    },
+                    overrideAccess: true
+                });
+            } catch (err) {
+                // Best-effort. If this fails, the batch stays in `cancelling`
+                // and force-reset is still the manual escape hatch.
+                req.payload.logger?.warn?.(`[ai-translate] cancel: short-circuit batch transition failed for ${batchId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Try (best-effort) to drop queued payload-jobs rows for the
+        // coordinator/worker for this batch. The exact column layout
+        // varies across Payload versions, so we wrap the optional path
+        // in a try.
+        void jobsSlug; // reserved for future use; see comment above.
+        return Response.json({
+            data: {
+                batchId,
+                cancelledJobs,
+                inFlightJobs,
+                status: inFlightJobs === 0 ? 'cancelled' : 'cancelling'
+            }
+        });
+    };

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

@@ -0,0 +1,70 @@
+import type { PayloadHandler } from 'payload';
+import type { AITranslatePluginConfig, BulkTranslateConfig } from '../../types.js';
+export interface BulkEnqueueScope {
+    collections?: string[];
+    globals?: string[];
+    locales?: string[];
+    excludeCollections?: string[];
+    documentIds?: Record<string, string[]>;
+}
+export interface BulkEnqueueBody {
+    scope: BulkEnqueueScope;
+    mode: 'changed' | 'force' | 'canary';
+    canaryLimit?: number;
+    totpCode?: string;
+    triggerReason?: string;
+}
+export interface BulkEnqueueHandlerOptions {
+    /** Slug override for the batches collection. */
+    batchesCollectionSlug?: string;
+    /** Coordinator task slug to enqueue. */
+    coordinatorTaskSlug?: string;
+}
+/**
+ * `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 declare const getBulkTranslateEnqueueHandler: (options?: BulkEnqueueHandlerOptions) => PayloadHandler;
+type ResolvedScope = {
+    collections: string[];
+    globals: string[];
+    locales: string[];
+    excludeCollections: string[];
+    /**
+     * The coordinator's `BulkBatchScope.documentIds` is a flat array
+     * (it only enumerates a single collection in `documents-explicit`
+     * mode). When the caller supplies a per-collection map, we flatten
+     * here AFTER honoring `collections` membership.
+     */
+    documentIdsFlat: string[];
+};
+export declare function resolveScope(scope: BulkEnqueueScope, config: AITranslatePluginConfig, bulk: BulkTranslateConfig): ResolvedScope;
+export type BatchCostEstimate = {
+    estimatedCostUsd: number | undefined;
+    documentCount: number;
+};
+export type BatchEstimateScope = ResolvedScope;
+/**
+ * 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 declare function estimateBatchCost(payload: import('payload').Payload, config: AITranslatePluginConfig, scope: ResolvedScope): Promise<BatchCostEstimate>;
+export {};