@verbatra/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,414 @@
+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.
+ */
+declare const verbatraConfigSchema: z.ZodObject<{
+    sourceLocale: z.ZodString;
+    targetLocales: z.ZodArray<z.ZodString>;
+    format: z.ZodEnum<{
+        "i18next-json": "i18next-json";
+        "vue-i18n-json": "vue-i18n-json";
+        "next-intl-json": "next-intl-json";
+        "ngx-translate-json": "ngx-translate-json";
+    }>;
+    files: z.ZodObject<{
+        pattern: z.ZodString;
+    }, z.core.$strict>;
+    provider: 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">;
+    glossary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        formal: "formal";
+        informal: "informal";
+        neutral: "neutral";
+    }>>;
+}, z.core.$strict>;
+type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
+
+/**
+ * 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.
+ */
+declare function defineConfig(config: VerbatraConfig): VerbatraConfig;
+
+interface LoadConfigOptions {
+    /** Directory to start the search from. Defaults to the current working directory. */
+    readonly cwd?: string;
+    /**
+     * A pre-resolved config object (e.g. one passed in code) to validate instead of
+     * searching the file system. Still validated with zod, exactly like a loaded file.
+     */
+    readonly configOverride?: unknown;
+    /**
+     * An explicit config file to load instead of searching. A relative path resolves
+     * against `cwd` (an absolute path is used as given), then cosmiconfig's load() parses
+     * it with the same loaders search uses (.json/.yaml/.ts), and it is zod-validated at
+     * the boundary exactly like a searched file. A missing file is CONFIG_NOT_FOUND; a
+     * present-but-unparseable/invalid file is CONFIG_INVALID. Precedence: configOverride
+     * wins over configPath, which wins over search.
+     */
+    readonly configPath?: string;
+}
+/**
+ * Load and validate the verbatra configuration. Supports a code-defined
+ * verbatra.config.ts and file-based configs (.verbatrarc.json/.yaml, package.json
+ * property) through cosmiconfig + cosmiconfig-typescript-loader. Multiple sources ->
+ * first-found-wins by cosmiconfig precedence. Any failure is a structured SdkError;
+ * a raw zod error is never thrown upward and an unvalidated config never proceeds.
+ *
+ * Precedence: `configOverride` (validate in-memory) > `configPath` (load one explicit file) > search.
+ *
+ * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, or an explicit `configPath`.
+ * @returns The validated {@link VerbatraConfig}.
+ * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
+ *   does not exist.
+ * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation
+ *   (a raw zod error never escapes).
+ * @example
+ * ```ts
+ * import { loadConfig, translate } from "@verbatra/sdk";
+ *
+ * // Search upward from the cwd (verbatra.config.ts, .verbatrarc.json, or a package.json "verbatra" key):
+ * const config = await loadConfig();
+ * // Or load one explicit file (relative resolves against cwd; absolute as given):
+ * // const config = await loadConfig({ configPath: "verbatra.config.ts" });
+ *
+ * const summary = await translate({ config });
+ * ```
+ */
+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
+ *   (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
+ *   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
+ *   (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`.
+ */
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCALE_FAILED";
+/** The single structured error the SDK throws or records. Never carries a secret. */
+declare class SdkError extends Error {
+    /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
+    readonly code: SdkErrorCode;
+    /**
+     * @param code - The stable failure code.
+     * @param message - A fixed, secret-free message; the SDK never holds a key to put here.
+     */
+    constructor(code: SdkErrorCode, message: string);
+}
+
+/** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
+interface LocaleSummary {
+    /** The target locale this summary is for. */
+    readonly locale: string;
+    /** Whether this locale's run succeeded or failed (a failure does not abort the run). */
+    readonly status: "succeeded" | "failed";
+    /**
+     * Keys translated and written this run. In dry-run, the keys that WOULD be translated
+     * (the provider is not called and nothing is written).
+     */
+    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). */
+    readonly orphaned: 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[];
+    /**
+     * 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
+     * wider than {@link SdkErrorCode}, so do not treat it as a closed set.
+     */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/** The aggregate result of a run across all target locales. */
+interface RunSummary {
+    /** Whether this was a dry-run (no provider calls, no writes). */
+    readonly dryRun: boolean;
+    /** One {@link LocaleSummary} per target locale, in config order. */
+    readonly locales: readonly LocaleSummary[];
+    /** Locales whose run succeeded. */
+    readonly succeeded: readonly string[];
+    /** Locales whose run failed (see each locale's `error`). */
+    readonly failed: readonly string[];
+}
+
+/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
+type BoundedFileRead = {
+    readonly kind: "ok";
+    readonly content: string;
+} | {
+    readonly kind: "missing";
+} | {
+    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.
+ */
+interface SdkFs {
+    /** Whether a readable file exists at the path. */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the
+     * handle is fstat'd and the read never advances past the sized length, so swapping the
+     * path for a larger file after the size check cannot bypass the cap. A missing or
+     * unreadable path is "missing" (first-run); a file over the cap is "too-large".
+     */
+    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /** Write atomically: a temp file in the same directory, then rename over the target. */
+    writeFile(path: string, data: string): Promise<void>;
+}
+
+/** Builds the provider from its config. Injectable so tests stay offline. */
+type CreateProvider = (config: ProviderConfig) => TranslationProvider;
+
+/** Everything the one-shot run needs: the validated config and where/how to run it. */
+interface TranslateInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to the current working directory. */
+    readonly cwd?: string;
+    /** When true, read + diff + report only: the provider is never constructed or called and nothing is written. */
+    readonly dryRun?: boolean;
+}
+/** Composition seam: inject a registry, a provider builder, and a file system for tests. */
+interface TranslateDeps {
+    /** Adapter registry to resolve the format from; defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** Provider builder; defaults to constructing the configured provider (which reads its key from env). */
+    readonly createProvider?: CreateProvider;
+    /** File system for existence checks and the lock-file; defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/**
+ * The one-shot end-to-end translate flow. Whole-run failures (config already validated
+ * by the caller, unknown format, provider construction, unreadable/invalid source,
+ * corrupt lock-file) throw a structured SdkError. Per-locale failures are isolated: a
+ * failing locale is reported and the run continues; the lock-file reflects exactly the
+ * locales that succeeded. Dry-run reads + diffs + reports without constructing/calling
+ * the provider and without writing any file or the lock-file.
+ *
+ * A per-locale failure does NOT throw: it is recorded on that locale's {@link LocaleSummary} as
+ * `status: "failed"` with a secret-free `{ code, message }`, where `code` is a preserved string (the
+ * underlying provider/adapter code, or `"LOCALE_FAILED"` as a fallback), not necessarily an
+ * {@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 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.
+ * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw (this wraps the
+ *   provider's own error, including a missing `*_API_KEY` reported as `MISSING_API_KEY`); only on a
+ *   non-dry-run, since dry-run never constructs the provider.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be read or parsed (wraps the
+ *   adapter read error).
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is present but corrupt or oversized.
+ * @example
+ * ```ts
+ * import { loadConfig, translate } from "@verbatra/sdk";
+ *
+ * // The provider reads its API key from the environment (e.g. ANTHROPIC_API_KEY); no key is passed here.
+ * const config = await loadConfig();
+ * const summary = await translate({ config });
+ *
+ * for (const locale of summary.locales) {
+ *   if (locale.status === "failed") {
+ *     // Surfaced, not thrown: code is a preserved string (LOCALE_FAILED is only the fallback).
+ *     console.error(`${locale.locale}: ${locale.error?.code} ${locale.error?.message}`);
+ *   } else {
+ *     console.log(`${locale.locale}: ${locale.translated.length} translated, ${locale.notices.length} notices`);
+ *   }
+ * }
+ *
+ * // Preview only: no provider call, no writes.
+ * const preview = await translate({ config, dryRun: true });
+ * ```
+ */
+declare function translate(input: TranslateInput, deps?: TranslateDeps): Promise<RunSummary>;
+
+/** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
+interface Watcher {
+    /** Register a listener invoked once per coalesced source-change event. */
+    onChange(listener: () => void): void;
+    /** Stop watching and release the underlying resources. */
+    close(): Promise<void>;
+}
+/** 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. */
+type RunTranslate = (input: TranslateInput) => Promise<RunSummary>;
+/** The outcome of one run, surfaced to the caller; never carries a secret. */
+type WatchRunResult = {
+    readonly status: "succeeded";
+    readonly summary: RunSummary;
+} | {
+    readonly status: "failed";
+    /**
+     * A secret-free projection of the run's failure. `code` is a preserved string (the underlying
+     * error's `code`, or `"WATCH_RUN_FAILED"` as a fallback), not an {@link SdkErrorCode}.
+     */
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+/** Everything watch mode needs: the config, optional cwd/debounce, and the per-run output callback. */
+interface WatchInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to the current working directory. */
+    readonly cwd?: string;
+    /** Quiet period after the last change before a run fires; defaults to 300ms. */
+    readonly debounceMs?: number;
+    /** Called once per run with its result. The SDK does no logging; this is the only output. */
+    readonly onRun: (result: WatchRunResult) => void;
+}
+/** Composition seam: inject the watcher and the run for deterministic, offline tests. */
+interface WatchDeps {
+    /** Adapter registry passed through to each run; defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** Provider builder passed through to each run; defaults to constructing the configured provider. */
+    readonly createProvider?: CreateProvider;
+    /** File system passed through to each run; defaults to the real file system. */
+    readonly fs?: SdkFs;
+    /** Source-change event source; defaults to the chokidar-backed watcher. */
+    readonly createWatcher?: CreateWatcher;
+    /** The run a trigger performs; defaults to the one-shot {@link translate}. */
+    readonly runTranslate?: RunTranslate;
+}
+/** Handle returned by {@link watch} to stop it. */
+interface WatchController {
+    /** Stop accepting triggers, close the watcher, and await the in-flight run to completion. */
+    stop(): Promise<void>;
+}
+/**
+ * Start watching the source file and re-run the one-shot translate on each debounced change.
+ * Watch adds no translation/diff/lock logic: it watches, debounces, serializes, and invokes the
+ * existing translate() unchanged. The state machine is IDLE <-> RUNNING with a single boolean
+ * pending-rerun flag (mid-run changes collapse into one immediate follow-up; never two runs at
+ * once). A missing source at startup is a hard error; a run that fails after start is reported and
+ * watching continues. Returns a controller whose stop() closes the watcher and awaits the in-flight
+ * run (the caller wires any signal, e.g. SIGINT, to it).
+ *
+ * Only the startup source check throws; every run outcome after start is surfaced through `onRun` as a
+ * {@link WatchRunResult} (a failed run never rejects the in-flight promise).
+ *
+ * @param input - The config, optional cwd/debounce, and the `onRun` callback that receives each result.
+ * @param deps - Optional composition seams (watcher, run, registry, provider builder, file system) for tests.
+ * @returns A {@link WatchController}; call `stop()` to close the watcher and await the in-flight run.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: at startup only, when the source locale file is absent.
+ * @example
+ * ```ts
+ * import { loadConfig, watch } from "@verbatra/sdk";
+ *
+ * // The provider reads its API key from the environment (e.g. ANTHROPIC_API_KEY); no key is passed here.
+ * const config = await loadConfig();
+ * const controller = await watch({
+ *   config,
+ *   onRun: (result) => {
+ *     if (result.status === "succeeded") {
+ *       console.log(`ran: ${result.summary.succeeded.length} ok, ${result.summary.failed.length} failed`);
+ *     } else {
+ *       // Surfaced, not thrown: code is a preserved string (WATCH_RUN_FAILED is only the fallback).
+ *       console.error(`run failed: ${result.error.code} ${result.error.message}`);
+ *     }
+ *   },
+ * });
+ *
+ * // Stop cleanly on Ctrl-C: closes the watcher and awaits the in-flight run.
+ * process.on("SIGINT", () => {
+ *   void controller.stop();
+ * });
+ * ```
+ */
+declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
+
+export { type CreateProvider, type CreateWatcher, 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, loadConfig, translate, verbatraConfigSchema, watch };