@broberg/ai-sdk 0.64.2 → 0.65.0

package/dist/pricing.d.ts

@@ -56,9 +56,30 @@ interface BasePrice {
      *  rows inherit the inventory snapshot's. */
     checkedAt?: string;
 }
+/** F080.1 — what a token-priced model is FOR. "Cheapest from Mistral" means the
+ *  cheapest CHAT model; without this a moderation endpoint won the question. */
+type PriceKind = "chat" | "embedding" | "moderation" | "ocr" | "transcribe" | "tts" | "image" | "video" | "judge" | "audio";
+/** F080.1 — is the model known to exist upstream, as of the last measurement?
+ *  `listed`: in the provider's own model list (direct) or in the OpenRouter catalogue
+ *  snapshot. `gone`: we priced it, but the provider no longer lists it. `unknown`: we
+ *  never asked that provider — never read it as `listed`. */
+type UpstreamStatus = "listed" | "gone" | "unknown";
 /** A model billed per token. */
 interface TokenModelPrice extends BasePrice {
     unit: "per_1m_tokens";
+    /** F080.1 — chat, embedding, moderation … (see {@link PriceKind}). */
+    kind: PriceKind;
+    /** F080.1 — how WE reach it: our own provider adapter, or OpenRouter. */
+    route: "direct" | "openrouter";
+    /** F080.1 — the `override` that calls exactly this row. */
+    callAs: {
+        provider: string;
+        model: string;
+    };
+    /** F080.1 — a deferred-batch price (`…:batch`), not an interactive one. */
+    batch: boolean;
+    /** F080.1 — see {@link UpstreamStatus}. */
+    upstream: UpstreamStatus;
     /** USD per 1M input tokens. */
     inputPer1M: number;
     /** USD per 1M output tokens. */
@@ -118,6 +139,9 @@ interface PriceFilter {
     /** Only $0/$0 models when true; only paid when false. */
     free?: boolean;
 }
+/** F080.1 — classify a model by its id (and, for OpenRouter rows, what it outputs).
+ *  One place, so "cheapest chat model" and every future filter agree on what chat is. */
+declare function classifyKind(id: string, out?: "text" | "image" | "audio"): PriceKind;
 /** Every non-token price the SDK bills from (F050). Separate from
  *  {@link listModelPrices} because the two answer different questions and mixing
  *  them silently changed what an existing caller's list meant. */
@@ -191,5 +215,62 @@ declare function pricingFreshness(nowMs?: number): PricingFreshness;
 declare function warnIfPricingStale(nowMs?: number): void;
 /** Test-only: forget that we already warned. */
 declare function resetPricingWarningForTests(): void;
+interface CheapestQuery {
+    /** The model maker: "mistral", "openai", "anthropic", "google", "deepseek", … */
+    vendor: string;
+    /** Default "chat". */
+    kind?: PriceKind;
+    /** Only rows we reach this way. Default: both. */
+    route?: "direct" | "openrouter";
+    region?: PriceRegion;
+    /** Deferred-batch prices. Default false — they are not interactive prices. */
+    includeBatch?: boolean;
+    /** Models the provider no longer lists. Default false. */
+    includeGone?: boolean;
+    /** OpenRouter ":free" promo ids (rate-limited, may vanish). Default false. */
+    includeFree?: boolean;
+    /** Default 3. */
+    limit?: number;
+    /** For tests: "now" for the staleness check. */
+    nowMs?: number;
+}
+interface CheapestRow {
+    model: string;
+    /** The `override` that calls exactly this row. */
+    callAs: {
+        provider: string;
+        model: string;
+    };
+    route: "direct" | "openrouter";
+    kind: PriceKind;
+    region: PriceRegion;
+    inputPer1M: number;
+    outputPer1M: number;
+    /** (3 × input + output) / 4 — the ranking key, the same 3:1 blend OpenRouter uses. */
+    blendedPer1M: number;
+    source: "curated" | "inventory";
+    checkedAt?: string;
+    upstream: UpstreamStatus;
+    /** Everything a reader should know before trusting this row. Empty = none. */
+    caveats: string[];
+}
+interface CheapestResult {
+    vendor: string;
+    kind: PriceKind;
+    /** Cheapest first. Empty when nothing matched — never a near-miss from another kind. */
+    results: CheapestRow[];
+    /** How many rows matched before `limit`. */
+    matched: number;
+    /** The token table is older than the freshness threshold (or has no check date). */
+    stale: boolean;
+    checkedAt: string;
+    /** Query-level reservations (e.g. staleness). */
+    caveats: string[];
+}
+/** The cheapest models a vendor offers for one kind of work — with where each price
+ *  came from, when it was checked, and how to call it. Measured on 22 Oct 2026 that
+ *  the obvious sort answered "cheapest from Mistral" with a moderation model that no
+ *  longer exists; this is the answer that does not. */
+declare function cheapestModels(q: CheapestQuery): CheapestResult;
 
-export { DEFAULT_CLIP_SEC, MEDIA_PRICING_CHECKED_AT, type MediaPrice, type MediaUnit, type ModelPrice, PRICING_STALE_AFTER_DAYS, type PriceFilter, type PriceRegion, type PricingFreshness, type UnitFreshness, findModelPrices, getMediaPrice, getModelPrice, listMediaPrices, listModelPrices, priceCall, pricingFreshness, pricingGeneratedAt, resetPricingWarningForTests, warnIfPricingStale };
+export { type CheapestQuery, type CheapestResult, type CheapestRow, DEFAULT_CLIP_SEC, MEDIA_PRICING_CHECKED_AT, type MediaPrice, type MediaUnit, type ModelPrice, PRICING_STALE_AFTER_DAYS, type PriceFilter, type PriceKind, type PriceRegion, type PricingFreshness, type UnitFreshness, type UpstreamStatus, cheapestModels, classifyKind, findModelPrices, getMediaPrice, getModelPrice, listMediaPrices, listModelPrices, priceCall, pricingFreshness, pricingGeneratedAt, resetPricingWarningForTests, warnIfPricingStale };

package/dist/pricing.js

@@ -2,6 +2,8 @@ import {
   DEFAULT_CLIP_SEC,
   MEDIA_PRICING_CHECKED_AT,
   PRICING_STALE_AFTER_DAYS,
+  cheapestModels,
+  classifyKind,
   findModelPrices,
   getMediaPrice,
   getModelPrice,
@@ -12,12 +14,14 @@ import {
   pricingGeneratedAt,
   resetPricingWarningForTests,
   warnIfPricingStale
-} from "./chunk-JMRWFOAC.js";
+} from "./chunk-D53S242W.js";
 import "./chunk-BWBRED4O.js";
 export {
   DEFAULT_CLIP_SEC,
   MEDIA_PRICING_CHECKED_AT,
   PRICING_STALE_AFTER_DAYS,
+  cheapestModels,
+  classifyKind,
   findModelPrices,
   getMediaPrice,
   getModelPrice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/ai-sdk",
-  "version": "0.64.2",
+  "version": "0.65.0",
   "description": "Unified AI/LLM SDK — one facade, all providers, all capabilities, first-class cost control on every call.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",