@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/bulk-translate-migrations.js

@@ -0,0 +1,153 @@
+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 { DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG } from '../translation-daily-spend-collection.js';
+export async function ensureBulkTranslateSchema(payload, opts = {}) {
+    const unitsSlug = opts.bulkTranslateUnitsSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+    const dailySpendSlug = opts.translationDailySpendSlug ?? DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG;
+    // Convert slug to table name. Payload's Postgres adapter snake-cases
+    // collection slugs into table names: `bulk-translate-units` →
+    // `bulk_translate_units`. If a consumer customizes the slug, the
+    // same transform applies.
+    const unitsTable = slugToTable(unitsSlug);
+    const dailySpendTable = slugToTable(dailySpendSlug);
+    const db = getDrizzle(payload);
+    if (!db) {
+        payload.logger?.warn?.('[ai-translate] ensureBulkTranslateSchema: payload.db.drizzle unavailable. Skipping. ' + 'Hand-write the indexes in your consumer migration if your adapter is not Postgres.');
+        return;
+    }
+    // Partial unique index on bulk-translate-units. The CREATE INDEX
+    // IF NOT EXISTS keyword is Postgres-specific; this helper is
+    // explicitly Postgres-only (per the plugin's existing adapter
+    // assumption in `utilities/helpers.ts:atomicUpdateLastCounter`).
+    const unitsIndexSql = `
+    CREATE UNIQUE INDEX IF NOT EXISTS ${unitsTable}_active_dedup
+      ON ${unitsTable} (collection, document_id, locale)
+      WHERE status IN ('pending','running');
+  `;
+    const dailySpendUniqueSql = `
+    CREATE UNIQUE INDEX IF NOT EXISTS ${dailySpendTable}_date_consumer_uniq
+      ON ${dailySpendTable} (date, consumer_key);
+  `;
+    await runIdempotent(payload, db, unitsIndexSql, `${unitsTable}_active_dedup`);
+    await runIdempotent(payload, db, dailySpendUniqueSql, `${dailySpendTable}_date_consumer_uniq`);
+}
+/**
+ * One-off data migration: prefix existing `ai-translate-meta`
+ * source-hash rows with the `v1:` version tag (R2 / F-ENG-07).
+ *
+ * Without this, the first bulk run after a plugin upgrade would treat
+ * every previously-translated field as "source changed" — burning
+ * tokens to re-translate everything that was already in sync.
+ *
+ * Idempotent: rows that already start with `v1:` are skipped. Safe
+ * to run repeatedly. Consumer should run ONCE per deploy that bumps
+ * past 1.1.16. Returns a count of rows updated.
+ */ export async function migrateHashesToV1Prefix(payload, opts = {}) {
+    const metaSlug = opts.metaSlug ?? 'ai-translate-meta';
+    const metaTable = slugToTable(metaSlug);
+    const db = getDrizzle(payload);
+    if (!db) {
+        throw new Error('[ai-translate] migrateHashesToV1Prefix: payload.db.drizzle unavailable. Non-Postgres adapters must roll their own migration.');
+    }
+    const scanResult = await db.execute(`SELECT count(*) AS count FROM ${metaTable} WHERE last_source_hash IS NOT NULL AND last_source_hash NOT LIKE 'v1:%'`);
+    const needsMigration = Number(scanResult.rows[0]?.count ?? 0);
+    const alreadyResult = await db.execute(`SELECT count(*) AS count FROM ${metaTable} WHERE last_source_hash LIKE 'v1:%'`);
+    const alreadyMigrated = Number(alreadyResult.rows[0]?.count ?? 0);
+    if (opts.dryRun) {
+        return {
+            scanned: needsMigration,
+            updated: 0,
+            alreadyMigrated
+        };
+    }
+    if (needsMigration === 0) {
+        return {
+            scanned: 0,
+            updated: 0,
+            alreadyMigrated
+        };
+    }
+    await db.execute(`UPDATE ${metaTable} SET last_source_hash = 'v1:' || last_source_hash WHERE last_source_hash IS NOT NULL AND last_source_hash NOT LIKE 'v1:%'`);
+    payload.logger?.info?.(`[ai-translate] migrateHashesToV1Prefix: prefixed ${needsMigration} rows; ${alreadyMigrated} already v1.`);
+    return {
+        scanned: needsMigration,
+        updated: needsMigration,
+        alreadyMigrated
+    };
+}
+/**
+ * v1.2.4 data migration: align `bulk_translate_batches.status` vocabulary
+ * on `'success'` (matching the units collection + the
+ * `BulkTranslateBatchStatus` TS union). Pre-1.2.4 the schema declared
+ * `'completed'` as the terminal-success value while the type union used
+ * `'success'`, so badges, filter chips, and the Hub's "recently
+ * terminal" query were all silently dead for successful runs. Worker
+ * + schema now write `'success'`; this helper backfills existing rows.
+ *
+ * Idempotent: only updates rows where status = 'completed'. Safe to run
+ * repeatedly; subsequent calls are no-ops.
+ *
+ * Consumer wiring:
+ *   - Add to a forward migration's up() OR
+ *   - Call from plugin onInit() once per deploy (boot-time self-heal).
+ */ export async function migrateBatchStatusVocabulary(payload, opts = {}) {
+    const batchesSlug = opts.batchesSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+    const batchesTable = slugToTable(batchesSlug);
+    const db = getDrizzle(payload);
+    if (!db) {
+        throw new Error('[ai-translate] migrateBatchStatusVocabulary: payload.db.drizzle unavailable. Non-Postgres adapters must roll their own migration.');
+    }
+    const scanResult = await db.execute(`SELECT count(*) AS count FROM ${batchesTable} WHERE status = 'completed'`);
+    const needs = Number(scanResult.rows[0]?.count ?? 0);
+    const alreadyResult = await db.execute(`SELECT count(*) AS count FROM ${batchesTable} WHERE status = 'success'`);
+    const already = Number(alreadyResult.rows[0]?.count ?? 0);
+    if (opts.dryRun) {
+        return {
+            scanned: needs,
+            updated: 0,
+            alreadyAligned: already
+        };
+    }
+    if (needs === 0) {
+        return {
+            scanned: 0,
+            updated: 0,
+            alreadyAligned: already
+        };
+    }
+    await db.execute(`UPDATE ${batchesTable} SET status = 'success', updated_at = now() WHERE status = 'completed'`);
+    payload.logger?.info?.(`[ai-translate] migrateBatchStatusVocabulary: updated ${needs} rows from 'completed' to 'success'; ${already} already aligned.`);
+    return {
+        scanned: needs,
+        updated: needs,
+        alreadyAligned: already
+    };
+}
+export function slugToTable(slug) {
+    // Match Payload's snake_case table-naming. Slugs are usually
+    // already kebab-case; replace dashes with underscores. Validate
+    // identifier shape to avoid SQL injection via consumer-provided
+    // slug overrides (AUDIT-H-06).
+    if (!/^[a-z][a-z0-9_-]{0,62}$/.test(slug)) {
+        throw new Error(`[ai-translate] slugToTable: invalid collection slug "${slug}" (must match /^[a-z][a-z0-9_-]{0,62}$/)`);
+    }
+    return slug.replace(/-/g, '_');
+}
+export function getDrizzle(payload) {
+    const db = payload.db?.drizzle;
+    if (!db || typeof db.execute !== 'function') return null;
+    return db;
+}
+async function runIdempotent(payload, db, sql, label) {
+    try {
+        await db.execute(sql);
+        payload.logger?.info?.(`[ai-translate] schema: ensured ${label}.`);
+    } catch (err) {
+        // The IF NOT EXISTS guard should prevent most "already exists"
+        // errors, but if the table itself is missing (plugin booting
+        // before consumer ran their initial migrations) this can throw.
+        // Log as warn — boot proceeds, the engine will fail at first
+        // bulk run with a clear error.
+        payload.logger?.warn?.(`[ai-translate] schema: failed to ensure ${label}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/lib/coalescing-queue.d.ts

@@ -0,0 +1,38 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type CoalescingEntry = {
+    payload: Payload;
+    /**
+     * Discriminator so the queue worker dispatches to `translateDocument`
+     * for collections and `translateGlobal` for globals. Defaults to
+     * `'collection'` for backwards compatibility with consumers that
+     * haven't yet started passing globals through this queue.
+     */
+    kind?: 'collection' | 'global';
+    /** Collection slug or global slug, depending on `kind`. */
+    collection: string;
+    id: string | number;
+    doc: Record<string, unknown>;
+    previousDoc: Record<string, unknown>;
+    /**
+     * Optional jobId so the queue worker reuses an already-created progress job
+     * (the after-change hook seeds one for instant UI feedback).
+     */
+    jobId?: string;
+    /** Originating request — threaded into locale writes for audit attribution. */
+    req?: PayloadRequest;
+    /**
+     * Effective locale list for this dispatch — overrides config.targetLocales
+     * downstream. The after-change hook computes this from the
+     * translation-settings global so admin opt-outs are honored. Omitted =
+     * fall back to config.targetLocales in the translate API.
+     */
+    targetLocales?: string[];
+};
+export type CoalescingCallback = (entry: CoalescingEntry) => Promise<void>;
+export type CoalescingQueue = {
+    enqueue(entry: CoalescingEntry): void;
+    cancel(collection: string, id: string | number): void;
+    pending(): number;
+    flush(): Promise<void>;
+};
+export declare function createCoalescingQueue(windowMs: number, callback: CoalescingCallback): CoalescingQueue;

package/dist/lib/coalescing-queue.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+export function createCoalescingQueue(windowMs, callback) {
+    const entries = new Map();
+    function makeKey(collection, id) {
+        // Globals key on `<slug>:<slug>` — same pattern collections use, just
+        // with id == slug since globals are singletons.
+        return `${collection}:${String(id)}`;
+    }
+    async function fire(key) {
+        const pending = entries.get(key);
+        if (!pending) return;
+        entries.delete(key);
+        try {
+            await callback(pending.entry);
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            console.error(`[ai-translate] Coalescing callback failed for ${key}: ${msg}`);
+        }
+    }
+    return {
+        enqueue (entry) {
+            const key = makeKey(entry.collection, entry.id);
+            // Cancel existing pending entry for this key
+            const existing = entries.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                // Keep the original previousDoc so field-diff captures all changes
+                // from the first save, not just the latest delta
+                entry = {
+                    ...entry,
+                    previousDoc: existing.entry.previousDoc
+                };
+            }
+            // Set new timer with updated entry
+            const timer = setTimeout(()=>{
+                void fire(key);
+            }, windowMs);
+            entries.set(key, {
+                entry,
+                timer
+            });
+        },
+        cancel (collection, id) {
+            const key = makeKey(collection, id);
+            const existing = entries.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                entries.delete(key);
+            }
+        },
+        pending () {
+            return entries.size;
+        },
+        async flush () {
+            const keys = [
+                ...entries.keys()
+            ];
+            for (const key of keys){
+                const existing = entries.get(key);
+                if (existing) {
+                    clearTimeout(existing.timer);
+                }
+                await fire(key);
+            }
+        }
+    };
+}

package/dist/lib/content-extractor.d.ts

@@ -0,0 +1,16 @@
+import type { Block, Field } from 'payload';
+import type { TranslatableField, TranslationUnit } from '../types.js';
+/**
+ * Build a `blockType → Block` map from a Payload collection / global's
+ * raw `fields` array. Walks `type: 'blocks'` fields anywhere in the tree
+ * (including under tabs, groups, arrays) and gathers their registered
+ * `blocks: Block[]` configurations.
+ *
+ * The result lets the extractor gate which block-internal keys are
+ * translatable based on the SCHEMA rather than the heuristic
+ * "every-string-is-text" walk that produces false positives for select
+ * values, color codes, etc. (the BUG-04 family).
+ */
+export declare function collectBlocksConfig(fields: Field[]): Map<string, Block>;
+export declare function extractTranslationUnits(doc: Record<string, unknown>, fields: TranslatableField[], excludePatterns: string[], blocksConfig?: Map<string, Block> | null): TranslationUnit[];
+export declare function getValueAtPath(obj: Record<string, unknown>, path: string): unknown;