@verbatra/sdk 0.4.0 → 0.4.2

package/README.md

@@ -10,6 +10,8 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@verbatra/sdk"><img src="https://img.shields.io/npm/v/@verbatra/sdk?label=%40verbatra%2Fsdk" alt="@verbatra/sdk npm version" /></a>
+  <a href="https://github.com/mariokreitz/verbatra/actions/workflows/ci.yml"><img src="https://github.com/mariokreitz/verbatra/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <a href="https://github.com/mariokreitz/verbatra/actions/workflows/e2e.yml"><img src="https://github.com/mariokreitz/verbatra/actions/workflows/e2e.yml/badge.svg?branch=main" alt="E2E" /></a>
   <a href="https://codecov.io/gh/mariokreitz/verbatra"><img src="https://codecov.io/gh/mariokreitz/verbatra/graph/badge.svg" alt="Coverage" /></a>
   <a href="https://github.com/mariokreitz/verbatra/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
 </p>

package/dist/index.d.cts

@@ -1,7 +1,186 @@
-export { SupportedFormat } from '@verbatra/core';
-import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
-import { AdapterRegistry } from '@verbatra/format-adapters';
+import Anthropic from '@anthropic-ai/sdk';
+import { Interactions } from '@google/genai';
+import OpenAI from 'openai';
+
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema$1: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already
+ * extracted; core never derives them from the value.
+ */
+declare const translationEntrySchema$1: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    value: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    meaning: z.ZodOptional<z.ZodString>;
+    placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    isPlural: z.ZodBoolean;
+}, z.core.$strip>;
+/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
+
+/**
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ */
+interface PlaceholderIntegrityResult {
+    /** True when nothing is missing or extra and order is preserved. */
+    readonly matches: boolean;
+    /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
+    readonly missing: readonly string[];
+    /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
+    readonly extra: readonly string[];
+    /** Same multiset present in both, but in a different order. */
+    readonly reordered: boolean;
+}
+
+/** A provider is either a prompt-driven LLM or a dedicated machine-translation API. */
+type ProviderKind = "llm" | "machine-translation";
+/** Target tone for a translation. Maps to formality for machine-translation providers. */
+type Tone = "formal" | "informal" | "neutral";
+/**
+ * Produces the placeholder set of a value for the output integrity check. Supplied
+ * by the caller (the SDK) so it matches the entries' format; ai-providers never
+ * derives placeholders itself.
+ */
+type PlaceholderExtractor = (value: string) => readonly string[];
+/**
+ * A batch translation request. Format- and provider-neutral: it carries no prompt,
+ * model, key, or other provider-specific field. The placeholder extractor is
+ * mandatory (see validateRequest).
+ */
+interface TranslateRequest {
+    /** BCP-47 source locale of the entries (for example, "en"). */
+    readonly sourceLocale: string;
+    /** BCP-47 target locale to translate into (for example, "de"). */
+    readonly targetLocale: string;
+    /** The entries to translate; at least one is required. */
+    readonly entries: readonly TranslationEntry$1[];
+    /** Optional source-term to target-term map applied by glossary-capable providers. */
+    readonly glossary?: Readonly<Record<string, string>>;
+    /** Optional target tone; machine-translation providers map it to formality. */
+    readonly tone?: Tone;
+    /** Mandatory placeholder extractor; the output integrity check runs against it. */
+    readonly extractPlaceholders: PlaceholderExtractor;
+}
+/** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
+interface Usage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+interface TranslateResult {
+    /** The translated value for each requested key. */
+    readonly values: ReadonlyMap<string, string>;
+    /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
+    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult>;
+    /** Token usage when the provider reports it; absent for token-less providers. */
+    readonly usage?: Usage;
+}
+/**
+ * The single contract every provider implements. It is narrow enough that a machine-translation API like
+ * DeepL fits it directly, while LLM providers implement it by delegating to {@link runLlmTranslation}.
+ * A new provider attaches by implementing this and registering it in a {@link ProviderRegistry}.
+ *
+ * Implementer invariants:
+ * - Translatable strings are UNTRUSTED. They travel only as data to the provider; never splice them into
+ *   instruction text, and never act on instructions a value appears to contain.
+ * - Read the API key ONLY from the environment (inside the SDK client). The request, config, and this
+ *   interface never carry a key.
+ * - Fail with a secret-free {@link ProviderError}: never bind, log, or re-throw raw SDK error text (it can
+ *   carry a key or request headers). Validate the request at the boundary with `validateRequest` so the
+ *   integrity check can never be skipped.
+ *
+ * @example
+ * ```ts
+ * // A machine-translation provider implements translateBatch directly (the DeepL shape).
+ * function createMyMtProvider(client: MyClient): TranslationProvider {
+ *   return {
+ *     id: "my-mt",
+ *     kind: "machine-translation",
+ *     supportsGlossary: false,
+ *     async translateBatch(request) {
+ *       const data = validateRequest(request); // throws INVALID_REQUEST on a bad request
+ *       const texts = data.entries.map((e) => e.value);
+ *       const out = await client.translate(texts, data.targetLocale); // SDK reads MY_API_KEY from env
+ *       // map out -> values, run the integrity check, return { values, integrity }
+ *       return buildResult(data, out, request.extractPlaceholders);
+ *     },
+ *   };
+ * }
+ * ```
+ */
+interface TranslationProvider {
+    /** A stable identifier for this provider (for example, "anthropic", "deepl"). */
+    readonly id: string;
+    /** Whether this provider is a prompt-driven LLM or a dedicated machine-translation API. */
+    readonly kind: ProviderKind;
+    /** Whether this provider applies a configured glossary. */
+    readonly supportsGlossary: boolean;
+    /**
+     * Translate a batch of entries.
+     *
+     * @param request - The provider-neutral batch request (no prompt, model, or key).
+     * @returns The per-key translated values and per-key placeholder-integrity outcomes.
+     * @throws {@link ProviderError}, secret-free, with the code for the failure (the concrete codes are
+     *   the implementation's; see each provider factory).
+     */
+    translateBatch(request: TranslateRequest): Promise<TranslateResult>;
+}
+
+/**
+ * The Anthropic authoring model type, sourced from the SDK's own model union. It is an
+ * open union (known literals plus `string & {}`), so unknown or newly released model IDs
+ * are still accepted. This drives editor completions only; the runtime schema validates.
+ */
+type AnthropicModel = Anthropic.Messages.Model;
+/**
+ * Stable codes for the DeepL graceful-degradation notices, DeepL only. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ */
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+/**
+ * An observable, structured signal that something was gracefully degraded (not an
+ * error). Carries only a stable code and a static message, never a key or content.
+ * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
+ */
+interface ProviderNotice {
+    /** The stable {@link ProviderNoticeCode} for what was degraded. */
+    readonly code: ProviderNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+
+/**
+ * The Gemini authoring model type, sourced from the installed SDK's own model union so
+ * verbatra restates no model IDs. It is an open union, so unknown model IDs are still
+ * accepted. Type-only: it informs editor completions and is never validated at runtime,
+ * where the schema stays `z.string().min(1)`.
+ */
+type GeminiModel = Interactions.Model;
+
+/**
+ * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model
+ * union. It drives editor completions only; it is never read at runtime, and the
+ * runtime schema stays `z.string().min(1)`.
+ */
+type OpenAiModel = OpenAI.ChatModel;
 
 /**
  * The provider section of the config: a discriminated union over the provider id, reusing each
@@ -221,6 +400,171 @@ declare class SdkError extends Error {
     constructor(code: SdkErrorCode, message: string);
 }
 
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat = z.infer<typeof supportedFormatSchema>;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already
+ * extracted; core never derives them from the value.
+ */
+declare const translationEntrySchema: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    value: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    meaning: z.ZodOptional<z.ZodString>;
+    placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    isPlural: z.ZodBoolean;
+}, z.core.$strip>;
+/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+type TranslationEntry = Readonly<z.infer<typeof translationEntrySchema>>;
+/** All translation entries for one locale and namespace, keyed by entry key. */
+interface LocaleResource {
+    /** The locale these entries belong to (for example, "en" or "de"). */
+    readonly locale: string;
+    /** The namespace these entries belong to. */
+    readonly namespace: string;
+    /** The source format the resource came from, for round-trip fidelity. */
+    readonly format: SupportedFormat;
+    /** Entries addressable by key. */
+    readonly entries: ReadonlyMap<string, TranslationEntry>;
+}
+
+/**
+ * The result of reading a file into core's intermediate representation.
+ */
+interface ReadResult {
+    /** The parsed locale resource. */
+    readonly resource: LocaleResource;
+    /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
+    readonly invalidIcuKeys: readonly string[];
+}
+/**
+ * The contract every format adapter implements. A new format attaches by implementing this interface
+ * and registering it in an {@link AdapterRegistry}.
+ *
+ * For a JSON-family format, implement via {@link createJsonFileAdapter} rather than from scratch. A
+ * non-JSON format implements this interface directly and first needs its format added to core's
+ * `SupportedFormat`.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * const resolution = registry.resolve("locales/en.json", { format: "i18next-json" });
+ * if (resolution.status === "resolved") {
+ *   const { resource } = await resolution.adapter.read("locales/en.json", "en");
+ *   await resolution.adapter.write(resource, "locales/en.json");
+ * }
+ * ```
+ */
+interface FormatAdapter {
+    /** The single format this adapter handles (a `SupportedFormat` from core). */
+    readonly format: SupportedFormat;
+    /**
+     * Detect whether this adapter can handle a file, by path extension and an optional content sample.
+     * Best-effort and side-effect-free; it reads nothing from disk.
+     *
+     * @param filePath - The path of the file under consideration.
+     * @param sample - An optional leading content sample to aid detection.
+     * @returns True if this adapter could handle the file. Several adapters may return true for the same
+     *   file (all JSON adapters claim `.json`); the caller disambiguates by explicit format.
+     */
+    canHandle(filePath: string, sample?: string): boolean;
+    /**
+     * Read a file into a {@link LocaleResource} plus its message-validity result.
+     *
+     * @param filePath - The file to read.
+     * @param locale - The locale to tag the resource with.
+     * @returns The parsed resource and the keys whose values are invalid for the format.
+     * @throws {@link AdapterError} when the content is malformed, oversized, or structurally invalid
+     *   (the implementation names the specific codes). A missing or unopenable path instead rejects with
+     *   the underlying filesystem error.
+     */
+    read(filePath: string, locale: string): Promise<ReadResult>;
+    /**
+     * Write a {@link LocaleResource} back to a file, preserving key order and structure, atomically.
+     *
+     * @param resource - The resource to serialize.
+     * @param filePath - The destination file.
+     * @throws {@link AdapterError} if the resource cannot be represented in the format; rejects with the
+     *   underlying filesystem error on a write failure.
+     */
+    write(resource: LocaleResource, filePath: string): Promise<void>;
+    /**
+     * Extract the format's placeholder tokens from a single value, resolving nothing.
+     *
+     * @param value - The translatable string to scan.
+     * @returns The placeholder tokens found, in document order. Does not throw.
+     */
+    extractPlaceholders(value: string): readonly string[];
+    /**
+     * Validate a single value against the format's message syntax before it is written. Non-ICU formats
+     * (i18next, vue-i18n, ngx-translate) treat every value as valid and return true.
+     *
+     * @param value - The candidate translated value to validate.
+     * @returns True when the value is valid for the format's message syntax. Does not throw; an
+     *   unparseable value returns false.
+     */
+    validateMessage(value: string): boolean;
+}
+
+/** Outcome of resolving an adapter for a file. Structured; never throws. */
+type AdapterResolution = {
+    readonly status: "resolved";
+    readonly adapter: FormatAdapter;
+} | {
+    readonly status: "no-match";
+    readonly filePath: string;
+    readonly triedFormats: readonly SupportedFormat[];
+} | {
+    readonly status: "ambiguous";
+    readonly filePath: string;
+    readonly candidates: readonly SupportedFormat[];
+};
+/** Options for {@link AdapterRegistry.resolve}: select a format explicitly, or aid detection. */
+interface ResolveOptions {
+    /** A content sample to aid detection. */
+    readonly sample?: string;
+    /** Bypass detection and select this format explicitly. */
+    readonly format?: SupportedFormat;
+}
+/**
+ * Holds the registered adapters and resolves one for a file. Open for extension:
+ * adapters attach through register without changing resolution logic.
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    /**
+     * Register an adapter.
+     *
+     * @param adapter - The adapter to add.
+     * @returns This registry, for chaining.
+     */
+    register(adapter: FormatAdapter): this;
+    private formats;
+    private resolveByFormat;
+    private resolveByDetection;
+    /**
+     * Resolve the adapter for a file, by explicit format when given, otherwise by detection.
+     *
+     * @param filePath - The file to resolve an adapter for.
+     * @param options - `format` selects explicitly and skips detection; `sample` aids detection.
+     * @returns A structured {@link AdapterResolution}: `resolved`, `no-match`, or `ambiguous`. Never
+     *   throws; an unresolvable file is a status, not an exception.
+     */
+    resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
+}
+
 /** Outcome of a bounded read: the content, or why it could not be read in bounds. */
 type BoundedFileRead = {
     readonly kind: "ok";
@@ -706,4 +1050,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate, verbatraConfigSchema, watch };

package/dist/index.d.ts

@@ -1,7 +1,186 @@
-export { SupportedFormat } from '@verbatra/core';
-import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
-import { AdapterRegistry } from '@verbatra/format-adapters';
+import Anthropic from '@anthropic-ai/sdk';
+import { Interactions } from '@google/genai';
+import OpenAI from 'openai';
+
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema$1: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already
+ * extracted; core never derives them from the value.
+ */
+declare const translationEntrySchema$1: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    value: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    meaning: z.ZodOptional<z.ZodString>;
+    placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    isPlural: z.ZodBoolean;
+}, z.core.$strip>;
+/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
+
+/**
+ * Result of comparing source placeholders against translated-output placeholders as MULTISETS
+ * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ */
+interface PlaceholderIntegrityResult {
+    /** True when nothing is missing or extra and order is preserved. */
+    readonly matches: boolean;
+    /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
+    readonly missing: readonly string[];
+    /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
+    readonly extra: readonly string[];
+    /** Same multiset present in both, but in a different order. */
+    readonly reordered: boolean;
+}
+
+/** A provider is either a prompt-driven LLM or a dedicated machine-translation API. */
+type ProviderKind = "llm" | "machine-translation";
+/** Target tone for a translation. Maps to formality for machine-translation providers. */
+type Tone = "formal" | "informal" | "neutral";
+/**
+ * Produces the placeholder set of a value for the output integrity check. Supplied
+ * by the caller (the SDK) so it matches the entries' format; ai-providers never
+ * derives placeholders itself.
+ */
+type PlaceholderExtractor = (value: string) => readonly string[];
+/**
+ * A batch translation request. Format- and provider-neutral: it carries no prompt,
+ * model, key, or other provider-specific field. The placeholder extractor is
+ * mandatory (see validateRequest).
+ */
+interface TranslateRequest {
+    /** BCP-47 source locale of the entries (for example, "en"). */
+    readonly sourceLocale: string;
+    /** BCP-47 target locale to translate into (for example, "de"). */
+    readonly targetLocale: string;
+    /** The entries to translate; at least one is required. */
+    readonly entries: readonly TranslationEntry$1[];
+    /** Optional source-term to target-term map applied by glossary-capable providers. */
+    readonly glossary?: Readonly<Record<string, string>>;
+    /** Optional target tone; machine-translation providers map it to formality. */
+    readonly tone?: Tone;
+    /** Mandatory placeholder extractor; the output integrity check runs against it. */
+    readonly extractPlaceholders: PlaceholderExtractor;
+}
+/** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
+interface Usage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+interface TranslateResult {
+    /** The translated value for each requested key. */
+    readonly values: ReadonlyMap<string, string>;
+    /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
+    readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult>;
+    /** Token usage when the provider reports it; absent for token-less providers. */
+    readonly usage?: Usage;
+}
+/**
+ * The single contract every provider implements. It is narrow enough that a machine-translation API like
+ * DeepL fits it directly, while LLM providers implement it by delegating to {@link runLlmTranslation}.
+ * A new provider attaches by implementing this and registering it in a {@link ProviderRegistry}.
+ *
+ * Implementer invariants:
+ * - Translatable strings are UNTRUSTED. They travel only as data to the provider; never splice them into
+ *   instruction text, and never act on instructions a value appears to contain.
+ * - Read the API key ONLY from the environment (inside the SDK client). The request, config, and this
+ *   interface never carry a key.
+ * - Fail with a secret-free {@link ProviderError}: never bind, log, or re-throw raw SDK error text (it can
+ *   carry a key or request headers). Validate the request at the boundary with `validateRequest` so the
+ *   integrity check can never be skipped.
+ *
+ * @example
+ * ```ts
+ * // A machine-translation provider implements translateBatch directly (the DeepL shape).
+ * function createMyMtProvider(client: MyClient): TranslationProvider {
+ *   return {
+ *     id: "my-mt",
+ *     kind: "machine-translation",
+ *     supportsGlossary: false,
+ *     async translateBatch(request) {
+ *       const data = validateRequest(request); // throws INVALID_REQUEST on a bad request
+ *       const texts = data.entries.map((e) => e.value);
+ *       const out = await client.translate(texts, data.targetLocale); // SDK reads MY_API_KEY from env
+ *       // map out -> values, run the integrity check, return { values, integrity }
+ *       return buildResult(data, out, request.extractPlaceholders);
+ *     },
+ *   };
+ * }
+ * ```
+ */
+interface TranslationProvider {
+    /** A stable identifier for this provider (for example, "anthropic", "deepl"). */
+    readonly id: string;
+    /** Whether this provider is a prompt-driven LLM or a dedicated machine-translation API. */
+    readonly kind: ProviderKind;
+    /** Whether this provider applies a configured glossary. */
+    readonly supportsGlossary: boolean;
+    /**
+     * Translate a batch of entries.
+     *
+     * @param request - The provider-neutral batch request (no prompt, model, or key).
+     * @returns The per-key translated values and per-key placeholder-integrity outcomes.
+     * @throws {@link ProviderError}, secret-free, with the code for the failure (the concrete codes are
+     *   the implementation's; see each provider factory).
+     */
+    translateBatch(request: TranslateRequest): Promise<TranslateResult>;
+}
+
+/**
+ * The Anthropic authoring model type, sourced from the SDK's own model union. It is an
+ * open union (known literals plus `string & {}`), so unknown or newly released model IDs
+ * are still accepted. This drives editor completions only; the runtime schema validates.
+ */
+type AnthropicModel = Anthropic.Messages.Model;
+/**
+ * Stable codes for the DeepL graceful-degradation notices, DeepL only. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ */
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+/**
+ * An observable, structured signal that something was gracefully degraded (not an
+ * error). Carries only a stable code and a static message, never a key or content.
+ * Surfaced as result data, never thrown; callers inspect it but need not treat it as a failure.
+ */
+interface ProviderNotice {
+    /** The stable {@link ProviderNoticeCode} for what was degraded. */
+    readonly code: ProviderNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+
+/**
+ * The Gemini authoring model type, sourced from the installed SDK's own model union so
+ * verbatra restates no model IDs. It is an open union, so unknown model IDs are still
+ * accepted. Type-only: it informs editor completions and is never validated at runtime,
+ * where the schema stays `z.string().min(1)`.
+ */
+type GeminiModel = Interactions.Model;
+
+/**
+ * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model
+ * union. It drives editor completions only; it is never read at runtime, and the
+ * runtime schema stays `z.string().min(1)`.
+ */
+type OpenAiModel = OpenAI.ChatModel;
 
 /**
  * The provider section of the config: a discriminated union over the provider id, reusing each
@@ -221,6 +400,171 @@ declare class SdkError extends Error {
     constructor(code: SdkErrorCode, message: string);
 }
 
+/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+declare const supportedFormatSchema: z.ZodEnum<{
+    "i18next-json": "i18next-json";
+    "vue-i18n-json": "vue-i18n-json";
+    "next-intl-json": "next-intl-json";
+    "ngx-translate-json": "ngx-translate-json";
+    xliff: "xliff";
+    yaml: "yaml";
+    arb: "arb";
+}>;
+/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+type SupportedFormat = z.infer<typeof supportedFormatSchema>;
+
+/**
+ * A single, format-neutral translation unit. Placeholders are supplied already
+ * extracted; core never derives them from the value.
+ */
+declare const translationEntrySchema: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    value: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    meaning: z.ZodOptional<z.ZodString>;
+    placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    isPlural: z.ZodBoolean;
+}, z.core.$strip>;
+/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+type TranslationEntry = Readonly<z.infer<typeof translationEntrySchema>>;
+/** All translation entries for one locale and namespace, keyed by entry key. */
+interface LocaleResource {
+    /** The locale these entries belong to (for example, "en" or "de"). */
+    readonly locale: string;
+    /** The namespace these entries belong to. */
+    readonly namespace: string;
+    /** The source format the resource came from, for round-trip fidelity. */
+    readonly format: SupportedFormat;
+    /** Entries addressable by key. */
+    readonly entries: ReadonlyMap<string, TranslationEntry>;
+}
+
+/**
+ * The result of reading a file into core's intermediate representation.
+ */
+interface ReadResult {
+    /** The parsed locale resource. */
+    readonly resource: LocaleResource;
+    /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
+    readonly invalidIcuKeys: readonly string[];
+}
+/**
+ * The contract every format adapter implements. A new format attaches by implementing this interface
+ * and registering it in an {@link AdapterRegistry}.
+ *
+ * For a JSON-family format, implement via {@link createJsonFileAdapter} rather than from scratch. A
+ * non-JSON format implements this interface directly and first needs its format added to core's
+ * `SupportedFormat`.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * const resolution = registry.resolve("locales/en.json", { format: "i18next-json" });
+ * if (resolution.status === "resolved") {
+ *   const { resource } = await resolution.adapter.read("locales/en.json", "en");
+ *   await resolution.adapter.write(resource, "locales/en.json");
+ * }
+ * ```
+ */
+interface FormatAdapter {
+    /** The single format this adapter handles (a `SupportedFormat` from core). */
+    readonly format: SupportedFormat;
+    /**
+     * Detect whether this adapter can handle a file, by path extension and an optional content sample.
+     * Best-effort and side-effect-free; it reads nothing from disk.
+     *
+     * @param filePath - The path of the file under consideration.
+     * @param sample - An optional leading content sample to aid detection.
+     * @returns True if this adapter could handle the file. Several adapters may return true for the same
+     *   file (all JSON adapters claim `.json`); the caller disambiguates by explicit format.
+     */
+    canHandle(filePath: string, sample?: string): boolean;
+    /**
+     * Read a file into a {@link LocaleResource} plus its message-validity result.
+     *
+     * @param filePath - The file to read.
+     * @param locale - The locale to tag the resource with.
+     * @returns The parsed resource and the keys whose values are invalid for the format.
+     * @throws {@link AdapterError} when the content is malformed, oversized, or structurally invalid
+     *   (the implementation names the specific codes). A missing or unopenable path instead rejects with
+     *   the underlying filesystem error.
+     */
+    read(filePath: string, locale: string): Promise<ReadResult>;
+    /**
+     * Write a {@link LocaleResource} back to a file, preserving key order and structure, atomically.
+     *
+     * @param resource - The resource to serialize.
+     * @param filePath - The destination file.
+     * @throws {@link AdapterError} if the resource cannot be represented in the format; rejects with the
+     *   underlying filesystem error on a write failure.
+     */
+    write(resource: LocaleResource, filePath: string): Promise<void>;
+    /**
+     * Extract the format's placeholder tokens from a single value, resolving nothing.
+     *
+     * @param value - The translatable string to scan.
+     * @returns The placeholder tokens found, in document order. Does not throw.
+     */
+    extractPlaceholders(value: string): readonly string[];
+    /**
+     * Validate a single value against the format's message syntax before it is written. Non-ICU formats
+     * (i18next, vue-i18n, ngx-translate) treat every value as valid and return true.
+     *
+     * @param value - The candidate translated value to validate.
+     * @returns True when the value is valid for the format's message syntax. Does not throw; an
+     *   unparseable value returns false.
+     */
+    validateMessage(value: string): boolean;
+}
+
+/** Outcome of resolving an adapter for a file. Structured; never throws. */
+type AdapterResolution = {
+    readonly status: "resolved";
+    readonly adapter: FormatAdapter;
+} | {
+    readonly status: "no-match";
+    readonly filePath: string;
+    readonly triedFormats: readonly SupportedFormat[];
+} | {
+    readonly status: "ambiguous";
+    readonly filePath: string;
+    readonly candidates: readonly SupportedFormat[];
+};
+/** Options for {@link AdapterRegistry.resolve}: select a format explicitly, or aid detection. */
+interface ResolveOptions {
+    /** A content sample to aid detection. */
+    readonly sample?: string;
+    /** Bypass detection and select this format explicitly. */
+    readonly format?: SupportedFormat;
+}
+/**
+ * Holds the registered adapters and resolves one for a file. Open for extension:
+ * adapters attach through register without changing resolution logic.
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    /**
+     * Register an adapter.
+     *
+     * @param adapter - The adapter to add.
+     * @returns This registry, for chaining.
+     */
+    register(adapter: FormatAdapter): this;
+    private formats;
+    private resolveByFormat;
+    private resolveByDetection;
+    /**
+     * Resolve the adapter for a file, by explicit format when given, otherwise by detection.
+     *
+     * @param filePath - The file to resolve an adapter for.
+     * @param options - `format` selects explicitly and skips detection; `sample` aids detection.
+     * @returns A structured {@link AdapterResolution}: `resolved`, `no-match`, or `ambiguous`. Never
+     *   throws; an unresolvable file is a status, not an exception.
+     */
+    resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
+}
+
 /** Outcome of a bounded read: the content, or why it could not be read in bounds. */
 type BoundedFileRead = {
     readonly kind: "ok";
@@ -706,4 +1050,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate, verbatraConfigSchema, watch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verbatra/sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "Programmatic API to automate i18n translation and keep your locale files in sync across languages with AI and machine-translation providers.",
   "keywords": [
@@ -79,10 +79,10 @@
     "typescript": "6.0.3",
     "vitest": "4.1.9",
     "@verbatra/ai-providers": "0.1.3",
+    "@verbatra/format-adapters": "0.3.0",
     "@verbatra/config": "0.0.0",
     "@verbatra/core": "0.1.1",
-    "@verbatra/exchange": "0.2.1",
-    "@verbatra/format-adapters": "0.3.0"
+    "@verbatra/exchange": "0.2.1"
   },
   "scripts": {
     "build": "tsup",