@purposeinplay/payload-ai-translate 0.1.0

package/dist/translate.d.ts

@@ -0,0 +1,113 @@
+import type { Payload, PayloadRequest } from 'payload';
+import type { AITranslatePluginConfig, FieldLocaleResult, TargetPolicy, TranslatableField, TranslationUnit, TranslationUsage } from './types.js';
+export type TranslateForLocaleParams = {
+    payload: Payload;
+    config: AITranslatePluginConfig;
+    sourceDoc: Record<string, unknown>;
+    documentId: string | number;
+    collection: string;
+    targetLocale: string;
+    units: TranslationUnit[];
+    fields: TranslatableField[];
+    /**
+     * Full set of localized top-level field names from the schema, NOT
+     * restricted by `options.fields`. Threaded into the merge so that a
+     * per-field translate (which narrows `fields` to one path) still
+     * populates required-localized siblings in writeData.
+     */
+    allLocalizedTopFields?: Set<string>;
+    /** See `TranslateDocumentOptions.writeMode`. */
+    writeMode?: 'full' | 'minimal';
+    targetPolicy: TargetPolicy;
+    signal?: AbortSignal;
+    /**
+     * Source request, when available. Threaded into the locale `payload.update`
+     * so audit/change hooks see `req.user` and can attribute the write.
+     */
+    req?: PayloadRequest;
+    /**
+     * When `true`, bypass the hash-skip (BUG-21) and manual-edit preserve
+     * guards. See `TranslateDocumentOptions.force` for the full contract.
+     * Hash bookkeeping after a successful write stays active either way.
+     */
+    force?: boolean;
+};
+export type TranslateForLocaleResult = {
+    succeeded: FieldLocaleResult[];
+    preserved: FieldLocaleResult[];
+    failed: FieldLocaleResult[];
+    usage: TranslationUsage;
+    /**
+     * Cumulative provider-call latency for this locale, in milliseconds.
+     * Sum of `latencyMs` returned by each `translateBatch` invocation —
+     * captures ONLY the actual LLM round-trip time, excluding token-bucket
+     * wait + provider rate-limit backoff (those happen before the SDK
+     * call inside the provider, and the provider's latencyMs is measured
+     * around the SDK call itself).
+     */
+    providerLatencyMs: number;
+};
+export declare function translateForLocale(params: TranslateForLocaleParams): Promise<TranslateForLocaleResult>;
+export type BatchTranslateParams = {
+    batch: TranslationUnit[];
+    config: AITranslatePluginConfig;
+    collection: string;
+    targetLocale: string;
+    signal?: AbortSignal;
+    retryConfig: {
+        attempts: number;
+        backoffMs: number;
+    };
+    /**
+     * Optional Payload handle used for structured logging only. The batch
+     * translation itself doesn't touch the DB — `payload` is threaded in
+     * so provider-retry warns / exhaustion errors land in pino with full
+     * structured fields (event, err.cause, locale, attempt).
+     */
+    payload?: Payload;
+};
+export type BatchTranslateResult = {
+    translations: Map<string, string>;
+    errors: Map<string, string>;
+    /**
+     * Parallel to `errors`: editor-facing code per failed unit id. Keys
+     * mirror `errors` 1:1 — UI renders `editorMessageFor(code)` with the
+     * raw `errors` string available behind a "Show technical details"
+     * disclosure.
+     */
+    errorCodes: Map<string, string>;
+    /**
+     * Items the validator marked as a "soft" rejection — typically a verbatim
+     * echo of source. The plugin still won't write them (we don't want source
+     * content in target locales), but the caller routes them to `skipped`
+     * status so the UI doesn't surface them as errors.
+     */
+    skipped: Map<string, string>;
+    /**
+     * Parallel to `skipped`: editor-facing code per skipped unit id. Keys
+     * mirror `skipped` 1:1. Empty when validation didn't classify (legacy).
+     */
+    skippedCodes: Map<string, string>;
+    usage: TranslationUsage;
+    latencyMs: number;
+};
+export declare function translateBatch(params: BatchTranslateParams): Promise<BatchTranslateResult>;
+/**
+ * Default items-per-batch cap. Independent of `perCallCharLimit`. Exists
+ * because some structured-output upstreams (Gemini 2.5 Flash via OpenRouter
+ * is the canonical case, surfaced 2026-06-04 on wild-payload-cms) silently
+ * stall on response generation when the response items array grows past
+ * a few hundred entries — HTTP 200 + headers arrive in <2s, then the body
+ * never finishes streaming and the per-call timeout aborts the whole
+ * batch. The char cap doesn't catch this because short strings (nav
+ * labels, JSON keys) pack many items into modest byte counts.
+ *
+ * 250 is chosen empirically: a `loyalty` JSON sub-object on
+ * wild-payload-cms (286 short keys, ~25k chars) completed in ~30s and
+ * 100% success; a 500-item batch on the same provider timed out roughly
+ * 3 of every 4 attempts. 250 puts us under the observed stall threshold
+ * with margin. Consumers running larger-context models (Claude Sonnet,
+ * GPT-4o) can override with a higher value via `costLimits.perCallItemLimit`.
+ */
+export declare const DEFAULT_PER_CALL_ITEM_LIMIT = 250;
+export declare function batchUnits(units: TranslationUnit[], perCallCharLimit: number, perCallItemLimit?: number): TranslationUnit[][];