@broberg/ai-sdk 0.27.0 → 0.28.0

package/dist/index.d.ts

@@ -1640,6 +1640,9 @@ declare const ttsInputSchema: z.ZodObject<{
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     text: z.ZodString;
     voice: z.ZodString;
+    /** F037: voice to use if `voice` is one we know the provider has retired. Without
+     *  it a retired voice throws VoiceUnavailableError rather than reaching the API. */
+    voiceFallback: z.ZodOptional<z.ZodString>;
     lang: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodString>;
     rate: z.ZodOptional<z.ZodNumber>;
@@ -1660,6 +1663,7 @@ declare const ttsInputSchema: z.ZodObject<{
     })[] | undefined;
     labels?: Record<string, string> | undefined;
     format?: string | undefined;
+    voiceFallback?: string | undefined;
     lang?: string | undefined;
     rate?: number | undefined;
 }, {
@@ -1679,6 +1683,7 @@ declare const ttsInputSchema: z.ZodObject<{
     })[] | undefined;
     labels?: Record<string, string> | undefined;
     format?: string | undefined;
+    voiceFallback?: string | undefined;
     lang?: string | undefined;
     rate?: number | undefined;
 }>;
@@ -2048,8 +2053,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.27.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.27.0";
+declare const VERSION: "0.28.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.28.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.
@@ -2102,6 +2107,88 @@ declare function refreshAvailability(opts?: RefreshOptions): Promise<RefreshResu
 /** Reset the overlay back to the curated defaults. For tests. */
 declare function resetRegistry(): void;
 
+type VoiceStatus = "available" | "retired" | "unknown";
+type VoiceProvider = "elevenlabs" | "azure";
+/** One row of the shared voice read — what a UI voice-picker renders. */
+interface VoiceInfo {
+    /** Full provider voice id, e.g. "da-DK-ChristelNeural" / "4RklGmuxoAskAbGXplXN". */
+    id: string;
+    /** Curated friendly name a caller passes as `voice`, e.g. "christel". */
+    name: string;
+    provider: VoiceProvider;
+    /** BCP-47 locale of the voice itself, e.g. "da-DK". NB: an Azure multilingual
+     *  voice speaking Danish reports its own locale ("de-DE" for Seraphina) — that
+     *  is what the adapter actually sends as xml:lang. */
+    locale: string;
+    /** Only where the provider publishes it — absent is "we do not know", never a
+     *  guess from the first name. */
+    gender?: "female" | "male";
+    available: boolean;
+    status: VoiceStatus;
+    /** Why it is unavailable, or any caveat worth showing in a picker. */
+    note?: string;
+    /** ISO date this row's status was last confirmed AGAINST THE PROVIDER. Exposed
+     *  on purpose (the F034.1 lesson): a registry that cannot be seen to go stale
+     *  is worse than one that can, because nobody knows when to re-check it. */
+    checkedAt: string;
+}
+/** Result of checkVoice — deliberately the same shape as ResolveResult (F022) so
+ *  a consumer learns one idiom for models and voices. */
+interface VoiceResolveResult {
+    /** True when the requested voice itself is usable. */
+    ok: boolean;
+    /** The id to actually send: the requested voice's id when ok, else the
+     *  fallback's. When there is no usable fallback this is the dead id and `ok`
+     *  is false — mirroring resolveModel, the caller must read `ok`. */
+    voiceId: string;
+    /** What the caller asked for, verbatim. */
+    requested: string;
+    provider?: VoiceProvider;
+    /** True when `voiceId` differs from what was requested because we fell back. */
+    fellBack: boolean;
+    status: VoiceStatus;
+    /** Why it degraded / why it is unavailable. */
+    reason?: string;
+}
+/** Thrown when the requested voice is retired and no usable fallback exists.
+ *  Callers flag on `.code === "voice_unavailable"`. */
+declare class VoiceUnavailableError extends Error {
+    readonly code = "voice_unavailable";
+    readonly requested: string;
+    readonly provider?: VoiceProvider;
+    readonly note?: string;
+    constructor(requested: string, note?: string, provider?: VoiceProvider);
+}
+
+interface CheckVoiceOptions {
+    /** One name/id or an ordered chain to try when `requested` is retired. */
+    fallback?: string | string[];
+    /** Throw VoiceUnavailableError instead of returning ok:false when nothing in the
+     *  chain is usable. For callers that want to fail loudly rather than degrade. */
+    throwIfUnavailable?: boolean;
+}
+/**
+ * The shared voice read — a UI picker greys out `available:false` rows and can show
+ * `checkedAt` so a stale registry is visible rather than silently trusted.
+ *
+ * NB: distinct from `elevenlabsAdapter().listVoices()`, which is an async call to
+ * ElevenLabs' live API. This one is synchronous, cross-provider, and reads only the
+ * curated registry.
+ */
+declare function listVoices(opts?: {
+    provider?: VoiceProvider;
+}): VoiceInfo[];
+/**
+ * Resolve a requested voice (curated name or raw provider id) to one that is
+ * actually usable. Synchronous + offline by contract.
+ *
+ * - Available → pass through ({ ok:true, fellBack:false }).
+ * - Retired + a usable fallback → swap ({ ok:false, fellBack:true }).
+ * - Retired + no usable fallback → throw (throwIfUnavailable) or return ok:false.
+ * - Untracked id → treated usable ({ status:"unknown" }), passed through verbatim.
+ */
+declare function checkVoice(requested: string, opts?: CheckVoiceOptions): VoiceResolveResult;
+
 /**
  * Cost in USD for a call. cache-read/creation tokens are priced separately when
  * the pricing entry defines rates for them; otherwise they fall back to the
@@ -2376,4 +2463,4 @@ interface StreamTransportRequest extends TransportRequest {
  */
 declare function streamTransport(req: StreamTransportRequest): AsyncIterable<string>;
 
-export { AZURE_DANISH_VOICES, AZURE_DANISH_VOICE_LIST, type AiClient, type AiConfig, type AzureVoiceInfo, type BatchJob, type BatchRequestItem, type BatchResultItem, type BflAdapterConfig, type BflCredits, type BudgetConfig, BudgetExceededError, BudgetGuard, type BudgetStore, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ChatStreamEvent, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostQuery, type CostSink, type CostSummary, type CostSummaryQuery, type CostTimeseriesQuery, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DialogueRequest, type DialogueTurn, type DiscordSinkConfig, ELEVENLABS_DANISH_VOICES, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type LoraWeight, type Message, type MockupInput, type MockupResult, type ModerationInput, type ModerationItem, type ModerationRequest, type ModerationResult, type OcrInput, type OcrPage, type OcrRequest, type OcrResult, type OpenAICompatibleConfig, type PodcastInput, type PodcastResult, type PricingEntry, type ProviderAdapter, type RefreshOptions, type RefreshResult, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TrainStyleInput, type TrainStyleRequest, type TrainStyleResult, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type TtsInput, type TtsRequest, type UpmetricsCostClientConfig, UpmetricsCostError, type UpmetricsCostRow, type UpmetricsCostSummary, type UpmetricsCostTimeseries, type UpmetricsSinkConfig, type Usage, VERSION, type VideoInput, type VisionInput, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, chatInputSchema, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultProviders, discordSink, elevenlabsAdapter, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, listAzureDanishVoices, makeContracts, makeOpenAICompatibleAdapter, messageSchema, mistralAdapter, mistralStubAdapter, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, refreshAvailability, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema };
+export { AZURE_DANISH_VOICES, AZURE_DANISH_VOICE_LIST, type AiClient, type AiConfig, type AzureVoiceInfo, type BatchJob, type BatchRequestItem, type BatchResultItem, type BflAdapterConfig, type BflCredits, type BudgetConfig, BudgetExceededError, BudgetGuard, type BudgetStore, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ChatStreamEvent, type CheckVoiceOptions, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostQuery, type CostSink, type CostSummary, type CostSummaryQuery, type CostTimeseriesQuery, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DialogueRequest, type DialogueTurn, type DiscordSinkConfig, ELEVENLABS_DANISH_VOICES, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type LoraWeight, type Message, type MockupInput, type MockupResult, type ModerationInput, type ModerationItem, type ModerationRequest, type ModerationResult, type OcrInput, type OcrPage, type OcrRequest, type OcrResult, type OpenAICompatibleConfig, type PodcastInput, type PodcastResult, type PricingEntry, type ProviderAdapter, type RefreshOptions, type RefreshResult, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TrainStyleInput, type TrainStyleRequest, type TrainStyleResult, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type TtsInput, type TtsRequest, type UpmetricsCostClientConfig, UpmetricsCostError, type UpmetricsCostRow, type UpmetricsCostSummary, type UpmetricsCostTimeseries, type UpmetricsSinkConfig, type Usage, VERSION, type VideoInput, type VisionInput, type VoiceInfo, type VoiceProvider, type VoiceResolveResult, type VoiceStatus, VoiceUnavailableError, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, chatInputSchema, checkVoice, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultProviders, discordSink, elevenlabsAdapter, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, listAzureDanishVoices, listVoices, makeContracts, makeOpenAICompatibleAdapter, messageSchema, mistralAdapter, mistralStubAdapter, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, refreshAvailability, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema };

package/dist/index.js

@@ -1390,13 +1390,13 @@ function elevenlabsAdapter(config = {}) {
     const audio = new Uint8Array(await res.arrayBuffer());
     return { audio, mimeType: "audio/mpeg", usage: priceFor(req.text.length, model) };
   }
-  async function listVoices() {
+  async function listVoices2() {
     const res = await fetchImpl(`${baseUrl}/voices`, { headers: { "xi-api-key": key() } });
     if (!res.ok) throw new Error(`elevenlabs voices ${res.status}`);
     const data = await res.json();
     return (data.voices ?? []).map((v) => ({ voiceId: v.voice_id, name: v.name, language: v.labels?.language }));
   }
-  return { name: "elevenlabs", dialogue, tts, listVoices };
+  return { name: "elevenlabs", dialogue, tts, listVoices: listVoices2 };
 }
 
 // src/providers/azure.ts
@@ -2449,6 +2449,143 @@ ${JSON.stringify(input.items)}`,
   };
 }
 
+// src/voices/registry.ts
+var CHECKED_AT = {
+  // All 5 curated ids confirmed by SYNTHESIS — POST /v1/text-to-speech/{id} returned
+  // 200 with distinct audio per voice (5 distinct sha256), and a fabricated id
+  // returned 404, so a 200 means something.
+  //
+  // NB: GET /v1/voices/{id} is NOT a liveness test and must not be used as one. It
+  // answers "is this voice saved in our account", and returns voice_not_found for a
+  // public/shared voice that synthesizes perfectly well. Using it cost us a false
+  // retirement (see the note on `mads` below) — the only honest liveness check for
+  // ElevenLabs is a real synthesis call, which is exactly why v1 does no live check.
+  elevenlabs: "2026-08-11",
+  // F026 (6ca38c4) verified the 6 curated names against Azure's voices/list. Not
+  // re-probed since: this machine has no Azure Speech key, and inventing a fresher
+  // date than the last real check is exactly the lie checkedAt exists to prevent.
+  azure: "2026-06-23"
+};
+var RETIRED_DEFAULT = {};
+var RETIRED = RETIRED_DEFAULT;
+var ELEVENLABS_GENDER = {
+  soren: "male",
+  jesper: "male",
+  noam: "male",
+  camilla: "female"
+};
+var NOTES = {
+  mads: "usable, but not saved to the ElevenLabs account, so the voices endpoint publishes no metadata for it (verified by synthesis 2026-08-11)"
+};
+function build() {
+  const rows = [];
+  for (const [name, id] of Object.entries(ELEVENLABS_DANISH_VOICES)) {
+    const retired = RETIRED[name];
+    rows.push({
+      id,
+      name,
+      provider: "elevenlabs",
+      // The curated ElevenLabs roster IS the Danish one (see the constant's name
+      // + F020); the multilingual model speaks it as da-DK.
+      locale: "da-DK",
+      gender: ELEVENLABS_GENDER[name],
+      available: retired === void 0,
+      status: retired === void 0 ? "available" : "retired",
+      note: retired ?? NOTES[name],
+      checkedAt: CHECKED_AT.elevenlabs
+    });
+  }
+  for (const v of AZURE_DANISH_VOICE_LIST) {
+    const retired = RETIRED[v.name];
+    rows.push({
+      id: v.voiceId,
+      name: v.name,
+      provider: "azure",
+      locale: localeOf(v.voiceId),
+      gender: v.gender,
+      available: retired === void 0,
+      status: retired === void 0 ? "available" : "retired",
+      note: retired ?? NOTES[v.name],
+      checkedAt: CHECKED_AT.azure
+    });
+  }
+  return rows;
+}
+var ROWS = build();
+function allVoices(provider) {
+  return provider ? ROWS.filter((v) => v.provider === provider) : [...ROWS];
+}
+function getVoice(nameOrId) {
+  return ROWS.find((v) => v.name === nameOrId || v.id === nameOrId);
+}
+
+// src/voices/types.ts
+var VoiceUnavailableError = class extends Error {
+  code = "voice_unavailable";
+  requested;
+  provider;
+  note;
+  constructor(requested, note, provider) {
+    super(`voice "${requested}" is unavailable${note ? ` (${note})` : ""}`);
+    this.name = "VoiceUnavailableError";
+    this.requested = requested;
+    this.note = note;
+    this.provider = provider;
+  }
+};
+
+// src/voices/resolve.ts
+function listVoices(opts = {}) {
+  return allVoices(opts.provider);
+}
+function usable(nameOrId) {
+  const v = getVoice(nameOrId);
+  return v ? v.available : true;
+}
+function idFor(nameOrId) {
+  return getVoice(nameOrId)?.id ?? nameOrId;
+}
+function checkVoice(requested, opts = {}) {
+  const entry = getVoice(requested);
+  const provider = entry?.provider;
+  if (usable(requested)) {
+    return {
+      ok: true,
+      voiceId: idFor(requested),
+      requested,
+      provider,
+      fellBack: false,
+      status: entry?.status ?? "unknown"
+    };
+  }
+  const chain = opts.fallback === void 0 ? [] : Array.isArray(opts.fallback) ? opts.fallback : [opts.fallback];
+  for (const fb of chain) {
+    if (usable(fb)) {
+      return {
+        ok: false,
+        voiceId: idFor(fb),
+        requested,
+        provider: getVoice(fb)?.provider ?? provider,
+        fellBack: true,
+        status: entry?.status ?? "retired",
+        reason: entry?.note ?? `${requested} is unavailable`
+      };
+    }
+  }
+  if (opts.throwIfUnavailable) {
+    throw new VoiceUnavailableError(requested, entry?.note, provider);
+  }
+  return {
+    ok: false,
+    voiceId: idFor(requested),
+    requested,
+    provider,
+    fellBack: false,
+    status: entry?.status ?? "retired",
+    reason: entry?.note ?? `${requested} is unavailable`
+  };
+}
+
 // src/schema/inputs.ts
 import { z } from "zod";
 var transportSchema = z.enum(["http", "subprocess"]);
@@ -2623,6 +2760,9 @@ var podcastInputSchema = z.object({
 var ttsInputSchema = z.object({
   text: z.string(),
   voice: z.string(),
+  /** F037: voice to use if `voice` is one we know the provider has retired. Without
+   *  it a retired voice throws VoiceUnavailableError rather than reaching the API. */
+  voiceFallback: z.string().optional(),
   lang: z.string().optional(),
   format: z.string().optional(),
   rate: z.number().positive().optional(),
@@ -2650,8 +2790,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.27.0";
-var SDK_TAG = "@broberg/ai-sdk@0.27.0";
+var VERSION = "0.28.0";
+var SDK_TAG = "@broberg/ai-sdk@0.28.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -3133,7 +3273,9 @@ function createAI(config = {}) {
       const inputs = input.script.map((turn) => {
         const mapped = input.voices[turn.speaker];
         if (!mapped) throw new Error(`ai.podcast: no voice mapped for speaker "${turn.speaker}"`);
-        return { text: turn.text, voiceId: resolveVoice(mapped) };
+        const res = checkVoice(mapped);
+        if (!res.ok) throw new VoiceUnavailableError(mapped, `${res.reason} \u2014 speaker "${turn.speaker}"`, res.provider);
+        return { text: turn.text, voiceId: res.voiceId };
       });
       const chars = input.script.reduce((n, t) => n + t.text.length, 0);
       return runCapability({
@@ -3154,6 +3296,7 @@ function createAI(config = {}) {
     },
     async tts(input) {
       input = ttsInputSchema.parse(input);
+      const { voiceId } = checkVoice(input.voice, { fallback: input.voiceFallback, throwIfUnavailable: true });
       return runCapability({
         primary: { ...DEFAULT_TTS_SPEC, ...input.override },
         fallback: input.fallback,
@@ -3166,7 +3309,7 @@ function createAI(config = {}) {
         invoke: async (spec) => {
           const adapter = pickProvider(spec.provider);
           if (!adapter.tts) throw new Error(`createAI: provider "${spec.provider}" does not support tts`);
-          return adapter.tts({ text: input.text, voiceId: resolveVoice(input.voice), lang: input.lang, format: input.format, rate: input.rate, spec });
+          return adapter.tts({ text: input.text, voiceId, lang: input.lang, format: input.format, rate: input.rate, spec });
         }
       });
     },
@@ -3614,6 +3757,7 @@ export {
   StreamHttpError,
   UpmetricsCostError,
   VERSION,
+  VoiceUnavailableError,
   aiConfigSchema,
   anthropicAdapter,
   anthropicApiAdapter,
@@ -3622,6 +3766,7 @@ export {
   bflAdapter,
   bflCredits,
   chatInputSchema,
+  checkVoice,
   computeCost,
   createAI,
   deepinfraAdapter,
@@ -3642,6 +3787,7 @@ export {
   imageInputSchema,
   listAzureDanishVoices,
   listModels,
+  listVoices,
   makeContracts,
   makeOpenAICompatibleAdapter,
   messageSchema,