@justanarthur/payload-plugin-translator 1.3.20 → 1.3.21

package/dist/jobs.d.ts

@@ -0,0 +1,195 @@
+import { CollectionAfterChangeHook } from "payload";
+type CreateAutoTranslateCollectionHookOptions = {
+	/**
+	* The collection's slug. Used to populate the workflow's
+	* `collection` input so the queued task targets the right entity.
+	*/
+	collectionSlug: string;
+	/**
+	* Source-of-truth locale. The hook only fires when the request
+	* is operating **in** this locale — edits to a non-default locale
+	* don't fan out (those edits would be translations of translations).
+	*
+	* Falls back to `req.payload.config.localization.defaultLocale`
+	* at request time when omitted.
+	*/
+	defaultLocale?: string;
+	/**
+	* Target locales the workflow fans out to. Defaults to every
+	* locale declared on `req.payload.config.localization.locales`
+	* **except** the default locale.
+	*/
+	targetLocales?: string[];
+	/**
+	* Only fan out when the doc is published. Default: `true`.
+	* Keeps draft autosaves from triggering per-locale jobs.
+	* Set `false` if your host treats drafts as valid translation
+	* sources.
+	*/
+	onlyOnPublished?: boolean;
+	/**
+	* Workflow slug the hook queues. Must match the slug of the
+	* workflow registered in
+	* `payload.config.ts → jobs: { workflows: [...] }`.
+	* Default: `'translateEntityToLocales'`.
+	*/
+	workflowSlug?: string;
+	/**
+	* Resolver key the queued task should call. Must match a `key`
+	* declared in `translator({ resolvers: [...] })`. Default: the
+	* first registered resolver's key (resolved at request time),
+	* which the workflow forwards to the per-locale task as the
+	* `resolver` input.
+	*/
+	resolverKey?: string;
+};
+/**
+* Build a `CollectionAfterChangeHook` that schedules the
+* auto-translation workflow for every non-default locale.
+*
+* Skip rules (any one is sufficient):
+*
+* - `context.disableAutoTranslate` is set (lets seed scripts and
+*   tests opt out).
+* - `req.locale` is missing or doesn't match `defaultLocale`.
+* - `req.user` is missing (system-initiated changes shouldn't
+*   kick off LLM-billed jobs).
+* - `onlyOnPublished` (default `true`) is enabled and the doc's
+*   `_status` is not `'published'`.
+* - The resolved target locale list is empty (e.g. single-locale
+*   site).
+*/
+declare function createAutoTranslateCollectionHook(options: CreateAutoTranslateCollectionHookOptions): {
+	afterChange: CollectionAfterChangeHook;
+};
+import { GlobalAfterChangeHook } from "payload";
+type CreateAutoTranslateGlobalHookOptions = {
+	/**
+	* The global's slug. Used to populate the workflow's `global`
+	* input so the queued task targets the right entity.
+	*/
+	globalSlug: string;
+	/**
+	* Source-of-truth locale. The hook only fires when the request
+	* is operating **in** this locale — edits to a non-default locale
+	* don't fan out (those edits would be translations of translations).
+	*
+	* Falls back to `req.payload.config.localization.defaultLocale`
+	* at request time when omitted.
+	*/
+	defaultLocale?: string;
+	/**
+	* Target locales the workflow fans out to. Defaults to every
+	* locale declared on `req.payload.config.localization.locales`
+	* **except** the default locale.
+	*/
+	targetLocales?: string[];
+	/**
+	* Workflow slug the hook queues. Must match the slug of the
+	* workflow registered in
+	* `payload.config.ts → jobs: { workflows: [...] }`.
+	* Default: `'translateEntityToLocales'`.
+	*/
+	workflowSlug?: string;
+	/**
+	* Resolver key the queued task should call. Must match a `key`
+	* declared in `translator({ resolvers: [...] })`. Default: the
+	* first registered resolver's key (resolved at request time),
+	* which the workflow forwards to the per-locale task as the
+	* `resolver` input.
+	*/
+	resolverKey?: string;
+};
+/**
+* Build a `GlobalAfterChangeHook` that schedules the
+* auto-translation workflow for every non-default locale.
+*
+* Same skip rules as the collection hook factory **minus** the
+* `_status === 'published'` check (globals have no versioning —
+* every save is the canonical state). See
+* `createAutoTranslateCollectionHook` for the full rule list.
+*/
+declare function createAutoTranslateGlobalHook(options: CreateAutoTranslateGlobalHookOptions): GlobalAfterChangeHook;
+import { TaskConfig, TaskHandler } from "payload";
+type TranslateTaskConfig = Omit<TaskConfig, "handler"> & {
+	handler: TaskHandler<string, string>;
+};
+type CreateTranslateTaskOptions = {
+	/**
+	* Resolver key the upstream `translateOperation` should call.
+	* Must match a `key` declared in the host's
+	* `translator({ resolvers: [{ key: '<X>', resolve: ... }] })`.
+	* Falls back to the first registered resolver's key when omitted.
+	*/
+	resolverKey?: string;
+	/**
+	* Override the task slug. Default:
+	* `'translateEntityToLocale'`.
+	*/
+	slug?: string;
+};
+/**
+* Build the per-locale translation task.
+*
+* Behaviour:
+*
+* 1. Call `translateOperation` with
+*    `emptyOnly: false, overrideAccess: true, update: false` so we
+*    get a translated payload without the plugin writing back.
+* 2. Strip the synthetic `_locale` / `_parent_id` keys the plugin
+*    attaches to the result.
+* 3. Persist via `req.payload.update` (collection) or
+*    `req.payload.updateGlobal` (global) at `toLocale`, again with
+*    `overrideAccess: true` so jobs run cleanly outside user
+*    sessions.
+* 4. Fail loudly on any error — Payload retries the task up to
+*    `retries` times before giving up.
+*
+* Hosts wire the returned task into
+* `payload.config.ts → jobs: { tasks: [<task>] }`.
+*/
+declare function createTranslateTask(options?: CreateTranslateTaskOptions): TranslateTaskConfig;
+import { WorkflowConfig, WorkflowHandler } from "payload";
+type TranslateWorkflowConfig = Omit<WorkflowConfig, "handler"> & {
+	handler: WorkflowHandler;
+};
+type CreateTranslateWorkflowOptions = {
+	/**
+	* Override the workflow slug. Default:
+	* `'translateEntityToLocales'`.
+	*/
+	slug?: string;
+	/**
+	* Override the per-locale task slug the workflow schedules.
+	* Must match the slug passed to `createTranslateTask` on the
+	* host's side. Default: `'translateEntityToLocale'`.
+	*/
+	taskSlug?: string;
+};
+/**
+* Build the per-save translation workflow.
+*
+* The workflow receives one `entity + (fromLocale, toLocale, updatedAt)`
+* tuple per call and schedules **one** `translateEntityToLocale` task.
+* The `afterChange` hook factories fan out one call per non-default
+* locale so each task runs independently — one failing locale does
+* not block the others.
+*
+* The dedupe key (entity + locales + `updatedAt`) lets Payload collapse
+* duplicate jobs queued by rapid autosave bursts.
+*
+* Hosts wire the returned workflow into
+* `payload.config.ts → jobs: { workflows: [<workflow>] }`.
+*/
+declare function createTranslateWorkflow(options?: CreateTranslateWorkflowOptions): TranslateWorkflowConfig;
+declare const TRANSLATE_TASK_SLUG = "translateEntityToLocale";
+declare const TRANSLATE_WORKFLOW_SLUG = "translateEntityToLocales";
+declare const jobs: {
+	TRANSLATE_TASK_SLUG: string;
+	TRANSLATE_WORKFLOW_SLUG: string;
+	createTranslateTask: typeof createTranslateTask;
+	createTranslateWorkflow: typeof createTranslateWorkflow;
+	createAutoTranslateCollectionHook: typeof createAutoTranslateCollectionHook;
+	createAutoTranslateGlobalHook: typeof createAutoTranslateGlobalHook;
+};
+export { jobs as default, createTranslateWorkflow, createTranslateTask, createAutoTranslateGlobalHook, createAutoTranslateCollectionHook, TranslateWorkflowConfig, TranslateTaskConfig, TRANSLATE_WORKFLOW_SLUG, TRANSLATE_TASK_SLUG, CreateTranslateWorkflowOptions, CreateTranslateTaskOptions, CreateAutoTranslateGlobalHookOptions, CreateAutoTranslateCollectionHookOptions };