@broberg/ai-sdk 0.38.0 → 0.40.0

package/dist/pricing.d.ts

@@ -10,9 +10,22 @@ interface ModelPrice {
     inputPer1M: number;
     /** USD per 1M output tokens. */
     outputPer1M: number;
-    /** Pricing unit (almost always "per_1m_tokens"). */
+    /** Pricing unit: "per_1m_tokens", or "per_sec" / "per_image" for a media model.
+     *  Check it before reading the token rates — they are 0 on a media row, which is a
+     *  placeholder and NOT a claim that the model is free. */
     unit: string;
-    /** GDPR region of the host. */
+    /** USD per second of generated video. Set only when `unit` is "per_sec". */
+    perSec?: number;
+    /** USD per generated image. Set only when `unit` is "per_image". */
+    perImage?: number;
+    /** ISO date this row was last verified. Media rows carry a HUMAN-set date; token
+     *  rows inherit the inventory snapshot's. */
+    checkedAt?: 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";
@@ -25,6 +38,10 @@ 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(): ModelPrice[];
 /** 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;
@@ -45,6 +62,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 +82,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 +112,41 @@ 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 };
+/** 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;
+
+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-KXTCLLVF.js";
 export {
+  DEFAULT_CLIP_SEC,
+  MEDIA_PRICING_CHECKED_AT,
   PRICING_STALE_AFTER_DAYS,
   findModelPrices,
+  getMediaPrice,
   getModelPrice,
+  listMediaPrices,
   listModelPrices,
   priceCall,
   pricingFreshness,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@broberg/ai-sdk",
-  "version": "0.38.0",
-  "description": "Unified AI/LLM SDK \u2014 one facade, all providers, all capabilities, first-class cost control on every call.",
+  "version": "0.40.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",
   "author": "Christian Broberg <cb@webhouse.dk>",