@verbatra/sdk 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -1,13 +1,43 @@
+import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
-import { ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { AdapterRegistry } from '@verbatra/format-adapters';
 
 /**
- * The verbatra project configuration. Non-secret only: it carries no API key (the
- * provider reads its key from the environment), and unknown top-level keys are rejected
- * so a stray secret cannot hide in the config. Validated with zod at the boundary
- * regardless of where it was loaded from.
+ * The provider section of the config: a discriminated union over the provider id,
+ * reusing each provider's own exported config schema. There is no key field anywhere
+ * in this union. The provider reads its API key from the environment at construction.
+ *
+ * This union and the factory table below are co-located on purpose: adding a provider
+ * is a single edit here (one union variant plus one table entry), and the mapped-type
+ * table makes the two sets provably identical at compile time.
  */
+declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodLiteral<"anthropic">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"gemini">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"deepl">;
+    options: z.ZodObject<{
+        glossaryId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strip>], "id">;
+type ProviderConfig = z.infer<typeof providerConfigSchema>;
+type ProviderId = ProviderConfig["id"];
+
 declare const verbatraConfigSchema: z.ZodObject<{
     sourceLocale: z.ZodString;
     targetLocales: z.ZodArray<z.ZodString>;
@@ -50,15 +80,106 @@ declare const verbatraConfigSchema: z.ZodObject<{
         informal: "informal";
         neutral: "neutral";
     }>>;
+    prune: z.ZodOptional<z.ZodBoolean>;
+    generatePlurals: z.ZodOptional<z.ZodBoolean>;
+    maxBatchSize: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
 
+/**
+ * The closed set of a provider's known model IDs: exactly the string literals its SDK
+ * model type ships, with the SDK's own open `string & {}` arm stripped out. Distributing
+ * over the union and dropping any arm the wide `string` extends leaves only the literals,
+ * so the authoring field offers and ACCEPTS only the selected provider's known models. A
+ * foreign or unknown model (for example a Claude model under `id: "gemini"`) is a type
+ * error at authoring time. This is a static authoring constraint only; the runtime schema
+ * stays `z.string().min(1)` and still accepts any non-empty string, so a brand-new model
+ * the installed SDK does not yet list is flagged in the editor but still runs.
+ */
+type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
+type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
+    id: Id;
+}> extends infer Variant ? Variant extends {
+    options: {
+        model: string;
+    };
+} ? Omit<Variant, "options"> & {
+    options: Omit<Variant["options"], "model"> & {
+        model: KnownModels<M>;
+    };
+} : never : never;
+/**
+ * The authoring view of one provider variant, keyed by id. LLM providers (anthropic,
+ * openai, gemini) restrict `options.model` to that provider's known model literals; DeepL
+ * has no model field and is carried through unchanged. Keying by id (rather than a flat
+ * union) lets {@link AuthoringConfigFor} select exactly one variant for a literal id, so
+ * the `options.model` site is one provider's literal set and never a multi-provider union.
+ */
+type AuthoringProviderVariant = {
+    anthropic: AuthoringVariant<"anthropic", AnthropicModel>;
+    openai: AuthoringVariant<"openai", OpenAiModel>;
+    gemini: AuthoringVariant<"gemini", GeminiModel>;
+    deepl: Extract<ProviderConfig, {
+        id: "deepl";
+    }>;
+};
+/**
+ * The authoring view of the whole config for a given provider id. It is structurally a
+ * {@link VerbatraConfig} whose `provider` is the single authoring variant for `TId`.
+ *
+ * When `TId` is a single provider literal, `provider` is one concrete variant, so
+ * `options.model` is that provider's known model literals alone and not a union across
+ * providers. `defineConfig` declares one overload per provider parameterized on this type
+ * (`AuthoringConfigFor<"openai">` and so on), so overload resolution picks the variant from
+ * the `provider.id` literal. That, together with the closed {@link KnownModels} set, makes a
+ * foreign model (for example a Claude model under `id: "gemini"`) a type error and aims to
+ * keep editors with weaker discriminated-union narrowing (for example the JetBrains/WebStorm
+ * completion engine) offering only the selected provider's models, since each overload's
+ * parameter is already a single variant with no nested union to narrow. When `TId` defaults
+ * to `ProviderId`, `provider` is the full authoring union. Every value assignable here is
+ * assignable to {@link VerbatraConfig}, because a model literal is a subtype of `string`.
+ */
+type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfig, "provider"> & {
+    provider: AuthoringProviderVariant[TId];
+};
+/**
+ * The authoring view of the whole config across every provider (the `TId = ProviderId`
+ * case of {@link AuthoringConfigFor}): identical to {@link VerbatraConfig} except that
+ * `provider` offers per-provider model completions.
+ */
+type AuthoringConfig = AuthoringConfigFor;
+
 /**
  * Identity helper for authoring a code-defined verbatra.config.ts. It returns its
  * argument unchanged; its only purpose is to give the author full type inference and
  * editor autocomplete on the config object.
+ *
+ * It is declared as one overload per provider id rather than a single generic. Each
+ * overload's parameter is the concrete single-provider authoring config
+ * ({@link AuthoringConfigFor}), so `provider.options.model` is already that one provider's
+ * known model literals, with no union across providers and no generic for an editor to
+ * infer. Overload resolution selects the matching overload from the `provider.id` literal,
+ * so the editor offers only the selected provider's models and a foreign or unknown model
+ * (for example a Claude model under `id: "gemini"`) is a type error. This is deliberately
+ * overload-based: a generic whose type parameter is inferred from a nested `provider.id`
+ * collapses correctly in tsserver but not in editors with weaker inference (notably the
+ * JetBrains/WebStorm completion engine), which then fall back to the full union and offer
+ * every provider's models. Concrete per-provider signatures avoid that inference step.
+ *
+ * The final overload accepts the full {@link AuthoringConfig} union, so a config whose
+ * provider id is not a single literal (for example a value typed as the union) still
+ * type-checks.
+ *
+ * The return type is the runtime {@link VerbatraConfig}. The model restriction is a static
+ * authoring constraint, not a runtime one: `loadConfig` still validates `model` as
+ * `z.string().min(1)`, so a model the installed provider SDK does not yet list is flagged
+ * in the editor but still runs.
  */
-declare function defineConfig(config: VerbatraConfig): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfig): VerbatraConfig;
 
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
@@ -107,57 +228,21 @@ interface LoadConfigOptions {
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig>;
 
-/**
- * The provider section of the config: a discriminated union over the provider id,
- * reusing each provider's own exported config schema. There is no key field anywhere
- * in this union. The provider reads its API key from the environment at construction.
- *
- * This union and the factory table below are co-located on purpose: adding a provider
- * is a single edit here (one union variant plus one table entry), and the mapped-type
- * table makes the two sets provably identical at compile time.
- */
-declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    id: z.ZodLiteral<"anthropic">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"openai">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"gemini">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"deepl">;
-    options: z.ZodObject<{
-        glossaryId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>;
-}, z.core.$strip>], "id">;
-type ProviderConfig = z.infer<typeof providerConfigSchema>;
-type ProviderId = ProviderConfig["id"];
-
 /**
  * Structured, secret-free error codes for the SDK boundaries. A key never appears in
  * any message: provider/adapter/core errors are already secret-free, and the SDK never
  * reads or holds a key. Each names a distinct boundary:
  *
- * - `CONFIG_NOT_FOUND`:no config was found by search, or an explicit `configPath` does not exist
+ * - `CONFIG_NOT_FOUND`: no config was found by search, or an explicit `configPath` does not exist
  *   (thrown by `loadConfig`).
- * - `CONFIG_INVALID`:a config was found but is unparseable or fails validation (thrown by `loadConfig`).
- * - `UNKNOWN_FORMAT`:no adapter is registered for the configured format (thrown by `translate`).
- * - `PROVIDER_CONSTRUCTION_FAILED`:the provider factory threw; wraps the provider's own error, including
+ * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation (thrown by `loadConfig`).
+ * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by `translate`).
+ * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error, including
  *   a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by `translate`, non-dry-run only).
- * - `SOURCE_UNREADABLE`:the source locale file is absent (thrown by `translate`, and by `watch` at startup).
- * - `SOURCE_INVALID`:the source locale file could not be read or parsed; wraps the adapter read error
+ * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by `translate`, and by `watch` at startup).
+ * - `SOURCE_INVALID`: the source locale file could not be read or parsed; wraps the adapter read error
  *   (thrown by `translate`).
- * - `LOCK_FILE_INVALID`:the lock-file is present but corrupt or oversized (thrown by `translate`).
+ * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt or oversized (thrown by `translate`).
  * - `LOCALE_FAILED` (NOT thrown): the fallback `code` recorded on a failed `LocaleSummary` when a
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction on
  *   `translate`.
@@ -174,6 +259,23 @@ declare class SdkError extends Error {
     constructor(code: SdkErrorCode, message: string);
 }
 
+/** A stable code for an SDK-originated notice (not a provider notice). */
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED";
+/**
+ * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
+ * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
+ * secret-free message; never a key value or translatable content. The SDK keeps its own codes here so
+ * the ai-providers `ProviderNoticeCode` union stays free of SDK concerns (the dependency arrow points
+ * sdk -> ai-providers, never the reverse).
+ */
+interface SdkNotice {
+    /** The stable {@link SdkNoticeCode} for what the SDK is reporting. */
+    readonly code: SdkNoticeCode;
+    /** A static, safe description; never a key or translatable content. */
+    readonly message: string;
+}
+/** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
+type LocaleNotice = ProviderNotice | SdkNotice;
 /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
 interface LocaleSummary {
     /** The target locale this summary is for. */
@@ -187,14 +289,31 @@ interface LocaleSummary {
     readonly translated: readonly string[];
     /** Keys already up to date, left unchanged this run. */
     readonly unchanged: readonly string[];
-    /** Target keys with no corresponding source key (candidates for removal). */
+    /** Target keys with no corresponding source key (candidates for removal). Reported regardless of pruning. */
     readonly orphaned: readonly string[];
+    /**
+     * Orphaned keys actually removed this run because pruning was on. In a dry-run with pruning on, the keys
+     * that WOULD be removed. Empty when pruning is off (the orphans then survive and are reported in
+     * `orphaned` only). A subset of `orphaned`; never includes a source-present key.
+     */
+    readonly pruned: readonly string[];
     /** Source keys flagged invalid-ICU that were skipped for translation this run. */
     readonly invalidIcuSource: readonly string[];
     /** Translated keys that failed the placeholder-integrity check and were withheld. */
     readonly integrityMismatches: readonly string[];
-    /** Provider notices for this locale (e.g. DeepL graceful-degradation); empty for LLM providers. */
-    readonly notices: readonly ProviderNotice[];
+    /**
+     * Plural-category keys verbatra SYNTHESIZED this run (for example a Polish `items_few` the source
+     * never supplied), kept distinct from {@link translated} because they were generated from the meaning
+     * of the source plural forms, not translated 1:1 from a source string. Empty unless plural generation
+     * was enabled and acted. In a dry-run this is empty (the provider is not called).
+     */
+    readonly generated: readonly string[];
+    /**
+     * Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
+     * (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
+     * nothing was degraded or flagged.
+     */
+    readonly notices: readonly LocaleNotice[];
     /**
      * Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
      * (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
@@ -236,9 +355,11 @@ type BoundedBytesRead = {
     readonly kind: "too-large";
 };
 /**
- * The minimal file-system surface the SDK needs for the lock-file and for existence
- * checks. Injectable so tests stay deterministic; the format adapters do their own
- * file IO and are not routed through this seam.
+ * The minimal file-system surface the SDK needs: existence checks, the lock-file read/write,
+ * and the untrusted workbook bytes read/write for the export/import flow. Reads are bounded
+ * (see {@link readFileBounded} / {@link readBytesBounded}) and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and are not routed through
+ * this seam.
  */
 interface SdkFs {
     /** Whether a readable file exists at the path. */
@@ -274,6 +395,19 @@ interface TranslateInput {
     readonly cwd?: string;
     /** When true, read + diff + report only: the provider is never constructed or called and nothing is written. */
     readonly dryRun?: boolean;
+    /**
+     * When true, remove orphaned keys (target keys absent from source) from the written file and the lock.
+     * Off by default. When set, takes precedence over the config's `prune` option for this run; when unset,
+     * the config's `prune` applies. Only `diff.orphaned` keys are ever removed; no other key is touched.
+     */
+    readonly prune?: boolean;
+    /**
+     * When true, synthesize the CLDR plural forms a richer target language requires but the source lacks
+     * (i18next-JSON + LLM providers only; every other case falls back to the existing warning). Off by
+     * default. When set, takes precedence over the config's `generatePlurals` option for this run; when
+     * unset, the config's `generatePlurals` applies.
+     */
+    readonly generatePlurals?: boolean;
 }
 /** Composition seam: inject a registry, a provider builder, and a file system for tests. */
 interface TranslateDeps {
@@ -298,7 +432,7 @@ interface TranslateDeps {
  * {@link SdkErrorCode}. DeepL notices, integrity mismatches, and invalid-ICU source keys likewise
  * surface on each `LocaleSummary`, never as throws.
  *
- * @param input - The validated config and run options (cwd, dryRun).
+ * @param input - The validated config and run options (cwd, dryRun, prune, generatePlurals).
  * @param deps - Optional composition seams (registry, provider builder, file system) for tests.
  * @returns A {@link RunSummary}: the per-locale {@link LocaleSummary}s and the succeeded/failed locale lists.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
@@ -424,7 +558,7 @@ interface Watcher {
 }
 /** Builds a {@link Watcher} for the given paths; the seam production fills with chokidar. */
 type CreateWatcher = (paths: readonly string[]) => Watcher;
-/** The run a watch trigger performs: the slice-1 one-shot translate, unchanged. */
+/** The run a watch trigger performs: the one-shot translate, unchanged. */
 type RunTranslate = (input: TranslateInput) => Promise<RunSummary>;
 /** The outcome of one run, surfaced to the caller; never carries a secret. */
 type WatchRunResult = {
@@ -512,4 +646,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate, verbatraConfigSchema, watch };
+export { type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, 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, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate, verbatraConfigSchema, watch };