@broberg/ai-sdk 0.39.0 → 0.41.0

package/dist/pricing.d.ts

@@ -1,22 +1,108 @@
+/** A price that is not per-token.
+ *
+ *  Six units, not the two F050 was carded for. The form-forbidding test found ten
+ *  MORE hand-written price constants than super's report named — speech billed per
+ *  1000 characters, transcription per audio-minute, OCR per page, a flat LoRA
+ *  training fee, and two more per-image tables. Moving only the four that had been
+ *  noticed would have left `caveats` reporting "covered" while four other units sat
+ *  in four adapters' private constants: the same blindness, one unit along. */
+type MediaUnit = "per_sec" | "per_image" | "per_1k_chars" | "per_min" | "per_page" | "per_training";
+interface MediaPrice {
+    unit: MediaUnit;
+    /** USD per second (video) or per generated image. */
+    usd: number;
+    /** ISO date a HUMAN last checked this against the vendor's published price.
+     *  Not derived from the monthly token job — that job never sees these. */
+    checkedAt: string;
+    /** Where the number comes from, so the next person can re-check it. */
+    source: string;
+}
+/** When a human last walked the whole media table against vendor pricing pages.
+ *
+ *  ONE date for the table rather than trusting every row's own: a row added later
+ *  with a fresh date would otherwise pull the table's average forward while the
+ *  older rows sat unrevised. Freshness reads the OLDEST answer, and this is it. */
+declare const MEDIA_PRICING_CHECKED_AT = "2026-09-05";
+/** Default clip length billed when the caller passes no `durationSec`.
+ *
+ *  It is an ASSUMPTION, not a measurement — the provider does not tell us how long
+ *  the clip it returned actually is. Every cost derived from it is stamped
+ *  `costBasis: "estimated"` so a consumer (and upmetrics) can tell it apart from a
+ *  cost computed off a real duration. super reported using such a number as if it
+ *  were measured and passing it on to Christian; that is the damage this stamp
+ *  removes. */
+declare const DEFAULT_CLIP_SEC = 8;
+/** Look up a non-token price. Unknown → undefined (never a fabricated 0). */
+declare function getMediaPrice(provider: string, model: string): MediaPrice | undefined;
+
 type PriceRegion = "eu" | "us" | "cn" | "other";
-interface ModelPrice {
+/** Fields every price row carries, whatever it is billed in. */
+interface BasePrice {
     /** Vendor/provider prefix (e.g. "deepseek", "anthropic"). */
     provider: string;
     /** Model id (OpenRouter-style "vendor/model", or the bare model for curated entries). */
     model: string;
     /** Human label, when known. */
     name?: string;
+    /** GDPR region derived from the PROVIDER NAME — a rough grouping, not a residency
+     *  claim. It is `"other"` for vertex/bfl/fal/azure precisely because those take a
+     *  configurable endpoint, so their region is a property of the CALL and not of the
+     *  model. For an actual residency answer use `regionOfHost()` before the call, or
+     *  `usage.region` after it. */
+    region: PriceRegion;
+    /** "curated" = authoritative hand-maintained number; "inventory" = from inventory.json. */
+    source: "curated" | "inventory";
+    /** ISO date this row was last verified. Media rows carry a HUMAN-set date; token
+     *  rows inherit the inventory snapshot's. */
+    checkedAt?: string;
+}
+/** A model billed per token. */
+interface TokenModelPrice extends BasePrice {
+    unit: "per_1m_tokens";
     /** USD per 1M input tokens. */
     inputPer1M: number;
     /** USD per 1M output tokens. */
     outputPer1M: number;
-    /** Pricing unit (almost always "per_1m_tokens"). */
-    unit: string;
-    /** GDPR region of the host. */
-    region: PriceRegion;
-    /** "curated" = authoritative hand-maintained number; "inventory" = from inventory.json. */
-    source: "curated" | "inventory";
+    /** Set when this model ALSO carries a non-token price — and that is the one the SDK
+     *  bills with (F050.2).
+     *
+     *  Gemini's image models are the real case: they have honest per-token rates for the
+     *  prompt AND a per-image price for the output, and `ai.image` charges the per-image
+     *  one. Returning only the token row is not WRONG the way whisper's fabricated $0 was
+     *  — the rates are real — it just answers a question nobody asked, and hides the
+     *  number that decides the bill. Both are true, so both are here. */
+    alsoBilled?: {
+        unit: MediaUnit;
+        usd: number;
+        checkedAt: string;
+    };
+}
+/** A model billed in anything else — per second, image, 1000 chars, minute, page,
+ *  or training run (F050.2).
+ *
+ *  **It deliberately has NO `inputPer1M`.** Until 0.40.0 a media row carried
+ *  `inputPer1M: 0`, and super's report named the fault exactly: "a field that does not
+ *  apply and a price that is free are the same number again" — the very distinction
+ *  `costBasis: "unpriced"` exists for, one storey down. A 0 there is a placeholder that
+ *  reads as a price. Splitting the type turns reading it into a COMPILE error instead. */
+interface MediaModelPrice extends BasePrice {
+    unit: MediaUnit;
+    /** The price, in USD, for one of whatever `unit` names. ALWAYS set on a media row —
+     *  read this rather than the unit-specific aliases below. */
+    usd: number;
+    /** USD per second. Set ONLY when `unit === "per_sec"`.
+     *
+     *  0.40.0 set this-or-`perImage` from a TWO-armed ternary over SIX units, so every
+     *  non-per-second price was labelled `perImage`: `azure:tts` reported
+     *  `perImage: 0.016` for a price that is per 1000 CHARACTERS. A confident wrong number
+     *  under a name that lies about its own unit — worse than the 0 that was reported. */
+    perSec?: number;
+    /** USD per generated image. Set ONLY when `unit === "per_image"`. */
+    perImage?: number;
 }
+/** A price row. Narrow on `unit` before reading rates:
+ *  `if (p.unit === "per_1m_tokens") … else …`. */
+type ModelPrice = TokenModelPrice | MediaModelPrice;
 interface PriceFilter {
     provider?: string;
     region?: PriceRegion;
@@ -25,13 +111,17 @@ interface PriceFilter {
     /** Only $0/$0 models when true; only paid when false. */
     free?: boolean;
 }
+/** 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. */
+declare function listMediaPrices(): MediaModelPrice[];
 /** Exact price for a model. `modelId` accepts "vendor/model", "provider:model", or a
  *  bare model/basename. Returns undefined if unknown. */
 declare function getModelPrice(modelId: string): ModelPrice | undefined;
 /** Every known model price (inventory, with the curated overlay applied). */
-declare function listModelPrices(): ModelPrice[];
+declare function listModelPrices(): TokenModelPrice[];
 /** Filter the price list (provider / region / max input rate / free-only). */
-declare function findModelPrices(filter?: PriceFilter): ModelPrice[];
+declare function findModelPrices(filter?: PriceFilter): TokenModelPrice[];
 /** Convenience USD compute for a token-priced model; undefined if unknown / not token-priced. */
 declare function priceCall(modelId: string, inputTokens: number, outputTokens: number): number | undefined;
 /** ISO timestamp of the inventory snapshot these prices came from.
@@ -45,6 +135,17 @@ declare function pricingGeneratedAt(): string;
  *  ONE constant: the `model-advisor` skill quotes the same number, and two copies of a
  *  threshold drift apart until the doc and the code disagree about what "stale" means. */
 declare const PRICING_STALE_AFTER_DAYS = 35;
+/** Freshness of ONE pricing unit. */
+interface UnitFreshness {
+    unit: string;
+    /** How many rows the table holds in this unit. Zero means NOT COVERED — which is
+     *  a different answer from "covered and fresh", and used to be indistinguishable. */
+    count: number;
+    /** When a check last happened for this unit. Empty = never. */
+    checkedAt: string;
+    ageDays: number | null;
+    stale: boolean;
+}
 interface PricingFreshness {
     /** When the numbers last CHANGED. */
     generatedAt: string;
@@ -54,9 +155,24 @@ interface PricingFreshness {
     /** Days since `checkedAt`; `null` when there is no check date to measure from. */
     ageDays: number | null;
     /** True when the check is older than {@link PRICING_STALE_AFTER_DAYS} — or when
-     *  there is no check date at all. An unanswerable question is not a pass. */
+     *  there is no check date at all. An unanswerable question is not a pass.
+     *
+     *  **Scope: the TOKEN table only.** Unchanged from F046 on purpose — consumers and
+     *  the release guard already read it. For "is anything I might bill for covered?",
+     *  read {@link PricingFreshness.caveats}. */
     stale: boolean;
     thresholdDays: number;
+    /** Per-unit breakdown (F050). Every unit the SDK can bill in, whether or not the
+     *  table has rows for it — an absent unit must show up as `count: 0`, not as an
+     *  absent key that a caller iterating the object would never notice. */
+    units: UnitFreshness[];
+    /** Human-readable reservations, one per unit that is uncovered or stale.
+     *
+     *  This is the field that makes `stale: false` honest. super measured the state it
+     *  exists to end: `{ageDays: 0, stale: false}` on a table where per-second prices
+     *  could not exist, so the API built to catch price drift reported "fresh" about
+     *  numbers it structurally could not see. Empty array = no reservations. */
+    caveats: string[];
 }
 declare function pricingFreshness(nowMs?: number): PricingFreshness;
 /** Warn ONCE per process that these prices are old. Called from every price lookup.
@@ -69,4 +185,4 @@ declare function warnIfPricingStale(nowMs?: number): void;
 /** Test-only: forget that we already warned. */
 declare function resetPricingWarningForTests(): void;
 
-export { type ModelPrice, PRICING_STALE_AFTER_DAYS, type PriceFilter, type PriceRegion, type PricingFreshness, findModelPrices, getModelPrice, listModelPrices, priceCall, pricingFreshness, pricingGeneratedAt, resetPricingWarningForTests, warnIfPricingStale };
+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 };

package/dist/pricing.js

@@ -1,18 +1,26 @@
 import {
+  DEFAULT_CLIP_SEC,
+  MEDIA_PRICING_CHECKED_AT,
   PRICING_STALE_AFTER_DAYS,
   findModelPrices,
+  getMediaPrice,
   getModelPrice,
+  listMediaPrices,
   listModelPrices,
   priceCall,
   pricingFreshness,
   pricingGeneratedAt,
   resetPricingWarningForTests,
   warnIfPricingStale
-} from "./chunk-QUOZWQ7G.js";
+} from "./chunk-B74RSBT5.js";
 export {
+  DEFAULT_CLIP_SEC,
+  MEDIA_PRICING_CHECKED_AT,
   PRICING_STALE_AFTER_DAYS,
   findModelPrices,
+  getMediaPrice,
   getModelPrice,
+  listMediaPrices,
   listModelPrices,
   priceCall,
   pricingFreshness,

package/package.json

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