@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/progress-store.d.ts

@@ -0,0 +1,103 @@
+export type TranslationJobStatus = 'running' | 'completed' | 'failed';
+export type TranslationJob = {
+    jobId: string;
+    collection: string;
+    documentId: string | number;
+    totalLocales: number;
+    completedLocales: string[];
+    failedLocales: {
+        locale: string;
+        error: string;
+    }[];
+    status: TranslationJobStatus;
+    startedAt: number;
+};
+export type JobProgressEvent = {
+    jobId: string;
+    completed: string[];
+    failed: {
+        locale: string;
+        error: string;
+    }[];
+    total: number;
+    status: TranslationJobStatus;
+};
+export type Subscriber = (event: JobProgressEvent) => void;
+/**
+ * Doc-level subscriber. Fires once per `createJob` for a matching
+ * (collection, documentId) pair, with the new job's first event.
+ * Lets the SSE endpoint hold an open stream for "any job on this doc"
+ * and push immediately when one starts — no client polling needed.
+ */
+export type DocSubscriber = (event: JobProgressEvent) => void;
+/**
+ * Optional persistence target. When the plugin's `persistJobs: true`
+ * is set, plugin.ts calls `setPersistenceContext()` at boot with the
+ * Payload instance + jobs-collection slug. Every mutation to `jobs`
+ * (create/update/cleanup) then also mirrors to the sidecar collection.
+ *
+ * Mirror writes are fire-and-forget — failures don't roll back the
+ * in-memory mutation. The persistence layer is for VISIBILITY across
+ * restarts; the actual translation closures still live in process
+ * memory and don't resume after a restart.
+ */
+type PersistenceContext = {
+    payload: {
+        create: (args: unknown) => Promise<unknown>;
+        update: (args: unknown) => Promise<unknown>;
+        delete: (args: unknown) => Promise<unknown>;
+        find: (args: unknown) => Promise<{
+            docs: unknown[];
+        }>;
+        logger?: {
+            warn?: (msg: string) => void;
+        };
+    };
+    collectionSlug: string;
+};
+export declare function setPersistenceContext(ctx: PersistenceContext | null): void;
+export declare function createJob(collection: string, documentId: string | number, locales: string[]): string;
+export declare function updateJob(jobId: string, locale: string, success: boolean, error?: string): void;
+export declare function getJob(jobId: string): TranslationJob | undefined;
+/**
+ * Atomically return the active job for `(collection, documentId)` or
+ * create a new one in a single synchronous step. Replaces the unsafe
+ * `getActiveJobForDoc(...) ?? createJob(...)` pattern: two concurrent
+ * after-change hook fires for the same doc could both read `undefined`
+ * from `getActiveJobForDoc` and both call `createJob`, producing two
+ * jobs (and two LLM calls) for the same write.
+ *
+ * Because Node is single-threaded and this whole function runs
+ * synchronously between event-loop turns, the get + set pair is
+ * effectively atomic from the caller's perspective. No mutex needed.
+ *
+ * Returns `{ jobId, created: boolean }`. Callers can branch on
+ * `created` to decide whether to fire a new translation closure
+ * (`created: true`) or join an in-flight one (`created: false`).
+ */
+export declare function getOrCreateJobForDoc(collection: string, documentId: string | number, locales: string[]): {
+    jobId: string;
+    created: boolean;
+};
+/**
+ * Mark a still-running job as `completed` without performing any
+ * translation. Used by the after-change hooks when they decide to
+ * short-circuit (e.g. `skipAutoOnPublish: true` from `effective-locales`)
+ * AFTER a job has already been seeded by a parent flow — without this,
+ * the polling UI would show "Translating…" until the TTL sweep
+ * (2 minutes). Notifies SSE subscribers so the client can clear its
+ * progress widget immediately. No-op if `jobId` isn't tracked.
+ */
+export declare function completeJobNow(jobId: string): void;
+export declare function getActiveJobForDoc(collection: string, documentId: string | number): TranslationJob | undefined;
+export declare function subscribe(jobId: string, callback: Subscriber): () => void;
+/**
+ * Subscribe to "any new job created for this (collection, documentId)".
+ * The callback fires once per new job started after this subscription is
+ * registered. Used by the `?docId=X` SSE endpoint to push events to open
+ * editors the moment a translation begins.
+ */
+export declare function subscribeToDoc(collection: string, documentId: string | number, callback: DocSubscriber): () => void;
+export declare function cleanup(): void;
+export declare function _resetStore(): void;
+export {};

package/dist/lib/progress-store.js

@@ -0,0 +1,314 @@
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+const jobs = new Map();
+const subscribers = new Map();
+const docSubscribers = new Map();
+let persistenceContext = null;
+export function setPersistenceContext(ctx) {
+    persistenceContext = ctx;
+}
+function mirrorCreate(job) {
+    if (!persistenceContext) return;
+    void persistenceContext.payload.create({
+        collection: persistenceContext.collectionSlug,
+        data: {
+            jobId: job.jobId,
+            collection: job.collection,
+            documentId: String(job.documentId),
+            status: job.status,
+            totalLocales: job.totalLocales,
+            completedLocales: job.completedLocales,
+            failedLocales: job.failedLocales,
+            startedAt: new Date(job.startedAt).toISOString()
+        },
+        overrideAccess: true
+    }).catch((err)=>{
+        // BUG-29 fix: don't silently swallow. Under bursty parallel
+        // translates (e.g. bulk-publish of 5+ docs), one of the
+        // concurrent `payload.create` calls on `ai_translate_jobs` can
+        // hit a transient DB conflict or transaction race; pre-fix this
+        // silently dropped the row and the admin Jobs page lost one
+        // out of N entries. We log loud + warn so ops can see it
+        // happened; the in-memory job is still correct so translation
+        // proceeds.
+        persistenceContext?.payload.logger?.warn?.(`[ai-translate] mirrorCreate for ai_translate_jobs failed for ${job.collection}/${String(job.documentId)} jobId=${job.jobId}: ${err instanceof Error ? err.message : 'Unknown error'}. The in-memory job remains active; the admin Jobs page may be missing this row.`);
+    });
+}
+function mirrorUpdate(job) {
+    if (!persistenceContext) return;
+    // Find by jobId then update — Payload doesn't expose upsert.
+    void persistenceContext.payload.find({
+        collection: persistenceContext.collectionSlug,
+        where: {
+            jobId: {
+                equals: job.jobId
+            }
+        },
+        limit: 1,
+        depth: 0,
+        overrideAccess: true
+    }).then(async (result)=>{
+        const first = result.docs[0];
+        if (!first?.id) return;
+        await persistenceContext.payload.update({
+            collection: persistenceContext.collectionSlug,
+            id: first.id,
+            data: {
+                status: job.status,
+                completedLocales: job.completedLocales,
+                failedLocales: job.failedLocales
+            },
+            overrideAccess: true
+        });
+    }).catch(()=>{});
+}
+function mirrorDelete(jobId) {
+    if (!persistenceContext) return;
+    void persistenceContext.payload.find({
+        collection: persistenceContext.collectionSlug,
+        where: {
+            jobId: {
+                equals: jobId
+            }
+        },
+        limit: 1,
+        depth: 0,
+        overrideAccess: true
+    }).then(async (result)=>{
+        const first = result.docs[0];
+        if (!first?.id) return;
+        await persistenceContext.payload.delete({
+            collection: persistenceContext.collectionSlug,
+            id: first.id,
+            overrideAccess: true
+        });
+    }).catch(()=>{});
+}
+// Background cleanup interval. Lazily armed on the first `createJob` so a
+// long-idle process (no translations ever) doesn't keep a timer alive. The
+// previous behavior only ran `cleanup()` on new-job arrival, so finished
+// jobs from a short burst would sit in memory forever during quiet periods.
+let cleanupTimer = null;
+const CLEANUP_INTERVAL_MS = 60_000; // 1 min; jobs expire at 2 min
+function armCleanupTimer() {
+    if (cleanupTimer !== null) return;
+    cleanupTimer = setInterval(()=>{
+        cleanup();
+        // Disarm when the store is fully drained so the timer doesn't keep the
+        // process alive in test runners or short-lived scripts.
+        if (jobs.size === 0) {
+            if (cleanupTimer) {
+                clearInterval(cleanupTimer);
+                cleanupTimer = null;
+            }
+        }
+    }, CLEANUP_INTERVAL_MS);
+    // Allow the Node event loop to exit even if the timer is still scheduled.
+    cleanupTimer.unref?.();
+}
+function docKey(collection, documentId) {
+    return `${collection}::${String(documentId)}`;
+}
+const JOB_TTL_MS = 120_000; // 2 minutes
+function toEvent(job) {
+    return {
+        jobId: job.jobId,
+        completed: [
+            ...job.completedLocales
+        ],
+        failed: [
+            ...job.failedLocales
+        ],
+        total: job.totalLocales,
+        status: job.status
+    };
+}
+function notifySubscribers(jobId) {
+    const job = jobs.get(jobId);
+    const subs = subscribers.get(jobId);
+    if (!job || !subs || subs.size === 0) return;
+    const event = toEvent(job);
+    for (const callback of subs){
+        try {
+            callback(event);
+        } catch  {
+        // Subscriber errors never break the store
+        }
+    }
+}
+function notifyDocSubscribers(job) {
+    const subs = docSubscribers.get(docKey(job.collection, job.documentId));
+    if (!subs || subs.size === 0) return;
+    const event = toEvent(job);
+    for (const callback of subs){
+        try {
+            callback(event);
+        } catch  {
+        // Subscriber errors never break the store
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function createJob(collection, documentId, locales) {
+    cleanup();
+    armCleanupTimer();
+    const jobId = randomUUID();
+    const job = {
+        jobId,
+        collection,
+        documentId,
+        totalLocales: locales.length,
+        completedLocales: [],
+        failedLocales: [],
+        status: 'running',
+        startedAt: Date.now()
+    };
+    jobs.set(jobId, job);
+    mirrorCreate(job);
+    // Notify any open `?docId=X` SSE streams that a new job has started
+    // for this document. The client can then mount its progress UI
+    // immediately — no polling delay.
+    notifyDocSubscribers(job);
+    return jobId;
+}
+export function updateJob(jobId, locale, success, error) {
+    const job = jobs.get(jobId);
+    if (!job) return;
+    // BUG-29 fix: dedup before append. Under bursty parallel translates
+    // a retry path or duplicate fire could call updateJob twice with the
+    // same locale, producing `completed_locales: ["es", "es"]`. Set-style
+    // dedup keeps the array correct under all event orderings.
+    if (success) {
+        if (!job.completedLocales.includes(locale)) {
+            job.completedLocales.push(locale);
+        }
+    } else {
+        const alreadyFailed = job.failedLocales.some((f)=>f.locale === locale);
+        if (!alreadyFailed) {
+            job.failedLocales.push({
+                locale,
+                error: error ?? 'Unknown error'
+            });
+        }
+    }
+    const done = job.completedLocales.length + job.failedLocales.length;
+    if (done >= job.totalLocales) {
+        job.status = job.failedLocales.length > 0 ? 'failed' : 'completed';
+    }
+    mirrorUpdate(job);
+    notifySubscribers(jobId);
+}
+export function getJob(jobId) {
+    return jobs.get(jobId);
+}
+/**
+ * Atomically return the active job for `(collection, documentId)` or
+ * create a new one in a single synchronous step. Replaces the unsafe
+ * `getActiveJobForDoc(...) ?? createJob(...)` pattern: two concurrent
+ * after-change hook fires for the same doc could both read `undefined`
+ * from `getActiveJobForDoc` and both call `createJob`, producing two
+ * jobs (and two LLM calls) for the same write.
+ *
+ * Because Node is single-threaded and this whole function runs
+ * synchronously between event-loop turns, the get + set pair is
+ * effectively atomic from the caller's perspective. No mutex needed.
+ *
+ * Returns `{ jobId, created: boolean }`. Callers can branch on
+ * `created` to decide whether to fire a new translation closure
+ * (`created: true`) or join an in-flight one (`created: false`).
+ */ export function getOrCreateJobForDoc(collection, documentId, locales) {
+    const existing = getActiveJobForDoc(collection, documentId);
+    if (existing) return {
+        jobId: existing.jobId,
+        created: false
+    };
+    const jobId = createJob(collection, documentId, locales);
+    return {
+        jobId,
+        created: true
+    };
+}
+/**
+ * Mark a still-running job as `completed` without performing any
+ * translation. Used by the after-change hooks when they decide to
+ * short-circuit (e.g. `skipAutoOnPublish: true` from `effective-locales`)
+ * AFTER a job has already been seeded by a parent flow — without this,
+ * the polling UI would show "Translating…" until the TTL sweep
+ * (2 minutes). Notifies SSE subscribers so the client can clear its
+ * progress widget immediately. No-op if `jobId` isn't tracked.
+ */ export function completeJobNow(jobId) {
+    const job = jobs.get(jobId);
+    if (!job) return;
+    if (job.status !== 'running') return; // already terminal
+    job.status = 'completed';
+    mirrorUpdate(job);
+    notifySubscribers(jobId);
+}
+export function getActiveJobForDoc(collection, documentId) {
+    for (const job of jobs.values()){
+        if (job.collection === collection && String(job.documentId) === String(documentId) && job.status === 'running') {
+            return job;
+        }
+    }
+    return undefined;
+}
+export function subscribe(jobId, callback) {
+    if (!subscribers.has(jobId)) {
+        subscribers.set(jobId, new Set());
+    }
+    subscribers.get(jobId).add(callback);
+    return ()=>{
+        const subs = subscribers.get(jobId);
+        if (subs) {
+            subs.delete(callback);
+            if (subs.size === 0) {
+                subscribers.delete(jobId);
+            }
+        }
+    };
+}
+/**
+ * Subscribe to "any new job created for this (collection, documentId)".
+ * The callback fires once per new job started after this subscription is
+ * registered. Used by the `?docId=X` SSE endpoint to push events to open
+ * editors the moment a translation begins.
+ */ export function subscribeToDoc(collection, documentId, callback) {
+    const key = docKey(collection, documentId);
+    if (!docSubscribers.has(key)) {
+        docSubscribers.set(key, new Set());
+    }
+    docSubscribers.get(key).add(callback);
+    return ()=>{
+        const subs = docSubscribers.get(key);
+        if (subs) {
+            subs.delete(callback);
+            if (subs.size === 0) {
+                docSubscribers.delete(key);
+            }
+        }
+    };
+}
+export function cleanup() {
+    const now = Date.now();
+    for (const [jobId, job] of jobs){
+        if (now - job.startedAt > JOB_TTL_MS) {
+            jobs.delete(jobId);
+            subscribers.delete(jobId);
+            mirrorDelete(jobId);
+        }
+    }
+}
+// For testing
+export function _resetStore() {
+    jobs.clear();
+    subscribers.clear();
+    docSubscribers.clear();
+    if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+    }
+}

package/dist/lib/rate-limiter.d.ts

@@ -0,0 +1,3 @@
+export declare function createRateLimiter(rpm: number): {
+    acquire(): Promise<void>;
+};

package/dist/lib/rate-limiter.js

@@ -0,0 +1,53 @@
+export function createRateLimiter(rpm) {
+    let tokens = rpm;
+    const refillRate = rpm / 60; // tokens per second
+    let lastRefill = Date.now();
+    const waiters = [];
+    let refillTimer = null;
+    function refill() {
+        const now = Date.now();
+        const elapsed = (now - lastRefill) / 1000;
+        tokens = Math.min(rpm, tokens + elapsed * refillRate);
+        lastRefill = now;
+    }
+    function drainWaiters() {
+        while(waiters.length > 0 && tokens >= 1){
+            tokens -= 1;
+            const resolve = waiters.shift();
+            resolve();
+        }
+    }
+    function scheduleRefillCheck() {
+        // Clean up any existing timer to prevent leaks
+        if (refillTimer !== null) {
+            clearTimeout(refillTimer);
+            refillTimer = null;
+        }
+        if (waiters.length === 0) {
+            return;
+        }
+        const msPerToken = 1000 / refillRate;
+        refillTimer = setTimeout(()=>{
+            refillTimer = null;
+            refill();
+            drainWaiters();
+            scheduleRefillCheck();
+        }, msPerToken);
+    }
+    return {
+        acquire () {
+            refill();
+            if (tokens >= 1) {
+                tokens -= 1;
+                return Promise.resolve();
+            }
+            return new Promise((resolve)=>{
+                const wasEmpty = waiters.length === 0;
+                waiters.push(resolve);
+                if (wasEmpty) {
+                    scheduleRefillCheck();
+                }
+            });
+        }
+    };
+}

package/dist/lib/snapshot-select.d.ts

@@ -0,0 +1,43 @@
+import type { TranslatableField } from '../types.js';
+/**
+ * Capture ONLY the localized translatable fields from a doc, stored
+ * as a nested object payload that can be passed directly to
+ * `payload.update({ data: snapshot })` during the revert action.
+ *
+ * Security (Decision #30 + F-SEC-SNAPSHOT): Payload's `findByID`
+ * returns the full document, which includes `password` hashes,
+ * `email`, `roles`, and other `excludeFields` content. Storing that
+ * into `bulk-translate-units.preRunSnapshot` jsonb would leak
+ * sensitive data into a queryable admin collection. This helper:
+ *   1. Rejects any path whose top-level segment is in the forbidden
+ *      denylist (runtime guard, not just convention).
+ *   2. Scopes captured keys to ONLY the paths the caller provided.
+ *
+ * Shape (Decision #22 v2 / F-DA-REVERT round-trip): paths with dots
+ * (e.g. `meta.description`) are stored as NESTED objects
+ * (`{ meta: { description: <value> } }`), not as flat keys with
+ * literal dots. This makes the snapshot a valid `payload.update`
+ * payload directly — revert simply spreads it into `data`.
+ *
+ * Array-index paths (`sections.0.title`) are intentionally rejected
+ * — they expand via the existing resolveTranslatableFields walker
+ * before this helper sees them. The CALLER passes the shape paths
+ * (`title`, `sections`); this helper does NOT understand per-index
+ * traversal.
+ */
+export declare function captureLocalizedSnapshot(doc: Record<string, unknown>, localizedFieldPaths: readonly string[]): Record<string, unknown>;
+/**
+ * Schema-hash of the localized translatable fields. Used by the
+ * revert action: if the schema changed between snapshot and replay
+ * (field renamed, type changed, field de-localized, field removed),
+ * the hash differs and the revert refuses unless the admin sets
+ * `force: true` (Decision #34 + F-DA-REVERT-SCHEMA).
+ *
+ * Hash includes `(path, type, localized)` tuples, sorted, so order
+ * doesn't matter. The `localized` flag is included because
+ * de-localizing a field (true → false) silently breaks revert: the
+ * snapshot data lives in a locale-scoped jsonb but the field on the
+ * doc is now global, and replaying writes either error or land in
+ * the wrong slot. Including the flag in the hash catches this.
+ */
+export declare function hashLocalizedSchema(fields: readonly TranslatableField[]): string;

package/dist/lib/snapshot-select.js

@@ -0,0 +1,108 @@
+import { hashFieldContent } from './content-hash.js';
+/**
+ * Hard denylist of field names that must NEVER appear in a snapshot.
+ * Converts F-SEC-SNAPSHOT from a documentation convention into a
+ * runtime invariant — a future call site that passes these by mistake
+ * will throw at snapshot time rather than silently leak them into a
+ * queryable `bulk-translate-units.preRunSnapshot` jsonb column.
+ */ const FORBIDDEN_TOP_LEVEL_KEYS = new Set([
+    'password',
+    'email',
+    'emailVerified',
+    'roles',
+    'salt',
+    'hash',
+    'apiKey',
+    'apiKeyIndex',
+    'secret',
+    'token',
+    'resetPasswordToken',
+    'loginAttempts',
+    'lockUntil'
+]);
+const NUMERIC_SEGMENT_RE = /^\d+$/;
+/**
+ * Capture ONLY the localized translatable fields from a doc, stored
+ * as a nested object payload that can be passed directly to
+ * `payload.update({ data: snapshot })` during the revert action.
+ *
+ * Security (Decision #30 + F-SEC-SNAPSHOT): Payload's `findByID`
+ * returns the full document, which includes `password` hashes,
+ * `email`, `roles`, and other `excludeFields` content. Storing that
+ * into `bulk-translate-units.preRunSnapshot` jsonb would leak
+ * sensitive data into a queryable admin collection. This helper:
+ *   1. Rejects any path whose top-level segment is in the forbidden
+ *      denylist (runtime guard, not just convention).
+ *   2. Scopes captured keys to ONLY the paths the caller provided.
+ *
+ * Shape (Decision #22 v2 / F-DA-REVERT round-trip): paths with dots
+ * (e.g. `meta.description`) are stored as NESTED objects
+ * (`{ meta: { description: <value> } }`), not as flat keys with
+ * literal dots. This makes the snapshot a valid `payload.update`
+ * payload directly — revert simply spreads it into `data`.
+ *
+ * Array-index paths (`sections.0.title`) are intentionally rejected
+ * — they expand via the existing resolveTranslatableFields walker
+ * before this helper sees them. The CALLER passes the shape paths
+ * (`title`, `sections`); this helper does NOT understand per-index
+ * traversal.
+ */ export function captureLocalizedSnapshot(doc, localizedFieldPaths) {
+    const out = {};
+    for (const path of localizedFieldPaths){
+        const segments = path.split('.');
+        const top = segments[0];
+        if (top && FORBIDDEN_TOP_LEVEL_KEYS.has(top)) {
+            throw new Error(`[ai-translate] captureLocalizedSnapshot: refusing to snapshot sensitive field path "${path}" (top-level key "${top}" is in the F-SEC-SNAPSHOT denylist). Caller must exclude this path before calling.`);
+        }
+        for (const seg of segments){
+            if (NUMERIC_SEGMENT_RE.test(seg)) {
+                throw new Error(`[ai-translate] captureLocalizedSnapshot: array-index paths are not supported here. Pass the shape path (e.g. "sections") instead of the indexed path ("${path}"). Array-item traversal lives in resolveTranslatableFields.`);
+            }
+        }
+        const value = resolvePathValue(doc, segments);
+        if (value !== undefined) {
+            setNestedPath(out, segments, value);
+        }
+    }
+    return out;
+}
+/**
+ * Schema-hash of the localized translatable fields. Used by the
+ * revert action: if the schema changed between snapshot and replay
+ * (field renamed, type changed, field de-localized, field removed),
+ * the hash differs and the revert refuses unless the admin sets
+ * `force: true` (Decision #34 + F-DA-REVERT-SCHEMA).
+ *
+ * Hash includes `(path, type, localized)` tuples, sorted, so order
+ * doesn't matter. The `localized` flag is included because
+ * de-localizing a field (true → false) silently breaks revert: the
+ * snapshot data lives in a locale-scoped jsonb but the field on the
+ * doc is now global, and replaying writes either error or land in
+ * the wrong slot. Including the flag in the hash catches this.
+ */ export function hashLocalizedSchema(fields) {
+    const sorted = [
+        ...fields
+    ].map((f)=>`${f.path}:${f.type}:${f.localized ? 'l' : 'g'}`).sort().join('\n');
+    return hashFieldContent(sorted);
+}
+function resolvePathValue(doc, segments) {
+    let cursor = doc;
+    for (const part of segments){
+        if (cursor === null || cursor === undefined) return undefined;
+        if (typeof cursor !== 'object') return undefined;
+        cursor = cursor[part];
+    }
+    return cursor;
+}
+function setNestedPath(target, segments, value) {
+    let cursor = target;
+    for(let i = 0; i < segments.length - 1; i++){
+        const part = segments[i];
+        const existing = cursor[part];
+        if (existing === null || existing === undefined || typeof existing !== 'object') {
+            cursor[part] = {};
+        }
+        cursor = cursor[part];
+    }
+    cursor[segments[segments.length - 1]] = value;
+}

package/dist/lib/translate-prompt.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { TranslateRequest } from '../types.js';
+/**
+ * Single source of truth for the prompt + response schema shared by every
+ * AI-SDK-backed provider. Previously each provider duplicated this code
+ * (~100 lines × 4) with subtle drift.
+ *
+ * The Zod schema is enforced by `generateObject` — the model is required
+ * to produce an `items` array. Single-item, multi-item, doesn't matter:
+ * the response shape is structural, not parsed from a JSON string.
+ */
+export declare const TranslateResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TranslateResponseObject = z.infer<typeof TranslateResponseSchema>;
+export declare function buildSystemPrompt(request: TranslateRequest): string;
+export declare function buildUserMessage(request: TranslateRequest): string;
+/**
+ * Pre-call estimate of token usage and cost. Heuristic-only — `ai` SDK has
+ * no dry-run token counter. Each provider plugs in its own pricing table.
+ */
+export declare function estimateUsage(request: TranslateRequest, pricing?: {
+    input: number;
+    output: number;
+}): {
+    inputTokens: number;
+    estimatedCostUsd?: number;
+};