@verbatra/sdk 0.4.2 → 0.4.4

package/dist/index.d.cts

@@ -37,7 +37,7 @@ type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
  * (counts matter). Always returned (never thrown) for an ordinary mismatch.
  */
 interface PlaceholderIntegrityResult {
-    /** True when nothing is missing or extra and order is preserved. */
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
     readonly missing: readonly string[];
@@ -153,8 +153,11 @@ type AnthropicModel = Anthropic.Messages.Model;
  *
  * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
  * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because DeepL cannot preserve those tokens; such entries are withheld (absent from the result maps)
+ *   rather than sent to DeepL and mangled.
  */
-type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
 /**
  * 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.
@@ -378,6 +381,8 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   (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`).
+ * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown by
+ *   `check`, `diff`, and `exportWorkbook` via the shared locale selection).
  * - `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).
@@ -388,7 +393,7 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   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";
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "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. */
@@ -648,7 +653,8 @@ interface CheckDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale drift status.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
 
@@ -697,12 +703,13 @@ interface DiffDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale pending change.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
 /** A stable code for an SDK-originated notice (not a provider notice). */
-type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED";
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
 /**
  * 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,
@@ -739,8 +746,20 @@ interface LocaleSummary {
     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. */
+    /**
+     * Translated keys that failed the placeholder-integrity check and were withheld. Never includes a
+     * key withheld because the provider call itself failed; see {@link LocaleSummary.providerFailures}
+     * for that case.
+     */
     readonly integrityMismatches: readonly string[];
+    /**
+     * Keys withheld because the provider call itself failed (for example a revoked API key, a rate
+     * limit, or a network timeout), as distinct from a translation that came back and failed the
+     * placeholder-integrity check. Nothing was translated for these keys. The corresponding
+     * {@link LocaleSummary.notices} entry carries the secret-free failure code and message. Empty in a
+     * dry-run and empty unless a provider call threw.
+     */
+    readonly providerFailures: readonly string[];
     /**
      * Plural-category keys verbatra synthesized this run (for example a Polish `items_few` the source
      * never supplied), kept distinct from {@link translated}. Empty unless plural generation was enabled
@@ -897,7 +916,8 @@ interface ExportWorkbookResult {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns Where the workbook was written and the per-locale row counts.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
 

package/dist/index.d.ts

@@ -37,7 +37,7 @@ type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
  * (counts matter). Always returned (never thrown) for an ordinary mismatch.
  */
 interface PlaceholderIntegrityResult {
-    /** True when nothing is missing or extra and order is preserved. */
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
     readonly missing: readonly string[];
@@ -153,8 +153,11 @@ type AnthropicModel = Anthropic.Messages.Model;
  *
  * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
  * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because DeepL cannot preserve those tokens; such entries are withheld (absent from the result maps)
+ *   rather than sent to DeepL and mangled.
  */
-type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
 /**
  * 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.
@@ -378,6 +381,8 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   (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`).
+ * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown by
+ *   `check`, `diff`, and `exportWorkbook` via the shared locale selection).
  * - `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).
@@ -388,7 +393,7 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   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";
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "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. */
@@ -648,7 +653,8 @@ interface CheckDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale drift status.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
 
@@ -697,12 +703,13 @@ interface DiffDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale pending change.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
 /** A stable code for an SDK-originated notice (not a provider notice). */
-type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED";
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
 /**
  * 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,
@@ -739,8 +746,20 @@ interface LocaleSummary {
     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. */
+    /**
+     * Translated keys that failed the placeholder-integrity check and were withheld. Never includes a
+     * key withheld because the provider call itself failed; see {@link LocaleSummary.providerFailures}
+     * for that case.
+     */
     readonly integrityMismatches: readonly string[];
+    /**
+     * Keys withheld because the provider call itself failed (for example a revoked API key, a rate
+     * limit, or a network timeout), as distinct from a translation that came back and failed the
+     * placeholder-integrity check. Nothing was translated for these keys. The corresponding
+     * {@link LocaleSummary.notices} entry carries the secret-free failure code and message. Empty in a
+     * dry-run and empty unless a provider call threw.
+     */
+    readonly providerFailures: readonly string[];
     /**
      * Plural-category keys verbatra synthesized this run (for example a Polish `items_few` the source
      * never supplied), kept distinct from {@link translated}. Empty unless plural generation was enabled
@@ -897,7 +916,8 @@ interface ExportWorkbookResult {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns Where the workbook was written and the per-locale row counts.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;