@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/events.js

@@ -0,0 +1,146 @@
+import { ALERTS_CONTEXT_FLAG, REENTRY_FLAG } from '../defaults.js';
+import { createScopedLogger } from './logger.js';
+/**
+ * Module-scoped payload reference for alert persistence. Set via
+ * `setAlertsContext` from the plugin's `onInit` (post-config-build,
+ * when `payload` is live). When null, `emitAlert` skips DB persistence
+ * but still fires the consumer's `onAlert` callback.
+ *
+ * `payload` carries an optional `logger` (pino) so we can emit
+ * structured "alerts about alerts failing" — without it, persistence
+ * failures swallow silently (Grafana blindness).
+ */ let alertsContext = null;
+export function setAlertsContext(ctx) {
+    alertsContext = ctx;
+}
+export function emitEvent(config, event) {
+    if (!config.onEvent) {
+        return;
+    }
+    try {
+        const result = config.onEvent(event);
+        if (result && typeof result.catch === 'function') {
+            result.catch((err)=>{
+                logEventsFailure('events.emit.failed', err, {
+                    eventType: event.type,
+                    phase: 'onEvent.async'
+                });
+            });
+        }
+    } catch (err) {
+        // Swallow — event emission never breaks the main flow.
+        // But surface to pino so Grafana sees consumer callbacks failing.
+        logEventsFailure('events.emit.failed', err, {
+            eventType: event.type,
+            phase: 'onEvent.sync'
+        });
+    }
+}
+/**
+ * Best-effort structured log for events/alerts-pipeline failures. The
+ * pipeline cannot break the main translation flow; the trade-off is
+ * that swallowed failures used to be invisible. Routes through the
+ * module-scoped alerts context's payload when set; otherwise falls
+ * back to `console.warn` so dev environments without `onInit` still
+ * see the signal.
+ */ function logEventsFailure(eventName, err, fields) {
+    if (alertsContext?.payload?.logger) {
+        const log = createScopedLogger(alertsContext.payload, {
+            component: 'events'
+        });
+        log.event('warn', eventName, {
+            err,
+            ...fields
+        });
+        return;
+    }
+    // No payload logger available (pre-onInit, or consumer mock). Last-
+    // resort visibility — better than the previous silent swallow.
+    // eslint-disable-next-line no-console
+    console.warn(`[ai-translate] ${eventName}`, {
+        err,
+        ...fields
+    });
+}
+/**
+ * Best-effort alert persistence + consumer callback. Two outputs:
+ *
+ *   1. Persists a row to `translation-alerts` collection when the
+ *      plugin's alertsContext is set (auto-registered when
+ *      `usageTracking.enabled`). Lets the Hub surface alerts in-app.
+ *   2. Calls the consumer's `onAlert` callback if set (back-compat —
+ *      pre-1.1.15 consumers wired this to Slack/email).
+ *
+ * Neither path can break the main translation flow — both are wrapped
+ * in best-effort try/catch with no propagation.
+ */ export function emitAlert(config, alert) {
+    // Persistence path. Doesn't depend on consumer config.
+    if (alertsContext) {
+        const ctx = alertsContext;
+        void (async ()=>{
+            try {
+                // Merge `code` + `context` (1.2.5+) into the metadata JSON
+                // column. AlertBanner reads them back via `metadata.code` /
+                // `metadata.context` and renders via `editorMessageFor()`.
+                // Pre-1.2.5 alerts without these fields fall back to the
+                // raw `message` string.
+                const baseMetadata = alert.metadata ?? null;
+                const mergedMetadata = alert.code || alert.context ? {
+                    ...baseMetadata ?? {},
+                    ...alert.code ? {
+                        code: alert.code
+                    } : {},
+                    ...alert.context ? {
+                        context: alert.context
+                    } : {}
+                } : baseMetadata;
+                await ctx.payload.create({
+                    collection: ctx.collectionSlug,
+                    data: {
+                        alertType: alert.type.replace(/^translation\./, ''),
+                        message: alert.message,
+                        collection: alert.collection ?? null,
+                        documentId: alert.documentId != null ? String(alert.documentId) : null,
+                        metadata: mergedMetadata,
+                        dismissed: false
+                    },
+                    context: {
+                        [ALERTS_CONTEXT_FLAG]: true,
+                        [REENTRY_FLAG]: true
+                    },
+                    overrideAccess: true
+                });
+            } catch (err) {
+                // Best-effort. Persistence failure cannot break the consumer's
+                // `onAlert` callback (which may be the primary alerting channel,
+                // e.g. wired to PagerDuty). But surface as a structured pino
+                // event so Grafana sees the "alerts about alerts failing".
+                logEventsFailure('events.emit.failed', err, {
+                    alertType: alert.type,
+                    phase: 'persistence'
+                });
+            }
+        })();
+    }
+    // Consumer callback path. Unchanged from pre-1.1.15.
+    if (!config.onAlert) {
+        return;
+    }
+    try {
+        const result = config.onAlert(alert);
+        if (result && typeof result.catch === 'function') {
+            result.catch((err)=>{
+                logEventsFailure('events.emit.failed', err, {
+                    alertType: alert.type,
+                    phase: 'onAlert.async'
+                });
+            });
+        }
+    } catch (err) {
+        // Swallow — alert emission never breaks the main flow.
+        logEventsFailure('events.emit.failed', err, {
+            alertType: alert.type,
+            phase: 'onAlert.sync'
+        });
+    }
+}

package/dist/lib/exclude-fields.d.ts

@@ -0,0 +1,3 @@
+import type { AITranslatePluginConfig } from '../types.js';
+export declare function getEffectiveExcludePatterns(config: Pick<AITranslatePluginConfig, 'excludeFields' | 'excludeUrlFields'>): string[];
+export declare function isExcluded(fieldPath: string, patterns: string[]): boolean;

package/dist/lib/exclude-fields.js

@@ -0,0 +1,64 @@
+/**
+ * Effective exclude patterns: user-supplied `excludeFields` plus defaults:
+ * - `**.url` — URL fields trip the verbatim-echo validator and waste tokens;
+ *   disable via `excludeUrlFields: false` for rare locale-specific deep links.
+ * - JSON-LD `@`-prefixed keys (`**.@type`, `**.@context`, `**.@id`, `**.@graph`)
+ *   — schema.org constants that consumers parse as identifiers; translating
+ *   `"Article"` to `"Artikel"` breaks structured-data interpretation. These
+ *   are unconditionally excluded because translating them is never correct.
+ *   Pattern matching uses literal `@` so `**.@type` matches paths ending in
+ *   `.@type` only.
+ */ const JSON_LD_RESERVED_PATTERNS = [
+    '**.@type',
+    '**.@context',
+    '**.@id',
+    '**.@graph',
+    '**.@vocab'
+];
+export function getEffectiveExcludePatterns(config) {
+    const user = config.excludeFields ?? [];
+    const patterns = [
+        ...user
+    ];
+    if (config.excludeUrlFields !== false && !user.includes('**.url')) {
+        // `**.url` matches any path ending in `.url` — link.url, hero.cta.url, etc.
+        patterns.push('**.url');
+    }
+    for (const reserved of JSON_LD_RESERVED_PATTERNS){
+        if (!patterns.includes(reserved)) patterns.push(reserved);
+    }
+    return patterns;
+}
+function matchesPattern(fieldPath, pattern) {
+    if (pattern === fieldPath) {
+        return true;
+    }
+    // Contains wildcard: '**.visibility.**' matches any path containing '.visibility.'.
+    // Must run before the prefix-only and suffix-only branches because those
+    // would otherwise claim a pattern like `**.x.**` (which starts with `**.`)
+    // before the contains-wildcard check ever runs.
+    if (pattern.startsWith('**.') && pattern.endsWith('.**')) {
+        const middle = pattern.slice(3, -3);
+        if (middle.length === 0) return true; // `**.**` matches anything
+        return fieldPath === middle || fieldPath.startsWith(middle + '.') || fieldPath.endsWith('.' + middle) || fieldPath.includes('.' + middle + '.');
+    }
+    // Suffix wildcard: 'visibility.**' matches 'visibility.auth', 'visibility.x.y'
+    if (pattern.endsWith('.**')) {
+        const prefix = pattern.slice(0, -3);
+        return fieldPath === prefix || fieldPath.startsWith(prefix + '.');
+    }
+    // Prefix wildcard: '**.visibility' matches 'content.0.visibility', 'x.y.visibility'
+    if (pattern.startsWith('**.')) {
+        const suffix = pattern.slice(3);
+        return fieldPath === suffix || fieldPath.endsWith('.' + suffix);
+    }
+    const patternParts = pattern.split('.');
+    const fieldParts = fieldPath.split('.');
+    if (patternParts.length !== fieldParts.length) {
+        return false;
+    }
+    return patternParts.every((part, i)=>part === '*' || part === fieldParts[i]);
+}
+export function isExcluded(fieldPath, patterns) {
+    return patterns.some((pattern)=>matchesPattern(fieldPath, pattern));
+}

package/dist/lib/field-breadcrumb.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resolve a dotted Payload field path into a human-readable breadcrumb.
+ *
+ * Example:
+ *   path  = "sidebar.featured_sidebar_items.3.label"
+ *   field = SiteNavigation tabs config
+ *   → ["Sidebar Navigation", "Featured Sidebar Items", "#4", "Label"]
+ *
+ * The Translation Hub renders soft-skipped field paths to editors who
+ * don't think in dotted-paths — they think in "Sidebar Navigation ›
+ * Featured Items › Item #4 › Label." This helper walks the field config
+ * matching each path segment to either a `name`, a numeric array index,
+ * or a tab name; falls back to titleizing the raw segment when the
+ * config doesn't match (older row paths, deleted fields, etc).
+ *
+ * Pure function, no side effects, no I/O. Tested in isolation against
+ * synthetic Payload configs that cover tabs/groups/arrays/rows/blocks.
+ */
+export type FieldBreadcrumbInput = {
+    /** Dotted field path, e.g. "sidebar.featured_sidebar_items.3.label" */
+    path: string;
+    /** Top-level field config from the collection or global */
+    fields: ReadonlyArray<unknown>;
+};
+/**
+ * Returns the resolved breadcrumb segments. Falls back to titleized
+ * raw segments for any part of the path that doesn't resolve, so the
+ * renderer can always show something. Numeric segments resolve to
+ * `#N` (1-based for editor familiarity).
+ */
+export declare function resolveFieldBreadcrumb(input: FieldBreadcrumbInput): string[];

package/dist/lib/field-breadcrumb.js

@@ -0,0 +1,227 @@
+/**
+ * Resolve a dotted Payload field path into a human-readable breadcrumb.
+ *
+ * Example:
+ *   path  = "sidebar.featured_sidebar_items.3.label"
+ *   field = SiteNavigation tabs config
+ *   → ["Sidebar Navigation", "Featured Sidebar Items", "#4", "Label"]
+ *
+ * The Translation Hub renders soft-skipped field paths to editors who
+ * don't think in dotted-paths — they think in "Sidebar Navigation ›
+ * Featured Items › Item #4 › Label." This helper walks the field config
+ * matching each path segment to either a `name`, a numeric array index,
+ * or a tab name; falls back to titleizing the raw segment when the
+ * config doesn't match (older row paths, deleted fields, etc).
+ *
+ * Pure function, no side effects, no I/O. Tested in isolation against
+ * synthetic Payload configs that cover tabs/groups/arrays/rows/blocks.
+ */ // ---------------------------------------------------------------------------
+// Minimal local field-config shape
+// ---------------------------------------------------------------------------
+/**
+ * Returns the resolved breadcrumb segments. Falls back to titleized
+ * raw segments for any part of the path that doesn't resolve, so the
+ * renderer can always show something. Numeric segments resolve to
+ * `#N` (1-based for editor familiarity).
+ */ export function resolveFieldBreadcrumb(input) {
+    const { path, fields } = input;
+    if (!path) {
+        return [];
+    }
+    const parts = path.split('.');
+    const fieldArray = fields;
+    const result = walk(parts, 0, fieldArray, []);
+    return result.length > 0 ? result : [
+        titleize(path)
+    ];
+}
+// ---------------------------------------------------------------------------
+// Walker
+// ---------------------------------------------------------------------------
+function walk(parts, index, fields, acc) {
+    if (index >= parts.length) {
+        return [
+            ...acc
+        ];
+    }
+    const part = parts[index];
+    // Numeric segment with no resolver context → render as `#N`. The
+    // array case below normally consumes the index after matching the
+    // array field, so reaching this branch means the path advanced into
+    // a block-typed array (which is unresolvable statically) or stale
+    // data — render the index without trying to descend further.
+    if (/^\d+$/.test(part)) {
+        const indexNum = Number(part);
+        return walk(parts, index + 1, fields, [
+            ...acc,
+            `#${indexNum + 1}`
+        ]);
+    }
+    if (!fields || fields.length === 0) {
+        const remaining = parts.slice(index).map(humanSegment);
+        return [
+            ...acc,
+            ...remaining
+        ];
+    }
+    const match = findInScope(fields, part);
+    if (!match) {
+        const remaining = parts.slice(index).map(humanSegment);
+        return [
+            ...acc,
+            ...remaining
+        ];
+    }
+    // Prepend any tab labels we crossed to reach the match
+    const acc2 = [
+        ...acc,
+        ...match.tabLabels.map((t)=>labelOf(t.label, t.name))
+    ];
+    const field = match.field;
+    const fieldLabel = labelOf(field.label, field.name);
+    switch(field.type){
+        case 'array':
+            {
+                const next = [
+                    ...acc2,
+                    fieldLabel
+                ];
+                const idxPart = parts[index + 1];
+                if (idxPart !== undefined && /^\d+$/.test(idxPart)) {
+                    const idxNum = Number(idxPart);
+                    return walk(parts, index + 2, field.fields, [
+                        ...next,
+                        `#${idxNum + 1}`
+                    ]);
+                }
+                return walk(parts, index + 1, field.fields, next);
+            }
+        case 'group':
+            {
+                const next = [
+                    ...acc2,
+                    fieldLabel
+                ];
+                return walk(parts, index + 1, field.fields, next);
+            }
+        case 'blocks':
+            {
+                const next = [
+                    ...acc2,
+                    fieldLabel
+                ];
+                const idxPart = parts[index + 1];
+                if (idxPart !== undefined && /^\d+$/.test(idxPart)) {
+                    const idxNum = Number(idxPart);
+                    const tail = parts.slice(index + 2).map(humanSegment);
+                    return [
+                        ...next,
+                        `#${idxNum + 1}`,
+                        ...tail
+                    ];
+                }
+                return walk(parts, index + 1, undefined, next);
+            }
+        default:
+            {
+                const next = [
+                    ...acc2,
+                    fieldLabel
+                ];
+                const remaining = parts.slice(index + 1).map(humanSegment);
+                return [
+                    ...next,
+                    ...remaining
+                ];
+            }
+    }
+}
+/**
+ * Find a named field within `fields`, transparently descending into
+ * `tabs`, `row`, and `collapsible` containers (which don't add a path
+ * segment). Returns the tab(s) crossed so the renderer can show
+ * "<TabLabel> › <Field>".
+ */ function findInScope(fields, name) {
+    for (const f of fields){
+        if (isNamedField(f) && f.name === name) {
+            return {
+                field: f,
+                tabLabels: []
+            };
+        }
+    }
+    for (const f of fields){
+        if (f.type === 'tabs' && f.tabs) {
+            for (const tab of f.tabs){
+                // Named tabs (`{ name: 'sidebar', fields: [...] }`) namespace
+                // their children under the tab name — so a path segment matching
+                // a tab name is the segment itself, not a child of an unnamed
+                // container. Treat the tab like a group: return a synthetic
+                // group field that the walker descends into.
+                if (tab.name === name) {
+                    return {
+                        field: {
+                            type: 'group',
+                            name: tab.name,
+                            label: tab.label,
+                            fields: tab.fields
+                        },
+                        tabLabels: []
+                    };
+                }
+                const inside = tab.fields ?? [];
+                const inner = findInScope(inside, name);
+                if (inner) {
+                    // Unnamed tab (`{ label: 'Foo', fields: [...] }`) — its
+                    // children appear at the parent scope with no namespace, so
+                    // the tab's label is prepended to the breadcrumb.
+                    return {
+                        field: inner.field,
+                        tabLabels: tab.name ? inner.tabLabels : [
+                            {
+                                name: tab.name,
+                                label: tab.label
+                            },
+                            ...inner.tabLabels
+                        ]
+                    };
+                }
+            }
+        }
+        if ((f.type === 'row' || f.type === 'collapsible') && f.fields) {
+            const inner = findInScope(f.fields, name);
+            if (inner) {
+                return inner;
+            }
+        }
+    }
+    return undefined;
+}
+function isNamedField(f) {
+    return typeof f.name === 'string';
+}
+// ---------------------------------------------------------------------------
+// Label resolution
+// ---------------------------------------------------------------------------
+function labelOf(label, name) {
+    if (typeof label === 'string') {
+        return label;
+    }
+    if (label && typeof label === 'object') {
+        const first = Object.values(label).find((v)=>typeof v === 'string');
+        if (first) return first;
+    }
+    if (name) {
+        return titleize(name);
+    }
+    return '';
+}
+function humanSegment(s) {
+    if (/^\d+$/.test(s)) {
+        return `#${Number(s) + 1}`;
+    }
+    return titleize(s);
+}
+function titleize(s) {
+    return s.split(/[_-]/).map((w)=>w.length === 0 ? '' : w[0].toUpperCase() + w.slice(1)).join(' ');
+}

package/dist/lib/field-diff.d.ts

@@ -0,0 +1 @@
+export declare function diffFields(previousDoc: Record<string, unknown>, currentDoc: Record<string, unknown>, fieldPaths: string[]): string[];

package/dist/lib/field-diff.js

@@ -0,0 +1,25 @@
+import { hashFieldContent } from './content-hash.js';
+function resolvePathValue(obj, path) {
+    const segments = path.split('.');
+    let current = obj;
+    for (const segment of segments){
+        if (current == null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+export function diffFields(previousDoc, currentDoc, fieldPaths) {
+    const changed = [];
+    for (const path of fieldPaths){
+        const prevValue = resolvePathValue(previousDoc, path);
+        const currValue = resolvePathValue(currentDoc, path);
+        const prevHash = hashFieldContent(prevValue);
+        const currHash = hashFieldContent(currValue);
+        if (prevHash !== currHash) {
+            changed.push(path);
+        }
+    }
+    return changed;
+}

package/dist/lib/field-empty.d.ts

@@ -0,0 +1,2 @@
+import type { TranslatableFieldType } from '../types.js';
+export declare function isFieldEmpty(value: unknown, fieldType: TranslatableFieldType): boolean;

package/dist/lib/field-empty.js

@@ -0,0 +1,68 @@
+function isTextEmpty(value) {
+    return value == null || typeof value === 'string' && value.trim() === '';
+}
+function isRichTextEmpty(value) {
+    if (value == null || typeof value !== 'object') {
+        return true;
+    }
+    const doc = value;
+    if (!doc.root || typeof doc.root !== 'object') {
+        return true;
+    }
+    const root = doc.root;
+    const children = root.children;
+    if (!Array.isArray(children) || children.length === 0) {
+        return true;
+    }
+    return children.every((child)=>{
+        if (child == null || typeof child !== 'object') {
+            return true;
+        }
+        const node = child;
+        const nodeChildren = node.children;
+        if (!Array.isArray(nodeChildren) || nodeChildren.length === 0) {
+            return true;
+        }
+        return nodeChildren.every((textNode)=>{
+            if (textNode == null || typeof textNode !== 'object') {
+                return true;
+            }
+            const tn = textNode;
+            return typeof tn.text === 'string' && tn.text.trim() === '';
+        });
+    });
+}
+function isArrayOrBlocksEmpty(value) {
+    if (value == null) {
+        return true;
+    }
+    if (!Array.isArray(value)) {
+        return true;
+    }
+    return value.length === 0;
+}
+function isGroupEmpty(value) {
+    if (value == null) {
+        return true;
+    }
+    if (typeof value !== 'object') {
+        return true;
+    }
+    return Object.values(value).every((v)=>v == null);
+}
+export function isFieldEmpty(value, fieldType) {
+    switch(fieldType){
+        case 'text':
+        case 'textarea':
+            return isTextEmpty(value);
+        case 'richText':
+            return isRichTextEmpty(value);
+        case 'array':
+        case 'blocks':
+            return isArrayOrBlocksEmpty(value);
+        case 'group':
+            return isGroupEmpty(value);
+        case 'json':
+            return isGroupEmpty(value);
+    }
+}

package/dist/lib/field-resolver.d.ts

@@ -0,0 +1,3 @@
+import type { Field } from 'payload';
+import type { TranslatableField } from '../types.js';
+export declare function resolveTranslatableFields(fields: Field[], parentPath?: string, inheritedLocalized?: boolean): TranslatableField[];