@purposeinplay/payload-ai-translate 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,672 @@
+import type { PayloadRequest } from 'payload';
+export type TranslationItemKind = 'plain' | 'inline' | 'block';
+export type TranslationItem = {
+    id: string;
+    text: string;
+    kind: TranslationItemKind;
+};
+export type TranslationContext = {
+    collectionSlug: string;
+    fieldPath: string;
+    documentTitle?: string;
+    formality?: 'formal' | 'informal';
+    hints?: Record<string, string>;
+};
+export type TranslateRequest = {
+    items: TranslationItem[];
+    sourceLocale: string;
+    targetLocale: string;
+    context: TranslationContext;
+    glossary?: Record<string, string>;
+    signal?: AbortSignal;
+};
+export type TranslationUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCostUsd?: number;
+    /**
+     * Provider-reported model id (e.g. `gpt-4o-mini`). Bubbled up from the
+     * provider's TranslateResponse so persistence sinks can record which
+     * model billed the work. Optional because some custom providers may
+     * not return a model name.
+     */
+    model?: string;
+};
+export type TranslatedItem = {
+    id: string;
+    text: string;
+};
+export type TranslateResponse = {
+    items: TranslatedItem[];
+    usage: TranslationUsage;
+    model: string;
+    latencyMs: number;
+};
+export type TranslationEstimate = {
+    inputTokens: number;
+    estimatedCostUsd?: number;
+};
+export type TranslationProvider = {
+    translate(request: TranslateRequest): Promise<TranslateResponse>;
+    estimate?(request: TranslateRequest): Promise<TranslationEstimate>;
+    /**
+     * Configured model identifier. Used by usage tracking to record what
+     * model would have run, even when `translate()` throws before the
+     * provider gets a response back. Optional for backwards compatibility
+     * with custom providers; built-in providers always set it.
+     */
+    model?: string;
+};
+export type TargetPolicy = 'mirror' | 'preserve';
+export type CostLimits = {
+    perCallCharLimit: number;
+    perDocCharCeiling: number;
+    bulkConfirmUsdThreshold: number;
+    /**
+     * Maximum translation units per provider call, independent of the char
+     * cap. Defaults to 500 (see `DEFAULT_PER_CALL_ITEM_LIMIT` in
+     * `translate.ts`). Exists because some providers' structured-output
+     * mode (notably Gemini 2.5 Flash via OpenRouter) silently stalls on
+     * response generation when the response items array grows past
+     * roughly 800-1000 entries — HTTP 200 returns in <2s but the body
+     * never finishes streaming, hitting the per-call timeout and failing
+     * the whole batch. The char cap doesn't catch this because short
+     * strings (nav labels, JSON keys) pack many items into modest byte
+     * counts: a translation-keys global with 1107 short strings fits
+     * comfortably in a 50k-char batch but trips the stall every time.
+     *
+     * Raise this only if you've verified your chosen model + structured
+     * output mode handles larger response arrays reliably.
+     */
+    perCallItemLimit?: number;
+};
+export type ConcurrencyLimits = {
+    perDocument: number;
+    perProvider: number;
+};
+export type RetryConfig = {
+    attempts: number;
+    backoffMs: number;
+};
+export type LexicalNodeRegistration = {
+    type: string;
+    translatable: boolean;
+    translatableAttributes?: string[];
+};
+export type AutomationConfig = {
+    trigger?: 'on-change' | 'on-publish';
+    mode?: 'async' | 'inline';
+    targetPolicy?: TargetPolicy;
+    diffOnly?: boolean;
+    coalescingWindowMs?: number;
+};
+export type AITranslatePluginConfig = {
+    collections?: string[];
+    globals?: string[];
+    sourceLocale: string;
+    targetLocales: string[];
+    /**
+     * Default provider used when no per-runtime override is configured.
+     * Required so the plugin can always translate, even before an admin
+     * has touched the `translation-settings` global.
+     */
+    provider: TranslationProvider;
+    /**
+     * Optional: a map of named providers that admins can choose between
+     * at runtime via the auto-registered `translation-settings` global.
+     *
+     * Each key becomes an option in the admin's "Active provider" select.
+     * Each value is a fully-built `TranslationProvider` (vendor + model
+     * baked in) — to expose multiple models for the same vendor, register
+     * them under different keys (e.g. `openai-mini`, `openai-4o`).
+     *
+     * When this map is non-empty, the plugin auto-registers the
+     * `translation-settings` global. When the global's `activeProvider`
+     * matches a key, that provider is used. Otherwise the plugin falls
+     * back to `provider`.
+     */
+    providers?: Record<string, TranslationProvider>;
+    costLimits: CostLimits;
+    excludeFields?: string[];
+    /**
+     * When true (default), URL-shaped paths (`**.url`) are appended to
+     * `excludeFields` so URL strings never reach the LLM. Sending URLs to
+     * the model wastes tokens and trips the verbatim-echo validator (a
+     * URL "translation" is the same URL). Set to `false` to translate
+     * URL fields anyway (rare — useful for locale-specific deep links).
+     */
+    excludeUrlFields?: boolean;
+    concurrency?: Partial<ConcurrencyLimits>;
+    retry?: Partial<RetryConfig>;
+    access?: {
+        /**
+         * Gate the `/ai-translate` and `/ai-translate/estimate` endpoints.
+         * Returns `true` to allow, `false` to return HTTP 403.
+         *
+         * **IMPORTANT:** the plugin's default behavior is "any authenticated
+         * user" — the built-in `aiTranslateAccess` helper (when consumers
+         * wire it via `access: { translate: aiTranslateAccess }`) only
+         * enforces a per-user rate limit, NOT a role check. If your CMS
+         * has editors vs admins, wrap the function with your role check:
+         *
+         * ```ts
+         * access: {
+         *   translate: ({ req }) => {
+         *     if (!req.user?.roles?.includes('admin')) return false;
+         *     return aiTranslateAccess({ req });
+         *   },
+         * }
+         * ```
+         *
+         * Translation requests can spend real money (LLM tokens) so the
+         * minimum default is intentionally permissive only because most
+         * consumers run a single-role admin setup. Multi-role consumers
+         * MUST add a role gate.
+         */
+        translate?: (args: {
+            req: PayloadRequest;
+        }) => boolean | Promise<boolean>;
+    };
+    onEvent?: (event: TranslationEvent) => void | Promise<void>;
+    onAlert?: (alert: TranslationAlert) => void | Promise<void>;
+    lexicalNodes?: LexicalNodeRegistration[];
+    enabled?: boolean;
+    automation?: AutomationConfig;
+    /** Show a translate button next to each localized field in the edit view. */
+    perFieldButton?: boolean;
+    /**
+     * Role names that count as "admin" for the plugin's admin-only field
+     * gates (the `_aiTranslateOptOut` checkbox and `_aiTranslateAutoLocales`
+     * select injected on every tracked surface). A user whose `roles`
+     * array intersects this list can edit those fields; others get
+     * read-only widgets.
+     *
+     * Defaults to `['admin']`. Set to your consumer's actual admin role
+     * value(s) if you use a different naming convention (e.g.
+     * `['super-admin', 'cms-admin']`). Pass `[]` to make the fields
+     * editable by everyone (NOT recommended — these fields gate LLM
+     * spend on a per-document basis).
+     *
+     * Note: this option controls FIELD-LEVEL admin gating only. The
+     * separate `access.translate` callback controls who can hit the
+     * manual translate endpoint — those concerns are intentionally
+     * decoupled so consumers can grant translate-button access to
+     * editors while keeping per-doc opt-out admin-only.
+     */
+    adminRoles?: string[];
+    quality?: QualityConfig;
+    /**
+     * Persist a row per translation job (succeeded or failed) into an
+     * auto-registered collection. Mirrors how `auditLogPlugin` registers its
+     * own `audit-logs` collection. Off by default — opt in via `enabled: true`.
+     */
+    usageTracking?: UsageTrackingConfig;
+    /**
+     * Override the auto-registered `translation-alerts` collection slug.
+     * The alerts collection is auto-registered when `usageTracking.enabled`
+     * is true (they're sibling features powering the Translation Hub).
+     * Defaults to `'translation-alerts'`. Holds rows for every
+     * `cost-guard-abort`, `persistent-failure`, and `provider-outage`
+     * event so the Hub can surface them in-app (consumer's `onAlert`
+     * callback continues to fire regardless).
+     */
+    alertsCollectionSlug?: string;
+    /**
+     * Detect manual edits to target-locale rows and skip overwriting them
+     * on the next translation pass. When enabled, the plugin auto-
+     * registers an `ai-translate-meta` sidecar collection holding a
+     * per-(collection, doc, locale, field) hash of the value it last
+     * wrote. Before each subsequent write, the plugin compares the
+     * current target value's hash to the stored one — divergence ⇒ a
+     * human edited the row, the field is skipped.
+     *
+     * Off by default to preserve the existing "always overwrite" behavior.
+     * Recommended for sites where editors hand-fix machine translations
+     * and want their edits preserved across publishes.
+     */
+    preserveManualEdits?: boolean;
+    /**
+     * Override the auto-registered sidecar collection slug used by
+     * `preserveManualEdits`. Defaults to `ai-translate-meta`. Only
+     * meaningful when `preserveManualEdits: true`.
+     */
+    manualEditCollectionSlug?: string;
+    /**
+     * Persist the in-memory job progress store to an auto-registered
+     * `ai-translate-jobs` sidecar collection. When enabled, every
+     * `createJob` / `updateJob` / `cleanup` operation mirrors to the
+     * database so admins can see what was in flight after a server
+     * restart.
+     *
+     * **NOT a full work-queue.** The translation closures themselves
+     * (req, doc, previousDoc) still live in process memory. A restart
+     * still drops the in-flight LLM call — this option just preserves
+     * the STATUS so admins can spot the ghost job and re-trigger.
+     *
+     * Off by default.
+     */
+    persistJobs?: boolean;
+    /**
+     * Override the auto-registered jobs-collection slug used by
+     * `persistJobs`. Defaults to `ai-translate-jobs`. Only meaningful
+     * when `persistJobs: true`.
+     */
+    jobsCollectionSlug?: string;
+    /**
+     * Override defaults for the auto-registered `translation-settings`
+     * global. Only meaningful when `providers` is configured.
+     */
+    settings?: import('./settings-global.js').TranslationSettingsConfig;
+    /**
+     * Bulk-translate engine configuration (v1.2.0+). Presence of this
+     * key auto-registers the bulk-translate sidecar collections
+     * (`bulk-translate-batches`, `bulk-translate-units`,
+     * `translation-daily-spend`, `translation-rate-limits`), exposes
+     * the `/api/translation-hub/bulk-translate` endpoints, and runs the
+     * `ensureBulkTranslateSchema` helper at boot to materialize the
+     * partial unique index that backs the F-DA-TOCTOU dedup invariant.
+     *
+     * Defaults to enabled when a `bulk` block is provided. Pass
+     * `enabled: false` to opt out explicitly (e.g. for environments
+     * where bulk translation should be disabled at the runtime layer).
+     *
+     * The real cost guards are `dailyUsdCap` + `requireTotp` — not
+     * this flag. See Design-2026-05-27-bulk-translate.md for the full
+     * design rationale.
+     */
+    bulk?: BulkTranslateConfig;
+    /** @internal Set by plugin factory — do not configure directly. */
+    _rateLimiter?: {
+        acquire(): Promise<void>;
+    };
+};
+export type UsageTrackingConfig = {
+    /** Master switch. Default: false (opt-in). */
+    enabled?: boolean;
+    /** Override the auto-registered collection slug. Default: 'translation-usage'. */
+    collectionSlug?: string;
+    /**
+     * Override the default admin-only read access. The default keeps cost data
+     * out of editors' hands by gating on a user role of `admin`.
+     */
+    access?: {
+        read?: import('payload').Access;
+    };
+};
+export type WriteMode = 'full' | 'minimal';
+export type TranslateDocumentOptions = {
+    collection: string;
+    id: string | number;
+    targetLocales?: string[];
+    targetPolicy?: TargetPolicy;
+    fields?: string[];
+    previousDoc?: Record<string, unknown>;
+    signal?: AbortSignal;
+    /**
+     * Locale-write scope. Default `'full'` includes all localized top-level
+     * fields in the update body so Payload's required-localized-field
+     * validation passes on a fresh target row. `'minimal'` writes only the
+     * fields that actually got translated — caller accepts that Payload
+     * may reject the write when other localized required fields are empty
+     * in the target locale. Useful for "translate one field, leave the
+     * rest exactly as the user has them" workflows where the target locale
+     * row is known to be fully populated already.
+     */
+    writeMode?: WriteMode;
+    /**
+     * Reuse an existing job in the progress store instead of creating a new one.
+     * Used by the after-change hook to avoid duplicate jobs (one phantom from the
+     * hook for instant UI feedback, one real from the API call).
+     */
+    jobId?: string;
+    /**
+     * Originating PayloadRequest from the user-facing operation. When passed,
+     * locale writes inherit `req.user`/`req.transactionID` so downstream hooks
+     * (e.g. audit-log) can attribute the changes correctly. Optional because
+     * background jobs and tests may invoke `translateDocument` without a req.
+     */
+    req?: PayloadRequest;
+    /**
+     * Read the latest draft when the collection has drafts enabled. Defaults
+     * to true (the typical caller is the admin UI editing a draft). No-op for
+     * non-versioned collections.
+     */
+    draft?: boolean;
+    /**
+     * Per-call override of the field-level guards that normally short-circuit
+     * a translate. When `true`:
+     *   - The hash-skip path (BUG-21) — which skips fields whose source AND
+     *     target hashes match the last successful write — is DISABLED. Every
+     *     translatable field is sent to the LLM.
+     *   - The manual-edit preserve guard — which drops fields whose current
+     *     target value diverges from the stored hash (assumed to be a
+     *     human-edited target) — is DISABLED. The new translation overwrites
+     *     the editor's manual change.
+     * Defaults to `false`. The bulk-translate worker passes `true` when the
+     * batch was enqueued with `mode: 'force'` so the UI's "Force re-translate
+     * (includes docs already up to date)" checkbox semantically matches what
+     * actually happens. Hash recording after a successful write stays active
+     * regardless — the next non-force run still benefits from the updated
+     * hashes.
+     */
+    force?: boolean;
+};
+export type TranslateGlobalOptions = {
+    global: string;
+    targetLocales?: string[];
+    targetPolicy?: TargetPolicy;
+    fields?: string[];
+    signal?: AbortSignal;
+    /** See `TranslateDocumentOptions.writeMode`. */
+    writeMode?: WriteMode;
+    /**
+     * Previous version of the global doc (typically the value before the save
+     * that triggered translation). When provided, fields whose hashed content
+     * matches the previous version are skipped — same diffOnly behavior the
+     * collections API has.
+     */
+    previousDoc?: Record<string, unknown>;
+    /**
+     * Reuse an existing job from the progress store. The on-change hook seeds
+     * one for instant UI feedback and threads it through here.
+     */
+    jobId?: string;
+    /** See `TranslateDocumentOptions.req`. */
+    req?: PayloadRequest;
+    /**
+     * When `true`, bypass the BUG-21 hash-skip path so every translatable
+     * top-level field is sent to the LLM regardless of cached hashes. Used
+     * by `bulk-translate mode: 'force'` and equivalent admin actions where
+     * the editor explicitly asks for a re-translate. Hash bookkeeping
+     * after the write still runs so the next non-force call benefits from
+     * fresh hashes. Mirrors `TranslateDocumentOptions.force`.
+     */
+    force?: boolean;
+};
+export type FieldLocaleResult = {
+    fieldPath: string;
+    locale: string;
+    status: 'success' | 'failed' | 'skipped';
+    error?: string;
+    /**
+     * Source-locale text for this field-locale entry. Populated on
+     * `status: 'skipped'` results so the persistence layer can surface the
+     * raw value to editors via `softSkippedFields[].sourceValue`. Optional
+     * on success/failed (renderer doesn't need it there) and on legacy code
+     * paths that haven't been updated to forward it.
+     */
+    sourceValue?: string;
+    /**
+     * Editor-facing code (see `EditorErrorCode` in `lib/error-messages.ts`)
+     * classifying the failure or soft-skip reason. The UI keys off this
+     * to render a friendly message; `error` is kept as the raw provider /
+     * validator string for the "Show technical details" disclosure.
+     * Set on every entry with `status !== 'success'`. Optional on legacy
+     * data — UI falls back to a generic message when absent.
+     */
+    errorCode?: string;
+    characterCount?: number;
+    durationMs?: number;
+    /**
+     * Final value written to the target locale for this field. Returned only
+     * for plain `text`/`textarea` results so the client can patch the form
+     * state without a round-trip. Omitted for richText/blocks where the
+     * structure can't be applied via a flat `setValue`.
+     */
+    translatedText?: string;
+};
+export type TranslateDocumentResult = {
+    jobId?: string;
+    documentId: string | number;
+    collection: string;
+    sourceLocale: string;
+    /**
+     * Cumulative provider-call latency for this translation in milliseconds,
+     * summed across every batch across every target locale. Measures ONLY
+     * actual LLM round-trip time — excludes token-bucket wait, provider
+     * rate-limit backoff, and queue scheduling. Used by the bulk worker
+     * to populate `bulk_translate_units.processingDurationMs`; usable by
+     * any caller that wants honest "how long did the AI take" signal.
+     */
+    providerLatencyMs?: number;
+    /**
+     * Field-locale entries that were actually persisted to the database.
+     * Excludes fields the plugin preserved as manual edits — those land
+     * in `preserved` instead. Pre-1.2.0 builds put preserved entries here
+     * too, which misled downstream automation about what was written.
+     */
+    succeeded: FieldLocaleResult[];
+    /**
+     * Field-locale entries the manual-edit guard kept out of the write
+     * because the target value diverged from the plugin's last-written
+     * hash. Distinct from `succeeded` so callers can tell "translated and
+     * written" from "translated but skipped to preserve editor work."
+     *
+     * Empty when `preserveManualEdits` is off.
+     */
+    preserved: FieldLocaleResult[];
+    failed: FieldLocaleResult[];
+    usage: TranslationUsage;
+};
+export type TranslationEventType = 'translation.started' | 'translation.field' | 'translation.succeeded' | 'translation.failed';
+export type SkippedFieldReport = {
+    fieldPath: string;
+    locale: string;
+    /**
+     * Validator reason (e.g. "Translation matches source verbatim — model
+     * likely echoed input for ..."). Surfaced as the raw "Show technical
+     * details" text — UI renders the friendly version via `reasonCode`.
+     */
+    reason?: string;
+    /**
+     * Editor-facing code (one of the `soft-skip.*` values from
+     * `lib/error-messages.ts`). UI keys off this to render a friendly
+     * message via `editorMessageFor(code, ctx)`. Optional on legacy data.
+     */
+    reasonCode?: string;
+    /**
+     * The source-locale text the AI declined to translate. Surfaced in the
+     * Hub so editors can see WHAT was kept (e.g. "Wheel Of") without opening
+     * the doc. Optional on legacy rows; capped at 500 chars so a rogue
+     * richText body can't bloat the row.
+     */
+    sourceValue?: string;
+};
+export type TranslationEvent = {
+    type: TranslationEventType;
+    documentId: string | number;
+    collection: string;
+    sourceLocale: string;
+    targetLocales: string[];
+    timestamp: Date;
+    fields?: FieldLocaleResult[];
+    usage?: TranslationUsage;
+    error?: string;
+    canary?: boolean;
+    /**
+     * Per-field soft skips (verbatim echo, validator misses). Doc-level
+     * `type` may still be `translation.succeeded` when the only failures are
+     * skips — soft skips don't drive doc-level status to failed, but the
+     * editor needs to know which fields silently stayed in source.
+     */
+    skippedFields?: SkippedFieldReport[];
+};
+export type TranslationAlertType = 'translation.persistent-failure' | 'translation.cost-guard-abort' | 'translation.provider-outage';
+export type TranslationAlert = {
+    type: TranslationAlertType;
+    message: string;
+    documentId?: string | number;
+    collection?: string;
+    timestamp: Date;
+    metadata?: Record<string, unknown>;
+    /**
+     * Editor-facing code (one of the `alert.*` or `cost-guard.*` values
+     * from `lib/error-messages.ts`). When set, AlertBanner renders the
+     * friendly title/body via `editorMessageFor(code, context)` instead
+     * of the raw `message` string. `message` is still written for
+     * back-compat with the consumer `onAlert` callback (Slack/email).
+     * Flattened into the persisted row's `metadata.code`.
+     */
+    code?: string;
+    /**
+     * Context for templating the code's message (count, locale, spent,
+     * cap, etc.). Flattened into the persisted row's `metadata.context`.
+     */
+    context?: Record<string, unknown>;
+};
+export type ValidationConfig = {
+    minLengthRatio?: number;
+    maxLengthRatio?: number;
+    minSourceLength?: number;
+    extraRefusalPatterns?: RegExp[];
+    extraInjectionPatterns?: RegExp[];
+};
+export type TranslationSample = {
+    documentId: string | number;
+    collection: string;
+    fieldPath: string;
+    sourceLocale: string;
+    targetLocale: string;
+    sourceText: string;
+    translatedText: string;
+    model: string;
+    timestamp: Date;
+};
+export type SamplingConfig = {
+    rate: number;
+    onSample?: (sample: TranslationSample) => void | Promise<void>;
+};
+export type QualityConfig = {
+    validation?: ValidationConfig;
+    sampling?: SamplingConfig;
+    canaryLocale?: string;
+};
+export type TranslatableFieldType = 'text' | 'textarea' | 'richText' | 'json' | 'group' | 'array' | 'blocks';
+export type TranslatableField = {
+    path: string;
+    type: TranslatableFieldType;
+    localized: boolean;
+};
+export type TranslationUnit = {
+    id: string;
+    fieldPath: string;
+    text: string;
+    kind: TranslationItemKind;
+};
+export type CostGuardError = Error & {
+    code: 'PER_CALL_LIMIT' | 'PER_DOC_CEILING';
+    characterCount: number;
+    limit: number;
+};
+/**
+ * Bulk-translate batch lifecycle event. Fires on terminal state
+ * transitions (completed / partial / failed / cancelled / reverted).
+ * Consumer-supplied callbacks can use this to plug into webhook
+ * notification surfaces (Slack, email, etc).
+ */
+export type BulkTranslateBatchEvent = {
+    batchId: string;
+    status: 'success' | 'partial' | 'failed' | 'cancelled' | 'reverted';
+    scope: {
+        collections?: string[];
+        globals?: string[];
+        locales?: string[];
+        mode: 'changed' | 'force' | 'canary';
+    };
+    counts: {
+        total: number;
+        completed: number;
+        failed: number;
+        skipped: number;
+    };
+    costUsd: {
+        estimated: number;
+        actual: number;
+    };
+    triggeredByUserId: string;
+    triggeredByEmail?: string;
+    durationMs: number;
+};
+export type BulkTranslateConfig = {
+    /**
+     * Master switch for the bulk-translate engine. Defaults to `true`
+     * when the `bulk` block is present in plugin config — pass
+     * `enabled: false` to opt out at the runtime layer (e.g. in
+     * environments where bulk operations should be disabled but the
+     * surrounding plugin config stays the same). The real cost guards
+     * are `dailyUsdCap` + `requireTotp`.
+     */
+    enabled?: boolean;
+    /**
+     * Collection slugs to exclude from bulk operations even if they're
+     * in the plugin's `collections` list. Decision #32: `users` is
+     * recommended here for any consumer where `users.bio` carries
+     * personally-identifying content (employee bios etc).
+     */
+    excludeCollections?: string[];
+    /**
+     * Hard ceiling on aggregate USD spend per UTC day (Decision #14 +
+     * F-SEC-TOTP-BYPASS). Applies to bulk-translate, per-doc retry,
+     * AND the plugin coalesce path. The env var
+     * `BULK_TRANSLATE_DAILY_USD_CAP` overrides this if set. Default
+     * is $50.
+     */
+    dailyUsdCap?: number;
+    /**
+     * Require a TOTP code on the bulk-translate POST endpoint
+     * (Decision #13 v2). Friction, not the primary security boundary
+     * — the daily USD cap is the real enforcement. Defaults to `true`
+     * when a TOTP plugin is detected at boot.
+     */
+    requireTotp?: boolean;
+    /**
+     * Default canary sample size when `mode: 'canary'` is selected
+     * without an explicit limit (Decision #26 + F-DA-CANARY).
+     * Selection is random-stratified across configured collections.
+     * Defaults to 10.
+     */
+    canaryDefaultSize?: number;
+    /**
+     * Fires on every terminal batch transition. Use for Slack /
+     * email notifications. Best-effort — exceptions are caught and
+     * logged, never block batch completion.
+     */
+    onBatchComplete?: (event: BulkTranslateBatchEvent) => void | Promise<void>;
+    /**
+     * Fires when a batch enters `failed` terminal state (zero
+     * successes). Distinct from `onBatchComplete` (which fires on all
+     * terminal states) so consumers can wire different alerting
+     * priorities.
+     */
+    onBatchFailed?: (event: BulkTranslateBatchEvent) => void | Promise<void>;
+    /**
+     * Fires when the daily USD cap rejects a request. Lets consumers
+     * page on-call before the cap silently locks out a day's work.
+     */
+    onCapExceeded?: (info: {
+        todaySpentUsd: number;
+        capUsd: number;
+        rejectedEstimateUsd: number;
+        requestPath: 'bulk-endpoint' | 'per-doc-retry' | 'coalesce';
+    }) => void | Promise<void>;
+    /**
+     * Slug override for the bulk-translate units collection. Reads default
+     * from `DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG`. Only set if the
+     * consumer renamed the collection.
+     */
+    unitsCollectionSlug?: string;
+    /**
+     * Interval (ms) between janitor sweeps that reclaim stuck `running`
+     * units back to `pending` when the worker crashes or the process
+     * restarts. Default 5 minutes. Set to `0` to disable the periodic
+     * sweep (the boot sweep still runs on every onInit).
+     *
+     * The janitor mechanism (see `tasks/bulk-translate-janitor.ts`) is
+     * dynamic-threshold: it only resets rows older than
+     * `max(10min, 2 × p99-LLM-latency)`, so legitimately slow
+     * translations are never interrupted. Lowering this interval below
+     * 1 minute is a foot-gun — the sweep walks the units table; do not
+     * set < 30_000.
+     */
+    janitorIntervalMs?: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export { };

package/dist/usage-collection.d.ts

@@ -0,0 +1,14 @@
+import type { Access, CollectionConfig } from 'payload';
+/**
+ * Factory for the auto-registered `translation-usage` collection.
+ *
+ * The plugin pushes this collection onto `config.collections` when
+ * `usageTracking.enabled` is true. Every translation job — succeeded or
+ * failed — writes one row from inside `lib/persist-usage.ts`. Cost data
+ * is treated as admin-only by default: `admin.hidden` keeps the entry
+ * out of the editor nav, and `access.read` blocks API reads even via
+ * direct URL.
+ *
+ * Mirrors the audit-log plugin's `createAuditLogsCollection` pattern.
+ */
+export declare function createUsageCollection(readAccess?: Access, collectionSlug?: string): CollectionConfig;