usage-tab 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+/**
+ * Registry schema — model identity and pricing periods.
+ *
+ * This is the contract `usage-tab` consumes directly, and that `chat-fit`
+ * optionally consumes for context-window helpers. Changing a field here is
+ * a breaking change for both packages.
+ */
+type ProviderId = 'openai' | 'anthropic' | 'google' | 'azure-openai' | 'aws-bedrock' | 'groq' | 'mistral' | 'cohere' | 'together' | 'openrouter';
+/**
+ * Provenance for a registry entry: where the data came from and when it was
+ * last reviewed against that source. Distinct from a pricing period's own
+ * `sourceUrl`/`observedAt`, which track the price specifically — a model's
+ * identity metadata (context window, capabilities) and its price can be
+ * confirmed on different dates.
+ */
+interface RegistrySource {
+    readonly url: string;
+    /** ISO date (YYYY-MM-DD) the data was observed/reviewed. */
+    readonly observedAt: string;
+    readonly notes?: readonly string[];
+}
+/**
+ * A priced interval for one model. Rates are decimal STRINGS end to end — a
+ * price must never pass through a JavaScript `number` on its authoritative
+ * path: money must never be calculated with binary floating point.
+ * Consumers (e.g. `usage-tab`) parse them into fixed-point integers
+ * themselves; this package never does arithmetic on them.
+ *
+ * A period is active for `effectiveFrom <= at < effectiveTo` — `effectiveTo`
+ * is exclusive so a restated price takes over cleanly at midnight of its own
+ * effective date, with no shared instant between two periods. Omit
+ * `effectiveTo` for the current, open-ended period. See `pricing-period.ts`.
+ */
+interface PricingPeriod {
+    /** ISO date (YYYY-MM-DD) the period starts being active (inclusive). */
+    readonly effectiveFrom: string;
+    /** ISO date (YYYY-MM-DD) the period stops being active (exclusive). */
+    readonly effectiveTo?: string;
+    readonly currency: 'USD';
+    readonly unit: 'per-million-tokens';
+    readonly input: string;
+    readonly output: string;
+    readonly cachedInput?: string;
+    readonly cacheWrite?: string;
+    readonly reasoning?: string;
+    /** Multiplier applied to all token usage under the provider's batch API, e.g. `"0.5"` for a 50% discount. */
+    readonly batchMultiplier?: string;
+    /**
+     * `true` when this period records the cheapest of several published
+     * pricing tiers for the same model — e.g. Google's <=200k-token prompt-size
+     * tier (a higher rate applies above it), or Azure OpenAI's Global
+     * deployment + short-context + Standard service tier (Data Zone/Regional
+     * deployment, long-context, and Priority Processing each cost more). This
+     * schema has no dimension for the tier itself — only a flag that one
+     * exists — because the extra dimensions differ per provider (prompt size,
+     * deployment region, context length, service tier) and are not uniform
+     * enough to model generically. Consumers (`usage-tab`) surface a warning
+     * whenever a calculation uses a period with this flag set, since real usage
+     * under a different tier costs more than the calculation reports — never
+     * omit this on a period whose provider file documents a higher unrecorded
+     * tier: accuracy matters more than breadth here, and under-reporting cost
+     * is the worst failure a pricing library can make.
+     * Omit entirely (never `false`) when the recorded rate is the only
+     * published tier.
+     */
+    readonly cheapestTier?: true;
+    /**
+     * URL of the authoritative documentation this rate was read from.
+     * Mandatory: every pricing period carries a source URL, an observed date,
+     * and an effective date.
+     */
+    readonly sourceUrl: string;
+    /** ISO date (YYYY-MM-DD) the rate was observed/reviewed against `sourceUrl`. */
+    readonly observedAt: string;
+    readonly notes?: readonly string[];
+}
+interface ModelDescriptor {
+    readonly canonicalId: string;
+    readonly provider: ProviderId;
+    readonly aliases: readonly string[];
+    readonly family?: string;
+    readonly tokenizerFamily?: string;
+    readonly contextWindow?: number;
+    readonly capabilities?: readonly string[];
+    readonly pricing?: readonly PricingPeriod[];
+    readonly source?: RegistrySource;
+}
+
+/**
+ * Stable error types for `@llm-kit/model-registry`.
+ *
+ * Every error extends `Error`, sets a stable string `code`, and carries an
+ * actionable message. Callers branch on `code`, never on `message` text —
+ * messages may be reworded.
+ */
+interface ModelCandidate {
+    readonly provider: string;
+    readonly canonicalId: string;
+}
+/**
+ * Raised by `resolveModel` (resolution step 6) when a requested model id
+ * matches nothing — not a custom override, not a provider-qualified
+ * canonical id or alias, not a globally unambiguous alias (only reachable
+ * when no provider was supplied — a provider qualifier is a constraint, not
+ * a hint), and no fallback was configured or matched.
+ */
+declare class UnknownModelError extends Error {
+    readonly code = "UNKNOWN_MODEL";
+    readonly requestedId: string;
+    readonly provider?: string;
+    /**
+     * Set only when the lookup was provider-qualified and `requestedId` exists
+     * under one or more *other* providers — the single most actionable fact
+     * for this failure. Sorted, deduplicated, and never the full registry:
+     * just the providers that actually carry this id.
+     */
+    readonly otherProviders?: readonly string[];
+    constructor(requestedId: string, provider?: string, otherProviders?: readonly string[]);
+}
+/**
+ * Raised by `resolveModel` whenever a requested model id would resolve to
+ * more than one distinct model. Ambiguity is always an error, never a guess —
+ * this is the single most important invariant this package enforces, since
+ * silently picking one candidate is how a caller gets billed against the
+ * wrong model.
+ */
+declare class AmbiguousAliasError extends Error {
+    readonly code = "AMBIGUOUS_ALIAS";
+    readonly requestedId: string;
+    readonly candidates: readonly ModelCandidate[];
+    constructor(requestedId: string, candidates: readonly ModelCandidate[]);
+}
+/**
+ * Raised by `selectPricingPeriod` when the `at` lookup value cannot be
+ * parsed as a date. Distinct from "no period matches" (a normal result,
+ * represented by `undefined` — see `pricing-period.ts`), which is not an
+ * error.
+ */
+declare class InvalidLookupDateError extends Error {
+    readonly code = "INVALID_LOOKUP_DATE";
+    readonly value: string;
+    constructor(value: string);
+}
+
+type ModelMatchKind = 'override' | 'canonical-qualified' | 'alias-scoped' | 'alias-global' | 'fallback';
+
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Produced by `scripts/generate-model-registry.ts` from the reviewed source
+ * files under `docs/provider-data/`. Editing this file directly is forbidden.
+ *
+ * Regenerate: pnpm exec tsx scripts/generate-model-registry.ts
+ * Verify:     pnpm exec tsx scripts/generate-model-registry.ts --check
+ */
+
+declare const REGISTRY_VERSION = "registry-5af85ce1a47be918";
+declare const MODEL_REGISTRY: readonly ModelDescriptor[];
+
+/**
+ * Public types.
+ */
+
+/**
+ * Normalized token usage for one request. `inputTokens` and `outputTokens`
+ * are the *total* reported counts; `cachedInputTokens` and `cacheWriteTokens`
+ * are subsets of `inputTokens`, and `reasoningTokens` is a subset of
+ * `outputTokens`, unless a specific provider adapter documents otherwise
+ * — see `normalize/anthropic.ts` and `normalize/google.ts`
+ * for the two adapters that must add rather than assume a subset relationship
+ * in the provider's own raw shape.
+ */
+interface LlmUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+}
+type PriceMode = 'standard' | 'batch';
+interface PriceRequest {
+    /** The id you have — a canonical id or an alias, from any provider. */
+    readonly model: string;
+    /**
+     * Qualifies resolution to one provider (resolution steps 2–3). Omit to
+     * resolve globally (step 4). `calculateCost` also accepts a provider
+     * qualifier on its `options` bag (`PriceOptions.provider`, useful when a
+     * `PriceCalculator` was built with a default) — when both are supplied,
+     * `request.provider` takes precedence. Either channel populates
+     * `CostBreakdown.requestedProvider`, so it is never a way to tell which
+     * one was used.
+     */
+    readonly provider?: ProviderId | string;
+    /**
+     * Already-normalized usage, or a raw value structurally close enough to
+     * `LlmUsage` to be used directly (numeric `inputTokens`/`outputTokens`).
+     * Anything else — a raw OpenAI/Anthropic/Google response object — must go
+     * through the matching `normalize*Usage` adapter first; `calculateCost`
+     * never guesses a provider's field names for you.
+     */
+    readonly usage: LlmUsage | unknown;
+    /** `'batch'` applies the resolved period's `batchMultiplier` when one is published; falls back to standard pricing (with a warning) otherwise. */
+    readonly mode?: PriceMode;
+    /** Effective date for pricing-period selection. Defaults to `new Date()`. */
+    readonly at?: Date | string;
+}
+interface CostLine {
+    /** Token count this line was billed against. */
+    readonly tokens: number;
+    /** The decimal USD-per-million-tokens rate actually applied, after any batch multiplier. */
+    readonly rate: string;
+    readonly costUsd: number;
+    readonly costUsdExact: string;
+}
+type PriceWarningCode = 'UNSUPPORTED_USAGE_FIELD' | 'CACHED_EXCEEDS_INPUT' | 'REASONING_EXCEEDS_OUTPUT' | 'BATCH_PRICING_UNAVAILABLE' | 'PARTIAL_TIER_PRICING' | 'REASONING_PRICED_AS_OUTPUT' | 'CACHED_INPUT_PRICED_AS_INPUT' | 'CACHE_WRITE_PRICED_AS_INPUT';
+/**
+ * A non-fatal condition surfaced alongside a `CostBreakdown` — the same rule
+ * that keeps unsupported usage fields visible as warnings, never silently
+ * discarded, extended to every other place this package must not
+ * fail silently. Always JSON-serializable. Never a substitute for an error:
+ * anything that would make the reported cost meaningless (an unresolvable
+ * model, no priced period for the lookup date) throws instead of warning —
+ * see `errors.ts`.
+ */
+interface PriceWarning {
+    readonly code: PriceWarningCode;
+    readonly message: string;
+    /** Usage or pricing field the warning concerns, when applicable. */
+    readonly field?: string;
+}
+interface CostBreakdown {
+    /** The id exactly as requested. */
+    readonly model: string;
+    /** The resolved registry entry's canonical id — may differ from `model` when `model` was an alias. */
+    readonly canonicalModel: string;
+    readonly provider: string;
+    /**
+     * How `model` was matched (registry resolution steps 1–5 — see
+     * `ResolveModelOptions`/`resolveModel`). Surfaced so a caller can tell a
+     * plain provider-qualified match (`'canonical-qualified'`/`'alias-scoped'`)
+     * apart from one that only succeeded via an explicitly configured
+     * `fallback` — the one remaining path (by design, not an oversight: see
+     * README "Edge cases and limitations") where `provider` can legitimately
+     * differ from the `provider` you requested.
+     */
+    readonly matchedBy: ModelMatchKind;
+    /** The provider qualifier exactly as requested, when one was supplied on either `request.provider` or `options.provider` (see `PriceRequest.provider`). Compare against `provider` to notice a `fallback` match that landed on a different provider. */
+    readonly requestedProvider?: string;
+    readonly currency: 'USD';
+    readonly input: CostLine;
+    readonly output: CostLine;
+    readonly cachedInput?: CostLine;
+    readonly cacheWrite?: CostLine;
+    readonly reasoning?: CostLine;
+    /** Ergonomic numeric total. Not the authoritative value — see `totalUsdExact`. */
+    readonly totalUsd: number;
+    /** Exact decimal string total, computed with integer/BigInt fixed-point arithmetic — the authoritative value; never derived from binary floating point. */
+    readonly totalUsdExact: string;
+    /** Content hash of the pricing data used (`@llm-kit/model-registry`'s `REGISTRY_VERSION`), independent of this package's own npm version. */
+    readonly registryVersion: string;
+    /** `effectiveFrom` of the pricing period actually used. */
+    readonly pricingEffectiveFrom: string;
+    readonly warnings: readonly PriceWarning[];
+}
+/** Return shape of every `normalize*Usage` adapter (and the internal generic fallback). */
+interface NormalizedUsageResult {
+    readonly usage: LlmUsage;
+    readonly warnings: readonly PriceWarning[];
+}
+interface ResolveModelOptions {
+    readonly provider?: ProviderId | string;
+    readonly overrides?: readonly ModelDescriptor[];
+    readonly fallback?: string;
+    /** Registry to resolve against. Defaults to the bundled `MODEL_REGISTRY`; overriding is mainly for tests. */
+    readonly registry?: readonly ModelDescriptor[];
+}
+interface ResolvedModel {
+    readonly descriptor: ModelDescriptor;
+    readonly matchedBy: ModelMatchKind;
+    readonly requestedId: string;
+    readonly requestedProvider?: string;
+}
+/**
+ * `PriceOptions.provider` and `PriceRequest.provider` are the same
+ * qualifier on two channels — see `PriceRequest.provider`'s doc comment for
+ * the precedence rule `calculateCost` applies between them.
+ */
+type PriceOptions = ResolveModelOptions;
+interface PriceCalculatorOptions {
+    readonly overrides?: readonly ModelDescriptor[];
+    readonly fallback?: string;
+    readonly registry?: readonly ModelDescriptor[];
+}
+interface PriceCalculator {
+    calculateCost(request: PriceRequest, options?: PriceOptions): CostBreakdown;
+    resolveModel(model: string, options?: ResolveModelOptions): ResolvedModel;
+}
+/** Input to `createPriceOverride` — a simplified way to build one custom `ModelDescriptor` without hand-writing the full registry shape. */
+interface CustomPriceInput {
+    readonly canonicalId: string;
+    /**
+     * Defaults to `'custom'`. Typed as a plain `string`, not `ProviderId` —
+     * unlike registry source data (schema-validated against the baseline
+     * provider list), a custom override may represent a negotiated deal with a
+     * vendor outside that list, and `resolveModel` never enforces `ProviderId`
+     * at runtime, only at the registry-generation boundary.
+     */
+    readonly provider?: string;
+    readonly aliases?: readonly string[];
+    readonly family?: string;
+    readonly contextWindow?: number;
+    readonly input: string;
+    readonly output: string;
+    readonly cachedInput?: string;
+    readonly cacheWrite?: string;
+    readonly reasoning?: string;
+    readonly batchMultiplier?: string;
+    /** ISO date. Defaults to `'1970-01-01'` (always active). */
+    readonly effectiveFrom?: string;
+    readonly effectiveTo?: string;
+    readonly sourceUrl?: string;
+    /** ISO date. Defaults to `effectiveFrom`. */
+    readonly observedAt?: string;
+    readonly notes?: readonly string[];
+}
+
+declare function calculateCost(request: PriceRequest, options?: PriceOptions): CostBreakdown;
+
+declare function resolveModel(model: string, options?: ResolveModelOptions): ResolvedModel;
+
+declare function createPriceCalculator(defaults?: PriceCalculatorOptions): PriceCalculator;
+
+/**
+ * Custom/negotiated pricing overrides — an exact custom override is the
+ * highest-precedence resolution step.
+ */
+
+/**
+ * Builds a single-period `ModelDescriptor` from a simplified rate shape, for
+ * passing as `options.overrides` to `calculateCost`/`resolveModel`/
+ * `createPriceCalculator` — without hand-writing the full registry schema
+ * (`sourceUrl`, `observedAt`, etc. are given sensible, deterministic
+ * defaults rather than reading the system clock, so the result is a pure
+ * function of its input).
+ */
+declare function createPriceOverride(input: CustomPriceInput): ModelDescriptor;
+
+/**
+ * Stable error types this package throws directly. `resolveModel` and
+ * `calculateCost` also propagate `AmbiguousAliasError`, `UnknownModelError`,
+ * and `InvalidLookupDateError` unchanged from `@llm-kit/model-registry` (see
+ * `index.ts`) — they are not redefined here, so a caller catching by `code`
+ * only ever deals with one class per code, regardless of which package threw
+ * it.
+ *
+ * Every error extends `Error`, sets a stable string `code`, and carries an
+ * actionable message. Normal conditions —
+ * an unsupported usage field, a period recording only the cheapest of
+ * several tiers — are `PriceWarning`s (see `types.ts`), not exceptions;
+ * these classes are reserved for conditions where the reported cost would
+ * otherwise be meaningless or silently wrong.
+ */
+/**
+ * Raised by `calculateCost` when `selectPricingPeriod` finds no period
+ * covering the lookup date — including a lookup date that precedes the
+ * first known period for a model. Returning a zero or default cost here
+ * would be exactly the silent under-reporting this package exists to
+ * prevent, so this is a thrown error, never a warning.
+ */
+declare class NoPricingPeriodError extends Error {
+    readonly code = "NO_PRICING_PERIOD";
+    readonly canonicalModel: string;
+    readonly provider: string;
+    readonly at: string;
+    constructor(canonicalModel: string, provider: string, at: string);
+}
+/**
+ * Raised when `PriceRequest.usage` is neither an `LlmUsage`-shaped object
+ * (numeric `inputTokens`/`outputTokens`) nor something a `normalize*Usage`
+ * adapter already turned into one. `calculateCost` never guesses a raw
+ * provider response's field names — call the matching adapter first.
+ */
+declare class InvalidUsageError extends Error {
+    readonly code = "INVALID_USAGE";
+    constructor(reason: string);
+}
+/**
+ * Raised when a token count is negative, non-integer, or not a JS safe
+ * integer. Very large aggregate token counts are expected to work up to
+ * `Number.MAX_SAFE_INTEGER`; beyond that, or below zero, or fractional, the
+ * count is rejected rather than silently coerced.
+ */
+declare class InvalidTokenCountError extends Error {
+    readonly code = "INVALID_TOKEN_COUNT";
+    readonly field: string;
+    readonly value: number;
+    constructor(field: string, value: number);
+}
+/**
+ * Raised when a pricing-period rate string does not parse as an exact
+ * non-negative decimal. Registry data is validated at generation time
+ * (`@llm-kit/model-registry`'s schema), so this only fires for a malformed
+ * `createPriceOverride`/custom `ModelDescriptor` supplied at the call site.
+ */
+declare class InvalidRateError extends Error {
+    readonly code = "INVALID_RATE";
+    readonly field: string;
+    readonly value: string;
+    constructor(field: string, value: string);
+}
+
+declare function normalizeOpenAIUsage(value: unknown): NormalizedUsageResult;
+
+declare function normalizeAnthropicUsage(value: unknown): NormalizedUsageResult;
+
+declare function normalizeGoogleUsage(value: unknown): NormalizedUsageResult;
+
+declare function normalizeOpenAICompatibleUsage(value: unknown): NormalizedUsageResult;
+
+export { AmbiguousAliasError, type CostBreakdown, type CostLine, type CustomPriceInput, InvalidLookupDateError, InvalidRateError, InvalidTokenCountError, InvalidUsageError, type LlmUsage, MODEL_REGISTRY, type ModelCandidate, type ModelDescriptor, NoPricingPeriodError, type NormalizedUsageResult, type PriceCalculator, type PriceCalculatorOptions, type PriceMode, type PriceOptions, type PriceRequest, type PriceWarning, type PriceWarningCode, type PricingPeriod, type ProviderId, REGISTRY_VERSION, type RegistrySource, type ResolveModelOptions, type ResolvedModel, UnknownModelError, calculateCost, createPriceCalculator, createPriceOverride, normalizeAnthropicUsage, normalizeGoogleUsage, normalizeOpenAICompatibleUsage, normalizeOpenAIUsage, resolveModel };