@focus-reactive/payload-plugin-translator 0.8.2 → 0.9.1

package/dist/server/modules/auto-translate/AutoTranslateEnqueue.hook.d.ts

@@ -0,0 +1,39 @@
+import type { CollectionAfterChangeHook } from "payload";
+import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
+import type { TaskRunnerFactory } from "../task-runner";
+import type { AutoTranslatePolicyResolver, NormalizedAutoTranslatePolicy } from "./AutoTranslate.policy";
+import type { AutoTranslateManagedConfig } from "./AutoTranslate.shapes";
+type AutoTranslateHookDeps = {
+    resolvePolicy: AutoTranslatePolicyResolver;
+    schemaMap: CollectionSchemaMap;
+    taskRunnerFactory: TaskRunnerFactory;
+};
+/**
+ * Build the `afterChange` hook that auto-enqueues translations when a document's source-locale content
+ * changes. Thin orchestration only — every decision lives in `AutoTranslate.policy.ts` or the core
+ * drift predicate. Best-effort by contract: any failure is logged and swallowed, never failing the
+ * editor's save.
+ *
+ * Order (cheap guards first): (1) skip the translator's own writes via the `req.context` flag;
+ * (2) resolve the policy — off ⇒ skip; (3) resolve the source locale (per-collection override else
+ * `localization.defaultLocale`) — unresolved ⇒ log + skip; (4) skip non-source-locale writes (the
+ * pipeline's target writes never match); (5) publish-gate (D8); (6) drift-gate (D3); then enqueue one
+ * job per target locale.
+ */
+export declare function makeAutoTranslateHook(deps: AutoTranslateHookDeps): CollectionAfterChangeHook;
+/**
+ * Attach the auto-translate hook to every enabled collection on `config`, appending to any
+ * consumer-supplied `afterChange` array. Idempotent: a collection that already carries the marked hook
+ * is skipped, so a repeated `init()` never stacks duplicates.
+ */
+export declare function injectAutoTranslateHook(config: AutoTranslateManagedConfig, enabledSlugs: Set<string>, hook: CollectionAfterChangeHook): void;
+/**
+ * Propagate each enabled collection's resolved policy onto the REGISTERED collection's `custom` bag, so
+ * the admin UI can read the opt-in back via `getAutoTranslateConfig`. This is required because
+ * `withAutoTranslate` stamps `custom` on the object passed to the plugin's `collections` param, which
+ * can be a DIFFERENT object than the one registered in `buildConfig.collections` (the reader would
+ * otherwise see no config and the indicator would disagree with the behaviour). Idempotent + additive:
+ * re-stamping the same value is a no-op and the behaviour wiring still reads from the plugin param.
+ */
+export declare function propagateAutoTranslateCustom(config: AutoTranslateManagedConfig, enabledSlugs: Set<string>, policies: Map<string, NormalizedAutoTranslatePolicy>): void;
+export {};

package/dist/server/modules/auto-translate/AutoTranslateEnqueue.hook.js

@@ -0,0 +1,94 @@
+import { hasSourceContentChanged } from "../../../core/domain/auto-translate";
+import { AUTO_TRANSLATE_CUSTOM_KEY } from "../../../core/domain/auto-translate";
+import { AUTO_TRANSLATE_SKIP_CONTEXT_KEY } from "../../../types/AutoTranslateContext";
+import { buildAutoTranslateTasks, passesPublishGate } from "./AutoTranslate.policy";
+/**
+ * Build the `afterChange` hook that auto-enqueues translations when a document's source-locale content
+ * changes. Thin orchestration only — every decision lives in `AutoTranslate.policy.ts` or the core
+ * drift predicate. Best-effort by contract: any failure is logged and swallowed, never failing the
+ * editor's save.
+ *
+ * Order (cheap guards first): (1) skip the translator's own writes via the `req.context` flag;
+ * (2) resolve the policy — off ⇒ skip; (3) resolve the source locale (per-collection override else
+ * `localization.defaultLocale`) — unresolved ⇒ log + skip; (4) skip non-source-locale writes (the
+ * pipeline's target writes never match); (5) publish-gate (D8); (6) drift-gate (D3); then enqueue one
+ * job per target locale.
+ */ export function makeAutoTranslateHook(deps) {
+    const { resolvePolicy, schemaMap, taskRunnerFactory } = deps;
+    const hook = async ({ doc, previousDoc, req, collection })=>{
+        try {
+            if (req.context?.[AUTO_TRANSLATE_SKIP_CONTEXT_KEY]) return doc;
+            const policy = resolvePolicy(collection.slug, doc);
+            if (!policy) return doc;
+            const localization = req.payload.config.localization;
+            const sourceLocale = policy.sourceLocale ?? (localization ? localization.defaultLocale : undefined);
+            if (!sourceLocale) {
+                req.payload.logger.warn({
+                    collection: collection.slug,
+                    documentId: String(doc.id),
+                    msg: "translator: auto-translate skipped — no source locale resolvable (set localization.defaultLocale or a per-collection sourceLocale)"
+                });
+                return doc;
+            }
+            if (req.locale !== sourceLocale) return doc;
+            const hasDrafts = Boolean(collection.versions && collection.versions.drafts);
+            if (!passesPublishGate(doc, hasDrafts)) return doc;
+            const schema = schemaMap.get(collection.slug);
+            if (schema && !hasSourceContentChanged(previousDoc, doc, schema)) return doc;
+            const tasks = buildAutoTranslateTasks({
+                policy,
+                collectionSlug: collection.slug,
+                documentId: String(doc.id),
+                sourceLocale,
+                doc,
+                hasDrafts,
+                now: Date.now()
+            });
+            if (tasks.length === 0) return doc;
+            await taskRunnerFactory.create(req.payload).enqueue(tasks);
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                collection: collection.slug,
+                documentId: String(doc.id),
+                msg: "translator: auto-translate hook failed"
+            });
+        }
+        return doc;
+    };
+    hook.__translatorAutoTranslate = true;
+    return hook;
+}
+/**
+ * Attach the auto-translate hook to every enabled collection on `config`, appending to any
+ * consumer-supplied `afterChange` array. Idempotent: a collection that already carries the marked hook
+ * is skipped, so a repeated `init()` never stacks duplicates.
+ */ export function injectAutoTranslateHook(config, enabledSlugs, hook) {
+    for (const collection of config.collections ?? []){
+        if (!enabledSlugs.has(collection.slug)) continue;
+        collection.hooks ??= {};
+        collection.hooks.afterChange ??= [];
+        const alreadyInjected = collection.hooks.afterChange.some((existing)=>existing.__translatorAutoTranslate === true);
+        if (!alreadyInjected) collection.hooks.afterChange.push(hook);
+    }
+}
+/**
+ * Propagate each enabled collection's resolved policy onto the REGISTERED collection's `custom` bag, so
+ * the admin UI can read the opt-in back via `getAutoTranslateConfig`. This is required because
+ * `withAutoTranslate` stamps `custom` on the object passed to the plugin's `collections` param, which
+ * can be a DIFFERENT object than the one registered in `buildConfig.collections` (the reader would
+ * otherwise see no config and the indicator would disagree with the behaviour). Idempotent + additive:
+ * re-stamping the same value is a no-op and the behaviour wiring still reads from the plugin param.
+ */ export function propagateAutoTranslateCustom(config, enabledSlugs, policies) {
+    for (const collection of config.collections ?? []){
+        if (!enabledSlugs.has(collection.slug)) continue;
+        const policy = policies.get(collection.slug);
+        if (!policy) continue;
+        collection.custom = {
+            ...collection.custom ?? {},
+            [AUTO_TRANSLATE_CUSTOM_KEY]: policy
+        };
+    }
+}
+
+//# sourceMappingURL=AutoTranslateEnqueue.hook.js.map

package/dist/server/modules/auto-translate/index.d.ts

@@ -0,0 +1,4 @@
+export { configureAutoTranslate } from "./AutoTranslate.wiring";
+export type { AutoTranslateModule } from "./AutoTranslate.wiring";
+export { makeAutoTranslateHook, injectAutoTranslateHook } from "./AutoTranslateEnqueue.hook";
+export type { AutoTranslatePolicyResolver, NormalizedAutoTranslatePolicy, } from "./AutoTranslate.policy";

package/dist/server/modules/auto-translate/index.js

@@ -0,0 +1,7 @@
+// Auto-translate adapter (Payload-backed). The payload-free drift predicate + config reader live in
+// the core (src/core/domain/auto-translate, src/core/domain/content-projection); this module is the config-time
+// wiring + the afterChange hook that enqueues translations on a source-locale change (#51).
+export { configureAutoTranslate } from "./AutoTranslate.wiring";
+export { makeAutoTranslateHook, injectAutoTranslateHook } from "./AutoTranslateEnqueue.hook";
+
+//# sourceMappingURL=index.js.map

package/dist/server/modules/index.d.ts

@@ -1,2 +1,2 @@
-export * from "../../core/translation-providers";
+export * from "../../core/domain/translation-providers";
 export * from "../../core/translation-pipeline";

package/dist/server/modules/index.js

@@ -1,4 +1,4 @@
-export * from "../../core/translation-providers";
+export * from "../../core/domain/translation-providers";
 export * from "../../core/translation-pipeline";
 
 //# sourceMappingURL=index.js.map

package/dist/server/modules/provenance/Provenance.service.d.ts

@@ -1,5 +1,5 @@
 import type { CollectionSlug, Payload } from "payload";
-import type { ProvenanceKey, ProvenanceStore } from "../../../core/provenance";
+import type { ProvenanceKey, ProvenanceStore } from "../../../core/domain/provenance";
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
 /** Per-locale staleness for one document (snake_case, matching the other translation endpoints). */
 export type StalenessLocale = {

package/dist/server/modules/provenance/Provenance.service.js

@@ -1,5 +1,5 @@
-import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
-import { isRecordStale } from "../../../core/provenance";
+import { computeSourceFingerprint } from "../../../core/domain/content-projection/computeSourceFingerprint";
+import { isRecordStale } from "../../../core/domain/provenance";
 import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
 /**
  * The single owner of provenance fingerprint policy — how the source is hashed on write, re-hashed on

package/dist/server/modules/provenance/Provenance.store.d.ts

@@ -1,5 +1,5 @@
 import type { Payload } from "payload";
-import type { ProvenanceKey, ProvenanceStore, TranslationProvenanceRecord } from "../../../core/provenance";
+import type { ProvenanceKey, ProvenanceStore, TranslationProvenanceRecord } from "../../../core/domain/provenance";
 /** Builds a provenance store bound to a Payload instance; absent when provenance is disabled. */
 export type ProvenanceStoreFactory = (payload: Payload) => ProvenanceStore;
 /**

package/dist/server/modules/provenance/index.js

@@ -1,5 +1,5 @@
 // Provenance adapter (Payload-backed). The framework-agnostic port + record types live in the core
-// (src/core/provenance); this module is the plugin-side implementation + its config-time wiring.
+// (src/core/domain/provenance); this module is the plugin-side implementation + its config-time wiring.
 export { DEFAULT_PROVENANCE_SLUG, isProvenanceCollection, makeProvenanceCollection } from "./Provenance.collection";
 export { PayloadProvenanceStore } from "./Provenance.store";
 export { injectProvenanceCleanup, makeProvenanceCleanupHook } from "./ProvenanceCleanup.hook";

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.js

@@ -31,6 +31,10 @@ const documentLocaleKey = (collectionId, targetLng)=>`${String(collectionId)}:${
         await Promise.all(tasks.map((task)=>this.payload.jobs.queue({
                 task: this.config.taskName,
                 queue: this.config.queueName,
+                // Debounce: when set, Payload holds the job until this instant. A superseding enqueue for
+                // the same (document, targetLng) cancels the pending delayed job first (see enqueue above),
+                // so rapid source edits coalesce to the final one. Undefined for the manual path.
+                waitUntil: task.waitUntil,
                 input: {
                     // Flat text reference (ID-agnostic). Stored as a string — no
                     // relationship type validation against the collection's ID type,

package/dist/server/modules/task-runner/types.d.ts

@@ -23,6 +23,13 @@ export type TaskInput = {
     targetLng: string;
     strategy: "overwrite" | "skip_existing";
     publishOnTranslation: boolean;
+    /**
+     * Optional scheduled-run time (debounce). When set, the job runs no earlier than this instant;
+     * omitted/`undefined` = run as soon as the runner picks it up (every existing caller). Honored by
+     * the Payload Jobs runner via `payload.jobs.queue({ waitUntil })`; the sync (dev) runner ignores it
+     * and runs immediately.
+     */
+    waitUntil?: Date;
 };
 /**
  * Normalized task representation

package/dist/server/modules/translation-levels/PluginConfigBuilder.d.ts

@@ -3,7 +3,7 @@ import type { AccessGuard } from "../../../types/AccessGuard";
 import type { RawPayloadComponentExport } from "../../../types/PayloadComponentExport";
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
 import type { ConfigModifier } from "../../../types/ConfigModifier";
-import type { TranslationProvider } from "../../../core/translation-providers";
+import type { TranslationProvider } from "../../../core/domain/translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
 import type { ProvenanceServiceFactory } from "../provenance";
 import type { CollectionAdminSlot, LevelContext, TranslationContext } from "./types";

package/dist/server/modules/translation-levels/types.d.ts

@@ -2,7 +2,7 @@ import type { CollectionConfig, Endpoint } from "payload";
 import type { AccessGuard } from "../../../types/AccessGuard";
 import type { RawPayloadComponentExport } from "../../../types/PayloadComponentExport";
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
-import type { TranslationProvider } from "../../../core/translation-providers";
+import type { TranslationProvider } from "../../../core/domain/translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
 import type { ProvenanceServiceFactory } from "../provenance";
 export type CollectionAdminSlot = "beforeDocumentControls" | "beforeListTable";

package/dist/server/shared/index.d.ts

@@ -4,9 +4,9 @@ export type { AccessGuard, AccessGuardRequest, Handler } from "./access";
 export { isEmpty, isObject, normalizePath, pipe, getByPath, setByPath, filterLocalizedFields, } from "./utils";
 export type { TranslatableField } from "./guards";
 export { isTranslatableField, isLocalizedField, isRelationshipField } from "./guards";
-export { isTabsField, isBlockItem, hasFields } from "../../core/field-traversal";
-export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig, } from "../../core/field-config";
-export type { TranslateKitFieldConfig } from "../../core/field-config";
-export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes, } from "../../core/lexical";
-export type { SerializedTextNodeRef } from "../../core/lexical";
+export { isTabsField, isBlockItem, hasFields } from "../../core/kernel/field-traversal";
+export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig, } from "../../core/domain/field-config";
+export type { TranslateKitFieldConfig } from "../../core/domain/field-config";
+export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes, } from "../../core/kernel/lexical";
+export type { SerializedTextNodeRef } from "../../core/kernel/lexical";
 export { JobIdSchema } from "./validation";

package/dist/server/shared/index.js

@@ -5,11 +5,11 @@ export { AnyAccessGuard } from "./access";
 // General utilities
 export { isEmpty, isObject, normalizePath, pipe, getByPath, setByPath, filterLocalizedFields } from "./utils";
 export { isTranslatableField, isLocalizedField, isRelationshipField } from "./guards";
-export { isTabsField, isBlockItem, hasFields } from "../../core/field-traversal";
+export { isTabsField, isBlockItem, hasFields } from "../../core/kernel/field-traversal";
 // Field config
-export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig } from "../../core/field-config";
+export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig } from "../../core/domain/field-config";
 // Lexical utilities
-export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes } from "../../core/lexical";
+export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes } from "../../core/kernel/lexical";
 // Validation primitives
 export { JobIdSchema } from "./validation";
 

package/dist/server/shared/utils/filterLocalizedFields.js

@@ -1,6 +1,6 @@
-import { resolveBlockFields, walkFields } from "../../../core/field-traversal";
+import { resolveBlockFields, walkFields } from "../../../core/kernel/field-traversal";
 import { isLocalizedField, isTranslatableField } from "../guards";
-import { isObject } from "../../../core/utils/isObject";
+import { isObject } from "../../../core/kernel/utils/isObject";
 /**
  * Filter walker: keeps only translatable, localized leaves, rebuilding the surrounding
  * object/array/blocks structure and dropping any container left empty. `id` (array/block

package/dist/server/shared/utils/getByPath.js

@@ -1,4 +1,4 @@
-import { isObject } from "../../../core/utils/isObject";
+import { isObject } from "../../../core/kernel/utils/isObject";
 /**
  * Gets a value from an object by dot-notation path.
  *

package/dist/server/shared/utils/index.d.ts

@@ -1,5 +1,5 @@
-export { isEmpty } from "../../../core/utils/isEmpty";
-export { isObject } from "../../../core/utils/isObject";
+export { isEmpty } from "../../../core/kernel/utils/isEmpty";
+export { isObject } from "../../../core/kernel/utils/isObject";
 export { normalizePath } from "./normalizePath";
 export { getByPath } from "./getByPath";
 export { setByPath } from "./setByPath";

package/dist/server/shared/utils/index.js

@@ -1,5 +1,5 @@
-export { isEmpty } from "../../../core/utils/isEmpty";
-export { isObject } from "../../../core/utils/isObject";
+export { isEmpty } from "../../../core/kernel/utils/isEmpty";
+export { isObject } from "../../../core/kernel/utils/isObject";
 export { normalizePath } from "./normalizePath";
 export { getByPath } from "./getByPath";
 export { setByPath } from "./setByPath";

package/dist/server/shared/utils/setByPath.js

@@ -1,4 +1,4 @@
-import { isObject } from "../../../core/utils/isObject";
+import { isObject } from "../../../core/kernel/utils/isObject";
 /**
  * Sets a value in an object by dot-notation path.
  * Creates intermediate objects/arrays as needed.

package/dist/translation-providers/index.d.ts

@@ -1,2 +1,2 @@
-export type { TranslationProvider, TranslationInput, TranslationOutput, } from "../core/translation-providers";
+export type { TranslationProvider, TranslationInput, TranslationOutput, } from "../core/domain/translation-providers";
 export * from "./openai";

package/dist/translation-providers/openai/OpenAITranslation.provider.d.ts

@@ -1,4 +1,4 @@
-import type { TranslationProvider, TranslationInput, TranslationOutput } from "../../core/translation-providers/TranslationProvider.interface";
+import type { TranslationProvider, TranslationInput, TranslationOutput } from "../../core/domain/translation-providers/TranslationProvider.interface";
 import type { ChatModel } from "openai/resources/index.mjs";
 /**
  * Function to transform text in dry run mode.

package/dist/translation-providers/openai/OpenAITranslation.provider.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { isObject } from "../../core/utils/isObject";
+import { isObject } from "../../core/kernel/utils/isObject";
 /** @deprecated Use `createOpenAIProvider` function instead */ export class OpenAITranslationProvider {
     openAiClient;
     config;

package/dist/types/AutoTranslateContext.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `req.context` flag the translator sets on its OWN document writes so the auto-translate
+ * `afterChange` hook skips them — the loop guard's second barrier (#51 D5). A single exported constant
+ * shared by the setter (`TranslateDocumentHandler.saveTranslatedDocument`) and the reader (the
+ * auto-translate hook), so the set-side and honor-side keys can never diverge.
+ *
+ * Lives in `types/` (a leaf contract) so both `server/features/translate-document` and
+ * `server/modules/auto-translate` import it without creating a cross-module edge.
+ */
+export declare const AUTO_TRANSLATE_SKIP_CONTEXT_KEY = "translatorSkipAutoTranslate";

package/dist/types/AutoTranslateContext.js

@@ -0,0 +1,11 @@
+/**
+ * The `req.context` flag the translator sets on its OWN document writes so the auto-translate
+ * `afterChange` hook skips them — the loop guard's second barrier (#51 D5). A single exported constant
+ * shared by the setter (`TranslateDocumentHandler.saveTranslatedDocument`) and the reader (the
+ * auto-translate hook), so the set-side and honor-side keys can never diverge.
+ *
+ * Lives in `types/` (a leaf contract) so both `server/features/translate-document` and
+ * `server/modules/auto-translate` import it without creating a cross-module edge.
+ */ export const AUTO_TRANSLATE_SKIP_CONTEXT_KEY = "translatorSkipAutoTranslate";
+
+//# sourceMappingURL=AutoTranslateContext.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",