@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/locale-row-check.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Check whether a given doc has any per-locale row in
+ * `<collection>_locales` for the target locale.
+ *
+ * Why this exists: Payload's `findByIdNoFallback(locale: X)` returns
+ * source-locale field values for SHARED parent tables (block parents,
+ * array parents) when the target locale has no row in `<col>_locales`.
+ * Downstream code in the translate flow then treats those source-fallback
+ * values as "real target data," merges translations on top, and writes
+ * them back with the source-locale row IDs — colliding with the source's
+ * own rows in the shared parent tables (PK violation surfacing as
+ * "Value must be unique: id" on the page-level update).
+ *
+ * The fix path: before merging, probe `<collection>_locales` directly
+ * via the pg pool. If zero rows for (parent=docId, locale=targetLocale),
+ * force the merge to take the "fresh target" branch so it strips array
+ * row ids and lets Payload generate fresh ones for the new locale.
+ *
+ * Postgres-only — Payload's other adapter (mongodb) handles this
+ * differently and doesn't hit the same race. Returns `true` (assume
+ * row exists) on non-Postgres or on any error so we never block a
+ * translation that would otherwise succeed.
+ */
+import type { Payload } from 'payload';
+/**
+ * Probe `<collection>_locales` for (parent=documentId, _locale=locale).
+ * Returns `true` when at least one row exists, `false` when zero rows,
+ * and `true` (defensive) when the check can't run.
+ */
+export declare function checkLocaleRowExists(payload: Payload, collection: string, documentId: string | number, locale: string): Promise<boolean>;

package/dist/lib/locale-row-check.js

@@ -0,0 +1,64 @@
+/**
+ * Check whether a given doc has any per-locale row in
+ * `<collection>_locales` for the target locale.
+ *
+ * Why this exists: Payload's `findByIdNoFallback(locale: X)` returns
+ * source-locale field values for SHARED parent tables (block parents,
+ * array parents) when the target locale has no row in `<col>_locales`.
+ * Downstream code in the translate flow then treats those source-fallback
+ * values as "real target data," merges translations on top, and writes
+ * them back with the source-locale row IDs — colliding with the source's
+ * own rows in the shared parent tables (PK violation surfacing as
+ * "Value must be unique: id" on the page-level update).
+ *
+ * The fix path: before merging, probe `<collection>_locales` directly
+ * via the pg pool. If zero rows for (parent=docId, locale=targetLocale),
+ * force the merge to take the "fresh target" branch so it strips array
+ * row ids and lets Payload generate fresh ones for the new locale.
+ *
+ * Postgres-only — Payload's other adapter (mongodb) handles this
+ * differently and doesn't hit the same race. Returns `true` (assume
+ * row exists) on non-Postgres or on any error so we never block a
+ * translation that would otherwise succeed.
+ */ /**
+ * Probe `<collection>_locales` for (parent=documentId, _locale=locale).
+ * Returns `true` when at least one row exists, `false` when zero rows,
+ * and `true` (defensive) when the check can't run.
+ */ export async function checkLocaleRowExists(payload, collection, documentId, locale) {
+    const dbHandle = payload.db;
+    const pool = dbHandle?.pool;
+    if (!pool || typeof pool.connect !== 'function') {
+        // Non-Postgres or no pool — fall back to "assume present" so we
+        // don't block writes. The id-collision bug this guards against is
+        // Postgres-specific anyway.
+        return true;
+    }
+    // Sanitize the table name. Payload's collection slug → table name
+    // conversion replaces `-` with `_`; same here. Single underscore-only
+    // alphanumeric guard prevents injection even though we control all
+    // call sites today.
+    const tableBase = collection.replace(/-/g, '_');
+    if (!/^[a-zA-Z0-9_]+$/.test(tableBase)) {
+        return true;
+    }
+    const localesTable = `${tableBase}_locales`;
+    let client;
+    try {
+        client = await pool.connect();
+        const res = await client.query(// `_locale` is the per-locale row's discriminator column;
+        // `_parent_id` joins back to the parent doc.
+        `SELECT 1 FROM "${localesTable}" WHERE "_parent_id" = $1 AND "_locale" = $2 LIMIT 1`, [
+            documentId,
+            locale
+        ]);
+        return res.rows.length > 0;
+    } catch (err) {
+        // Table doesn't exist (no localized fields at all), pool failure,
+        // SQL error — any of these should not block a translate. Return
+        // `true` so the merge uses its existing targetValue branch.
+        payload.logger?.debug?.(`[ai-translate] checkLocaleRowExists(${collection}, ${String(documentId)}, ${locale}) probe failed (assuming present): ${String(err)}`);
+        return true;
+    } finally{
+        if (client) client.release();
+    }
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Structured logger wrapper around `payload.logger` (pino). Emits every
+ * line as `(object, msg)` so transports / Grafana can index fields like
+ * `event`, `batchId`, `err.name`, `err.cause.name`. The plugin previously
+ * used the `(msg)` form everywhere, throwing structure away.
+ *
+ * Usage:
+ *
+ *   const log = createScopedLogger(payload, {
+ *     component: 'bulk.worker', batchId, unitId,
+ *   });
+ *   log.event('error', 'bulk.worker.unit.failed', { err, durationMs });
+ *
+ * Levels:
+ *   - error: terminal failure, batch → failed, audit-write failed
+ *   - warn:  transient retry, fallback / degradation, unknown classifier
+ *   - info:  lifecycle (unit start/end, batch transition, provider resolved)
+ *   - debug: per-retry state, per-unit heartbeat
+ */
+import type { Payload } from 'payload';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogContext {
+    module?: string;
+    component?: string;
+    batchId?: string | number;
+    unitId?: string | number;
+    jobId?: string | number;
+    collection?: string;
+    documentId?: string | number;
+    locale?: string;
+    provider?: string;
+    model?: string;
+    [key: string]: unknown;
+}
+export interface LogEventFields {
+    err?: unknown;
+    durationMs?: number;
+    attempt?: number;
+    maxAttempts?: number;
+    failureCode?: string;
+    [key: string]: unknown;
+}
+export interface ScopedLogger {
+    event(level: LogLevel, eventName: string, fields?: LogEventFields): void;
+    child(extraContext: LogContext): ScopedLogger;
+}
+interface PinoLikeLogger {
+    debug?: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+}
+type PayloadLike = Pick<Payload, 'logger'> | {
+    logger?: PinoLikeLogger;
+};
+export declare function createScopedLogger(payload: PayloadLike, context?: LogContext): ScopedLogger;
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+    status?: number;
+    body?: unknown;
+    cause?: SerializedError;
+    [key: string]: unknown;
+}
+/**
+ * Recursively serialise an error-like value. Captures `name`, `message`,
+ * `stack`, `cause`, plus any extra enumerable own properties (HTTP-client
+ * errors typically expose `status`, `body`, `code`). Mirrors pino's
+ * default `err` serializer so Grafana queries on `err.cause.status` work.
+ */
+export declare function serializeErr(err: unknown): SerializedError | undefined;
+export {};

package/dist/lib/logger.js

@@ -0,0 +1,97 @@
+/**
+ * Structured logger wrapper around `payload.logger` (pino). Emits every
+ * line as `(object, msg)` so transports / Grafana can index fields like
+ * `event`, `batchId`, `err.name`, `err.cause.name`. The plugin previously
+ * used the `(msg)` form everywhere, throwing structure away.
+ *
+ * Usage:
+ *
+ *   const log = createScopedLogger(payload, {
+ *     component: 'bulk.worker', batchId, unitId,
+ *   });
+ *   log.event('error', 'bulk.worker.unit.failed', { err, durationMs });
+ *
+ * Levels:
+ *   - error: terminal failure, batch → failed, audit-write failed
+ *   - warn:  transient retry, fallback / degradation, unknown classifier
+ *   - info:  lifecycle (unit start/end, batch transition, provider resolved)
+ *   - debug: per-retry state, per-unit heartbeat
+ */ export function createScopedLogger(payload, context = {}) {
+    const baseContext = {
+        module: 'ai-translate',
+        ...context
+    };
+    function emit(level, eventName, fields) {
+        const logger = payload.logger;
+        if (!logger) return;
+        const fn = logger[level];
+        if (typeof fn !== 'function') return;
+        const merged = {
+            event: eventName,
+            ...baseContext
+        };
+        if (fields) {
+            for (const [k, v] of Object.entries(fields)){
+                if (k === 'err') {
+                    const serialized = serializeErr(v);
+                    if (serialized) merged.err = serialized;
+                } else if (v !== undefined) {
+                    merged[k] = v;
+                }
+            }
+        }
+        try {
+            fn.call(logger, merged, eventName);
+        } catch  {
+        // Logger itself failed; nothing recoverable.
+        }
+    }
+    return {
+        event (level, eventName, fields) {
+            emit(level, eventName, fields);
+        },
+        child (extraContext) {
+            return createScopedLogger(payload, {
+                ...baseContext,
+                ...extraContext
+            });
+        }
+    };
+}
+/**
+ * Recursively serialise an error-like value. Captures `name`, `message`,
+ * `stack`, `cause`, plus any extra enumerable own properties (HTTP-client
+ * errors typically expose `status`, `body`, `code`). Mirrors pino's
+ * default `err` serializer so Grafana queries on `err.cause.status` work.
+ */ export function serializeErr(err) {
+    if (err == null) return undefined;
+    if (err instanceof Error) {
+        const out = {
+            name: err.name,
+            message: err.message
+        };
+        if (err.stack) out.stack = err.stack;
+        for (const key of Object.keys(err)){
+            if (key === 'name' || key === 'message' || key === 'stack' || key === 'cause') {
+                continue;
+            }
+            out[key] = err[key];
+        }
+        const cause = err.cause;
+        if (cause != null) {
+            out.cause = serializeErr(cause);
+        }
+        return out;
+    }
+    if (typeof err === 'object') {
+        return {
+            name: 'NonError',
+            message: 'Non-Error thrown',
+            ...err
+        };
+    }
+    return {
+        name: 'NonError',
+        message: String(err)
+    };
+}

package/dist/lib/manual-edit-guard.d.ts

@@ -0,0 +1,128 @@
+import type { Payload, PayloadRequest } from 'payload';
+/**
+ * SHA-1 of a stable JSON serialization of a value. Used to fingerprint
+ * field values for the `preserveManualEdits` feature so we can detect
+ * when a target locale row has drifted from the last plugin-written
+ * shape.
+ *
+ * Stable serialization: object keys sorted, undefined dropped. Same
+ * value → same hash across processes / machines.
+ */
+export declare function hashFieldValue(value: unknown): string;
+/**
+ * Fetch every (fieldPath → lastWrittenHash) row for one
+ * (collection, documentId, locale) tuple. Used by the writer before
+ * issuing the locale-update so it can filter out fields that have
+ * drifted from the stored hash.
+ */
+export declare function loadFieldHashes(payload: Payload, metaCollection: string, collection: string, documentId: string | number, locale: string): Promise<Map<string, string>>;
+/**
+ * Inspect the current target doc and decide which top-level fields in
+ * `writeData` would overwrite a manually edited value. Returns the set
+ * of field names to DROP from `writeData` before issuing the update.
+ *
+ * Detection: for each top-level field path that has a stored hash, if
+ * the current target value's hash differs from the stored one, the
+ * field has been edited since the plugin's last write — skip it.
+ */
+export declare function pickManualEditedFields(writeData: Record<string, unknown>, targetDoc: Record<string, unknown> | null | undefined, storedHashes: Map<string, string>): {
+    fieldsToDrop: string[];
+    skipReasons: Map<string, string>;
+};
+/**
+ * Upsert per-field hashes after a successful locale write. One row per
+ * (collection, documentId, locale, fieldPath). Best-effort — failures
+ * here do NOT roll back the translation, they just mean the next write
+ * can't detect divergence for that field.
+ *
+ * `sourceValues` (BUG-21): map of `fieldPath → source value at time of
+ * write`. When provided, the upsert also stores `lastSourceHash` so the
+ * next translate can compare current-source-hash to stored-source-hash
+ * and skip the LLM call entirely if both source AND target are
+ * unchanged. Omitted when source values aren't available (rare).
+ */
+export declare function recordFieldHashes(payload: Payload, metaCollection: string, collection: string, documentId: string | number, locale: string, writeData: Record<string, unknown>, sourceValues?: Record<string, unknown>, 
+/**
+ * Optional request context to thread into the inner find/update/create
+ * calls. When the caller wraps the locale-write in a fresh transaction,
+ * passing the same `req` here keeps the bookkeeping rows on the same
+ * connection lifecycle. Omit for ad-hoc / out-of-band invocations.
+ */
+req?: PayloadRequest): Promise<{
+    written: number;
+    failed: number;
+}>;
+/**
+ * Fetch every `(fieldPath → { writtenHash, sourceHash })` row for one
+ * (collection, documentId, locale) tuple. Variant of `loadFieldHashes`
+ * that also returns the BUG-21 source hash so the LLM-skip check can
+ * compare current source content to what was translated last time.
+ *
+ * Returns an empty map on read failure (caller treats as "no prior data,
+ * proceed with full translate"). Rows pre-BUG-21 have `sourceHash:
+ * undefined` — those are treated as "can't safely skip; run translate."
+ */
+export declare function loadFieldHashesWithSource(payload: Payload, metaCollection: string, collection: string, documentId: string | number, locale: string): Promise<Map<string, {
+    writtenHash: string;
+    sourceHash?: string;
+}>>;
+import type { FieldLocaleResult, TranslationUnit } from '../types.js';
+/**
+ * Result of a hash-skip preflight.
+ *   - `remainingUnits`: units the caller should still send to the LLM.
+ *   - `hashSkipped`: synthetic FieldLocaleResults to add to the success
+ *     bucket so the per-field event stream and counters reflect that
+ *     these fields were processed (just not via the LLM).
+ */
+export type HashSkipResult = {
+    remainingUnits: TranslationUnit[];
+    hashSkipped: FieldLocaleResult[];
+};
+/**
+ * Read stored source+target hashes for `(surfaceSlug, documentId,
+ * targetLocale)`, compare against current source + target, and remove
+ * units whose top-level field is unchanged on both sides. Returns the
+ * remaining units the caller still needs to translate plus synthetic
+ * `status: 'success'` results for the skipped units (characterCount = 0,
+ * durationMs = 0 — these are the "fieldsHashSkipped" rows in usage).
+ *
+ * Surface-agnostic: pass a `loadTargetDoc` closure so callers can supply
+ * `findByIdNoFallback(payload, collection, docId, locale)` for collections
+ * or `findGlobalNoFallback(payload, globalSlug, locale)` for globals.
+ *
+ * Wrapped in try/catch internally — best-effort optimization, never throws.
+ */
+export declare function applyHashSkip(args: {
+    payload: Payload;
+    metaCollection: string;
+    surfaceSlug: string;
+    documentId: string | number;
+    targetLocale: string;
+    units: TranslationUnit[];
+    sourceDoc: Record<string, unknown>;
+    loadTargetDoc: () => Promise<Record<string, unknown> | null>;
+}): Promise<HashSkipResult>;
+/**
+ * Persist per-field source+target hashes after a successful locale
+ * write. Surface-agnostic — `surfaceSlug` is the collection slug for
+ * collection writes, or the global slug for global writes (matching the
+ * existing `bulk-translate` persist contract).
+ *
+ * Builds the `sourceValues` map from `sourceDoc` for exactly the fields
+ * in `writeData`, then defers to `recordFieldHashes`. Wraps the call so
+ * upstream errors are logged via the payload logger but never re-thrown
+ * — translation succeeded already, bookkeeping failure shouldn't surface
+ * to the editor.
+ */
+export declare function recordHashesAfterWrite(args: {
+    payload: Payload;
+    metaCollection: string;
+    surfaceSlug: string;
+    documentId: string | number;
+    targetLocale: string;
+    writeData: Record<string, unknown>;
+    sourceDoc: Record<string, unknown>;
+}): Promise<{
+    written: number;
+    failed: number;
+}>;