@verbatra/sdk 0.5.0-next.1 → 0.5.0-next.3

package/dist/index.d.cts

@@ -100,7 +100,31 @@ interface Usage {
     readonly inputTokens: number;
     readonly outputTokens: number;
 }
-/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+/**
+ * Stable codes for a provider's graceful-degradation notices. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (DeepL's free tier does not
+ *   support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary term map was not applied (DeepL only applies a
+ *   native glossary id, never a term map).
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because the provider cannot preserve those tokens; such entries are withheld (absent from the
+ *   result maps) rather than sent to the provider and mangled.
+ */
+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.
+ * 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;
+}
+/** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
 interface TranslateResult {
     /** The translated value for each requested key. */
     readonly values: ReadonlyMap<string, string>;
@@ -108,6 +132,12 @@ interface TranslateResult {
     readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$1>;
     /** Token usage when the provider reports it; absent for token-less providers. */
     readonly usage?: Usage;
+    /**
+     * Graceful-degradation notices for this batch. Every provider populates this as a present array:
+     * DeepL reports real notices (for example `GLOSSARY_IGNORED`); an LLM provider with nothing to
+     * report returns an empty array rather than omitting the field.
+     */
+    readonly notices?: readonly ProviderNotice[];
 }
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -166,28 +196,6 @@ interface TranslationProvider {
  * 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.
- * - `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" | "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.
- * 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
@@ -943,11 +951,13 @@ interface LocaleSummary {
      */
     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.
+     * Keys withheld because nothing was translated for them this run, as distinct from a translation
+     * that came back and failed the placeholder-integrity check. This covers two causes: the provider
+     * call itself failed (for example a revoked API key, a rate limit, or a network timeout), in which
+     * case the corresponding {@link LocaleSummary.notices} entry carries the secret-free failure code
+     * and message; or the call succeeded but the key was still missing or duplicated in the response
+     * after the shared LLM layer's bounded reconcile repair round, in which case no notice is added.
+     * Empty in a dry-run.
      */
     readonly providerFailures: readonly string[];
     /**

package/dist/index.d.ts

@@ -100,7 +100,31 @@ interface Usage {
     readonly inputTokens: number;
     readonly outputTokens: number;
 }
-/** Result of a batch translation: per-key values and per-key integrity outcomes. */
+/**
+ * Stable codes for a provider's graceful-degradation notices. These are returned DATA on a
+ * successful result, NOT thrown:
+ *
+ * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (DeepL's free tier does not
+ *   support it).
+ * - `GLOSSARY_IGNORED`: a supplied generic glossary term map was not applied (DeepL only applies a
+ *   native glossary id, never a term map).
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because the provider cannot preserve those tokens; such entries are withheld (absent from the
+ *   result maps) rather than sent to the provider and mangled.
+ */
+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.
+ * 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;
+}
+/** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
 interface TranslateResult {
     /** The translated value for each requested key. */
     readonly values: ReadonlyMap<string, string>;
@@ -108,6 +132,12 @@ interface TranslateResult {
     readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$1>;
     /** Token usage when the provider reports it; absent for token-less providers. */
     readonly usage?: Usage;
+    /**
+     * Graceful-degradation notices for this batch. Every provider populates this as a present array:
+     * DeepL reports real notices (for example `GLOSSARY_IGNORED`); an LLM provider with nothing to
+     * report returns an empty array rather than omitting the field.
+     */
+    readonly notices?: readonly ProviderNotice[];
 }
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
@@ -166,28 +196,6 @@ interface TranslationProvider {
  * 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.
- * - `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" | "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.
- * 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
@@ -943,11 +951,13 @@ interface LocaleSummary {
      */
     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.
+     * Keys withheld because nothing was translated for them this run, as distinct from a translation
+     * that came back and failed the placeholder-integrity check. This covers two causes: the provider
+     * call itself failed (for example a revoked API key, a rate limit, or a network timeout), in which
+     * case the corresponding {@link LocaleSummary.notices} entry carries the secret-free failure code
+     * and message; or the call succeeded but the key was still missing or duplicated in the response
+     * after the shared LLM layer's bounded reconcile repair round, in which case no notice is added.
+     * Empty in a dry-run.
      */
     readonly providerFailures: readonly string[];
     /**