@broberg/ai-sdk 0.46.0 → 0.47.0

package/README.md

@@ -146,6 +146,40 @@ personal data by default; override per call for an even cheaper non-personal rou
 (The `claude -p` subprocess transport is still available via explicit
 `override: { transport: "subprocess" }`, but is no longer a default route.)
 
+## Where WOULD this go? — `wouldRouteTo` (a forecast, not a fact)
+
+`usage.region` answers **where a call went**. It cannot answer *may I send this?*, because
+it only exists once the bytes have left. `wouldRouteTo` answers that half:
+
+```ts
+import { wouldRouteTo } from "@broberg/ai-sdk";
+
+const f = wouldRouteTo("smart");
+// { kind: "forecast", provider: "mistral", host: "https://api.mistral.ai/v1",
+//   wouldRouteTo: "eu", onlyIf: [ …the assumptions… ] }
+```
+
+**It is deliberately not shaped like `usage.region`.** There is no field called `region` on
+it, and that is enforced by a test: a forecast that can be wrong must not wear the clothes
+of a fact that cannot. `onlyIf` comes back **with** the answer rather than living in these
+docs — the answer holds only while you override no `baseUrl` and pass no fallback, because
+**a fallback IS a route and the route decides residency**.
+
+**`"depends-on-config"` is an answer, not a failure.** `azure`, `vertex`, `deepl`, `requesty`
+and `fal` build their host from values you supply. `requesty` is why this state exists: it
+has *both* an EU and a non-EU host, so any region we named there would be a residency claim
+decided by a table instead of by a route.
+
+**It refuses nothing.** It never throws and never blocks a call — not even for a nonsense
+provider. Residency policy belongs to each consumer, not to this package; this is the
+information that makes that decision possible, which is the opposite of a gate.
+
+**Why it can say `"eu"` where `regionOfProvider` says `"unknown"`:** it asks the *host* the
+SDK would actually use, not the provider's *name*. `regionOfProvider("mistral")` is
+`"unknown"` by design — that adapter takes a `baseUrl`. Filed by a consumer who had
+hand-copied our tier table into their own repo to answer this; that copy can now be deleted
+instead of maintained.
+
 ## Cost, budget & sinks
 
 ```ts

package/dist/index.d.ts

@@ -2534,8 +2534,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.46.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.46.0";
+declare const VERSION: "0.47.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.47.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.
@@ -2881,6 +2881,69 @@ interface PricingEntry {
 }
 declare function getPrice(provider: string, model: string): PricingEntry | undefined;
 
+/** What a forecast can say. `"depends-on-config"` is NOT a region — it is the honest
+ *  answer for a provider whose host you supply part of (azure, vertex, deepl, requesty,
+ *  fal). `requesty` is why it exists: it has both an EU and a non-EU host, so a table
+ *  answering there would be a residency claim decided by a table rather than by a route. */
+type RouteForecast = {
+    kind: "forecast";
+    /** The provider the tier resolves to today. */
+    provider: string;
+    /** The host the SDK would use if you override nothing. */
+    host: string;
+    /** Region of THAT host. Only `"eu"` is a positive claim — `"unknown"` means we
+     *  cannot say, never "probably fine". */
+    wouldRouteTo: Region;
+    /** The assumptions, returned WITH the answer rather than left in the docs. Never
+     *  empty: a forecast whose conditions are invisible reads as a fact. */
+    onlyIf: string[];
+} | {
+    kind: "depends-on-config";
+    provider: string;
+    /** Why no table can answer for this provider. */
+    because: string;
+    onlyIf: string[];
+} | {
+    kind: "unknown-provider";
+    provider: string;
+    onlyIf: string[];
+};
+/** Forecast for a PROVIDER, using the host the SDK would default to. */
+declare function wouldProviderRouteTo(provider: string): RouteForecast;
+/** Forecast for a TIER — the question helpdesk actually asked. */
+declare function wouldRouteTo(tier: Tier): RouteForecast;
+
+/** Providers whose default endpoint is a FIXED host. */
+declare const DEFAULT_BASE_URLS: {
+    readonly anthropic: "https://api.anthropic.com";
+    readonly deepinfra: "https://api.deepinfra.com/v1/openai";
+    readonly deepseek: "https://api.deepseek.com/v1";
+    readonly elevenlabs: "https://api.elevenlabs.io/v1";
+    readonly gemini: "https://generativelanguage.googleapis.com/v1beta";
+    readonly mistral: "https://api.mistral.ai/v1";
+    readonly openai: "https://api.openai.com/v1";
+    readonly openrouter: "https://openrouter.ai/api/v1";
+};
+type FixedHostProvider = keyof typeof DEFAULT_BASE_URLS;
+/** `bfl` is DELIBERATELY ABSENT. Its adapter hard-pins `https://api.eu.bfl.ai` in a local
+ *  constant and calls that pin the GDPR crux, non-negotiable — faces and portraits go
+ *  through it. Hoisting the value here would make a deliberate pin editable from a shared
+ *  file that nine other providers also read, which is a worse trade than one more name for
+ *  one URL. It is not a drifting copy either: there is exactly one place, it is just not
+ *  this one. The scanner below does not flag it because bfl never used the
+ *  `baseUrl ?? "https://…"` form it forbids. */
+declare const LOCALLY_PINNED_HOSTS: Record<string, string>;
+/** Providers whose host is DERIVED FROM CONFIG, so no table can answer for them.
+ *
+ *  Measured 12 September 2026, and this list is the honest half of F056: a flat
+ *  "default host per provider" table would answer for these too, and be wrong in the
+ *  GREEN direction — it would say something instead of saying it cannot.
+ *
+ *  `requesty` is the sharp one: it has BOTH an EU and a non-EU host, so a guess there
+ *  would be a residency claim decided by a table rather than by the route. */
+declare const CONFIG_DERIVED_HOSTS: Record<string, string>;
+declare function defaultBaseUrl(provider: string): string | undefined;
+
 interface TransportRequest {
     /** Resolved routing for this call (transport field selects the path). */
     spec: TierSpec;
@@ -2946,4 +3009,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 AlignedWordTimings, type AzureVoiceInfo, type AzureWordBoundary, 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 Region, 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, type WordTiming, aiConfigSchema, alignWordTimings, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, chatInputSchema, checkVoice, classifyRegionName, 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, regionOfHost, regionOfProvider, 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 AlignedWordTimings, type AzureVoiceInfo, type AzureWordBoundary, type BatchJob, type BatchRequestItem, type BatchResultItem, type BflAdapterConfig, type BflCredits, type BudgetConfig, BudgetExceededError, BudgetGuard, type BudgetStore, CONFIG_DERIVED_HOSTS, 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_BASE_URLS, 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 FixedHostProvider, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, LOCALLY_PINNED_HOSTS, 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 Region, type RerankInput, type RerankResult, type Role, type RouteForecast, 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, type WordTiming, aiConfigSchema, alignWordTimings, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, chatInputSchema, checkVoice, classifyRegionName, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultBaseUrl, 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, regionOfHost, regionOfProvider, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema, wouldProviderRouteTo, wouldRouteTo };

package/dist/index.js

@@ -20,6 +20,31 @@ import {
   pricingGeneratedAt
 } from "./chunk-OWXXPBKN.js";
 
+// src/cost/default-hosts.ts
+var DEFAULT_BASE_URLS = {
+  anthropic: "https://api.anthropic.com",
+  deepinfra: "https://api.deepinfra.com/v1/openai",
+  deepseek: "https://api.deepseek.com/v1",
+  elevenlabs: "https://api.elevenlabs.io/v1",
+  gemini: "https://generativelanguage.googleapis.com/v1beta",
+  mistral: "https://api.mistral.ai/v1",
+  openai: "https://api.openai.com/v1",
+  openrouter: "https://openrouter.ai/api/v1"
+};
+var LOCALLY_PINNED_HOSTS = {
+  bfl: "https://api.eu.bfl.ai"
+};
+var CONFIG_DERIVED_HOSTS = {
+  azure: "host comes from your region + resource name",
+  vertex: "host comes from your region (europe-west1 by default)",
+  deepl: "host differs between the free and paid plans",
+  requesty: "has BOTH an EU and a non-EU host \u2014 your config decides",
+  fal: "uses several hosts depending on the call"
+};
+function defaultBaseUrl(provider) {
+  return DEFAULT_BASE_URLS[provider];
+}
+
 // src/transport/http.ts
 async function httpTransport(req) {
   if (!req.http) {
@@ -401,7 +426,7 @@ function flattenForSubprocess(messages) {
   return { prompt: turns.join("\n\n"), system: sys.length ? sys.join("\n") : void 0 };
 }
 function anthropicAdapter(config = {}) {
-  const baseUrl = config.baseUrl ?? "https://api.anthropic.com";
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URLS.anthropic;
   const version = config.anthropicVersion ?? "2023-06-01";
   function buildBody(req) {
     const system = [];
@@ -892,7 +917,7 @@ function mapFinishReason(reason) {
 
 // src/providers/openai.ts
 function openaiAdapter(config = {}) {
-  const baseUrl = config.baseUrl ?? "https://api.openai.com/v1";
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URLS.openai;
   const base = makeOpenAICompatibleAdapter({ name: "openai", baseUrl, apiKey: config.apiKey });
   async function embedding(req) {
     const apiKey = config.apiKey ?? process.env.OPENAI_API_KEY;
@@ -1010,7 +1035,7 @@ function partsFrom(content) {
   });
 }
 function geminiAdapter(config = {}) {
-  const baseUrl = config.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta";
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URLS.gemini;
   function resolveKey() {
     const apiKey = config.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY;
     if (!apiKey) throw new Error("gemini adapter: API key not set (env GOOGLE_API_KEY or GEMINI_API_KEY)");
@@ -1239,14 +1264,14 @@ function mapGeminiFinish(reason) {
 function deepinfraAdapter(config = {}) {
   return makeOpenAICompatibleAdapter({
     name: "deepinfra",
-    baseUrl: config.baseUrl ?? "https://api.deepinfra.com/v1/openai",
+    baseUrl: config.baseUrl ?? DEFAULT_BASE_URLS.deepinfra,
     apiKey: config.apiKey
   });
 }
 
 // src/providers/openrouter.ts
 function openrouterAdapter(config = {}) {
-  const baseUrl = config.baseUrl ?? "https://openrouter.ai/api/v1";
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URLS.openrouter;
   const headers = {
     "HTTP-Referer": config.referer ?? "https://broberg.ai",
     "X-Title": config.title ?? "@broberg/ai-sdk"
@@ -1328,7 +1353,7 @@ function deepseekAdapter(config = {}) {
   return makeOpenAICompatibleAdapter({
     name: "deepseek",
     // → key DEEPSEEK_API_KEY
-    baseUrl: config.baseUrl ?? "https://api.deepseek.com/v1",
+    baseUrl: config.baseUrl ?? DEFAULT_BASE_URLS.deepseek,
     apiKey: config.apiKey,
     // Direct API returns no usage.cost → price from the table (not response).
     costFromResponseField: false
@@ -1337,7 +1362,7 @@ function deepseekAdapter(config = {}) {
 
 // src/providers/mistral.ts
 function mistralAdapter(config = {}) {
-  const baseUrl = config.baseUrl ?? "https://api.mistral.ai/v1";
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URLS.mistral;
   const base = makeOpenAICompatibleAdapter({ name: "mistral", baseUrl, apiKey: config.apiKey, supportsPromptCacheKey: true, supportsPrefix: true });
   function key() {
     const k = config.apiKey ?? process.env.MISTRAL_API_KEY;
@@ -1591,7 +1616,7 @@ function ttsText(req) {
   return applyPronunciations(req.text, req.pronunciations, (p) => p.alias);
 }
 function elevenlabsAdapter(config = {}) {
-  const baseUrl = config.baseUrl ?? "https://api.elevenlabs.io/v1";
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URLS.elevenlabs;
   const fetchImpl = config.fetch ?? fetch;
   function key() {
     const k = config.apiKey ?? process.env.ELEVENLABS_API_KEY;
@@ -3337,8 +3362,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.46.0";
-var SDK_TAG = "@broberg/ai-sdk@0.46.0";
+var VERSION = "0.47.0";
+var SDK_TAG = "@broberg/ai-sdk@0.47.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -4345,14 +4370,39 @@ function upmetricsCostClient(config) {
     }
   };
 }
+
+// src/cost/would-route.ts
+var ASSUMPTIONS = [
+  "you do not set your own baseUrl \u2014 we cannot know where your gateway forwards to",
+  "you pass no fallback: a fallback IS a route, and the route decides residency",
+  "you pass no override that changes the provider"
+];
+function wouldProviderRouteTo(provider) {
+  const onlyIf = [...ASSUMPTIONS];
+  const host = DEFAULT_BASE_URLS[provider] ?? LOCALLY_PINNED_HOSTS[provider];
+  if (host) {
+    return { kind: "forecast", provider, host, wouldRouteTo: regionOfHost(host), onlyIf };
+  }
+  const because = CONFIG_DERIVED_HOSTS[provider];
+  if (because) return { kind: "depends-on-config", provider, because, onlyIf };
+  return { kind: "unknown-provider", provider, onlyIf };
+}
+function wouldRouteTo(tier) {
+  const spec = DEFAULT_TIER_MAP[tier];
+  if (!spec) return { kind: "unknown-provider", provider: String(tier), onlyIf: [...ASSUMPTIONS] };
+  return wouldProviderRouteTo(spec.provider);
+}
 export {
   AZURE_DANISH_VOICES,
   AZURE_DANISH_VOICE_LIST,
   BudgetExceededError,
   BudgetGuard,
+  CONFIG_DERIVED_HOSTS,
+  DEFAULT_BASE_URLS,
   DEFAULT_CLIP_SEC,
   DEFAULT_TIER_MAP,
   ELEVENLABS_DANISH_VOICES,
+  LOCALLY_PINNED_HOSTS,
   MEDIA_PRICING_CHECKED_AT,
   ModelUnavailableError,
   PRICING_STALE_AFTER_DAYS,
@@ -4377,6 +4427,7 @@ export {
   deepinfraAdapter,
   deeplAdapter,
   deepseekAdapter,
+  defaultBaseUrl,
   defaultProviders,
   discordSink,
   elevenlabsAdapter,
@@ -4432,6 +4483,8 @@ export {
   upmetricsSink,
   usdFromMicro,
   vertexAdapter,
-  visionInputSchema
+  visionInputSchema,
+  wouldProviderRouteTo,
+  wouldRouteTo
 };
 //# sourceMappingURL=index.js.map