@bymax-one/nest-ai-tokens 1.0.0

package/dist/shared/index.d.cts

@@ -0,0 +1,1044 @@
+/**
+ * @fileoverview Catalog of the AI providers this library recognizes out of the
+ * box. Custom OpenAI-compatible providers register their own id at runtime via
+ * `providerPresets.openaiCompatible(id)`, so the public {@link ProviderId} type
+ * (see `types/catalogs.ts`) widens this closed list with `(string & {})`.
+ * @layer shared
+ */
+/**
+ * The provider identifiers shipped with the library. Frozen tuple so the derived
+ * {@link KnownProviderId} union stays in sync with the runtime values.
+ */
+declare const PROVIDER_IDS: readonly ["openai", "azure-openai", "anthropic", "gemini", "vertex", "mistral", "bedrock", "openrouter", "deepseek", "xai", "groq"];
+/** A provider id known to the library at build time (excludes custom ids). */
+type KnownProviderId = (typeof PROVIDER_IDS)[number];
+
+/**
+ * @fileoverview Catalog of AI operation kinds a usage record can describe. The
+ * operation is part of the price-resolution key; `'responses'` bills identically
+ * to `'chat'` and shares its price rows (see spec §5.1).
+ * @layer shared
+ */
+/** Every operation kind the library can meter and price. */
+declare const AI_OPERATIONS: readonly ["chat", "responses", "embeddings", "image", "video", "audio", "rerank", "moderation"];
+/** A logical AI operation kind. */
+type AiOperation = (typeof AI_OPERATIONS)[number];
+
+/**
+ * @fileoverview Catalog of response service tiers. Providers may silently
+ * downgrade a request (OpenAI returns `service_tier: "default"` when priority
+ * capacity is exhausted), so pricing keys off the tier reported in the RESPONSE,
+ * which is what the normalizers read (see spec §5.1).
+ * @layer shared
+ */
+/**
+ * Service tier of the actual response. `'batch'` is the Batch API (~50% discount);
+ * `'flex'` is OpenAI flex processing (batch rates, synchronous); `'priority'` is
+ * paid premium; `'standard'` is the default.
+ */
+declare const SERVICE_TIERS: readonly ["standard", "batch", "flex", "priority"];
+/** A response service tier. */
+type ServiceTier = (typeof SERVICE_TIERS)[number];
+
+/**
+ * @fileoverview Catalog of the token categories that are rated independently.
+ * Cache reads/writes are first-class because a naive input/output-only model
+ * over-bills cached traffic by up to 10× (see spec §5.4).
+ * @layer shared
+ */
+/** Every token category that carries its own per-million rate. */
+declare const TOKEN_CATEGORIES: readonly ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1h", "reasoning", "audioIn", "audioOut", "imageIn", "imageOut"];
+/** A single rated token category. */
+type TokenCategory = (typeof TOKEN_CATEGORIES)[number];
+
+/**
+ * @fileoverview Catalog of wallet entry kinds. Balances are the signed sum of
+ * these append-only entries (see spec §9.1).
+ * @layer shared
+ */
+/** Every kind of entry that can appear in a wallet's append-only ledger. */
+declare const WALLET_ENTRY_TYPES: readonly ["grant", "debit", "refund", "adjustment", "expiry"];
+/** A wallet entry kind. */
+type WalletEntryType = (typeof WALLET_ENTRY_TYPES)[number];
+
+/**
+ * @fileoverview The exhaustive catalog of error codes the library raises. Keys
+ * and values are identical strings so `keyof typeof AI_TOKENS_ERROR_CODES` is the
+ * canonical code union that the message/status maps (server layer) are typed
+ * against — the compiler then enforces exhaustive coverage (see spec §16).
+ * @layer shared
+ */
+/** Every error code the library can raise, mapped to itself for value access. */
+declare const AI_TOKENS_ERROR_CODES: {
+    readonly AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED";
+    readonly AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG";
+    readonly AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER";
+    readonly AI_TOKENS_USAGE_MALFORMED: "AI_TOKENS_USAGE_MALFORMED";
+    readonly AI_TOKENS_PRICE_NOT_FOUND: "AI_TOKENS_PRICE_NOT_FOUND";
+    readonly AI_TOKENS_FX_REQUIRED: "AI_TOKENS_FX_REQUIRED";
+    readonly AI_TOKENS_BUDGET_EXCEEDED: "AI_TOKENS_BUDGET_EXCEEDED";
+    readonly AI_TOKENS_QUOTA_EXCEEDED: "AI_TOKENS_QUOTA_EXCEEDED";
+    readonly AI_TOKENS_INSUFFICIENT_CREDITS: "AI_TOKENS_INSUFFICIENT_CREDITS";
+    readonly AI_TOKENS_HOLD_NOT_FOUND: "AI_TOKENS_HOLD_NOT_FOUND";
+    readonly AI_TOKENS_HOLD_EXPIRED: "AI_TOKENS_HOLD_EXPIRED";
+    readonly AI_TOKENS_HOLD_ALREADY_SETTLED: "AI_TOKENS_HOLD_ALREADY_SETTLED";
+    readonly AI_TOKENS_IDEMPOTENCY_CONFLICT: "AI_TOKENS_IDEMPOTENCY_CONFLICT";
+    readonly AI_TOKENS_STREAM_USAGE_MISSING: "AI_TOKENS_STREAM_USAGE_MISSING";
+    readonly AI_TOKENS_STORE_ERROR: "AI_TOKENS_STORE_ERROR";
+};
+/** A library error code. */
+type AiTokensErrorCode = keyof typeof AI_TOKENS_ERROR_CODES;
+
+/**
+ * @fileoverview The canonical usage shape every provider normalizer produces.
+ * Downstream pricing, ledger, and budget logic is generic over this type, so it
+ * never sees a provider-specific payload.
+ * @layer shared
+ */
+
+/**
+ * Provider-agnostic, per-call token and cost usage. All token counts are plain
+ * `number` (well under 2^53 per record); money is `bigint` nano-USD.
+ */
+interface NormalizedUsage {
+    provider: ProviderId;
+    /** Model id as reported by the RESPONSE (may be a dated snapshot — see spec §6.6). */
+    model: string;
+    operation: AiOperation;
+    /** Tier reported by the response; absent → `'standard'`. */
+    serviceTier?: ServiceTier;
+    /** Uncached, non-reasoning input tokens (after the last cache breakpoint). */
+    inputTokens: number;
+    /**
+     * Output/completion tokens EXCLUDING reasoning tokens (§5.5 invariant).
+     * Anthropic folds thinking into output with no sub-field, so its adapter leaves
+     * `reasoningTokens` at 0 and keeps everything here.
+     */
+    outputTokens: number;
+    /** Tokens served from a cache hit (billed at a fraction of input). */
+    cacheReadTokens: number;
+    /** Tokens written to a 5-minute cache (Anthropic 1.25× input; Bedrock cacheWrite). */
+    cacheWrite5mTokens: number;
+    /** Tokens written to a 1-hour cache (Anthropic 2× input). */
+    cacheWrite1hTokens: number;
+    /** Reasoning/thinking tokens reported separately (OpenAI, Gemini). */
+    reasoningTokens: number;
+    /** Audio input tokens (multimodal). */
+    audioInTokens: number;
+    /** Audio output tokens (multimodal). */
+    audioOutTokens: number;
+    /** Image input tokens (multimodal). */
+    imageInTokens: number;
+    /** Image output tokens (multimodal). */
+    imageOutTokens: number;
+    /**
+     * Server-side tool usage counts — NON-token line items rated via
+     * `PriceVersion.unitRates` (§6.2), e.g. `{ web_search_requests: 2 }`. Anthropic
+     * reports these in `usage.server_tool_use`; for OpenAI/Gemini the host passes
+     * counts via `MeteringContext.extraUnits`.
+     */
+    serverToolUse?: Record<string, number>;
+    /** Provider-reported cost in nano-USD when available (OpenRouter `usage.cost`). */
+    providerReportedCostNanoUsd?: bigint;
+    /** Unclassified fields preserved verbatim for audit. */
+    raw?: Record<string, unknown>;
+}
+
+/**
+ * @fileoverview Canonical catalog types that the rest of the library is generic
+ * over: provider/operation/tier unions, the metering scope, the rating mode, and
+ * the pure normalizer/preset contracts. Framework-free.
+ * @layer shared
+ */
+
+/**
+ * A provider identifier. Widened with `(string & {})` so custom
+ * OpenAI-compatible providers can register their own id while known ids keep
+ * editor autocomplete.
+ */
+type ProviderId = KnownProviderId | (string & {});
+/**
+ * How a call is rated. `'rate-table'` computes cost from the price registry;
+ * `'provider-reported'` trusts `NormalizedUsage.providerReportedCostNanoUsd`.
+ */
+type RatingMode = 'rate-table' | 'provider-reported';
+/** The payer subject whose wallet/budget a call consumes. */
+interface MeteringScope {
+    /** `'key'` scopes spend their owner's wallet — they cannot own money. */
+    type: 'tenant' | 'team' | 'user' | 'key';
+    id: string;
+}
+/** The discriminant of {@link MeteringScope}. */
+type ScopeType = MeteringScope['type'];
+/**
+ * A pure function mapping one provider's raw `usage` object into the canonical
+ * {@link NormalizedUsage} shape. Consumes plain objects — never a provider SDK.
+ */
+type UsageNormalizer = (raw: unknown) => NormalizedUsage;
+/**
+ * Pairs a normalizer with the right provider id and rating mode. Passed in
+ * `MeteringContext.preset` and consumed by `meter()`, the interceptor, and
+ * `record()`.
+ */
+interface ProviderPreset {
+    provider: ProviderId;
+    normalizer: UsageNormalizer;
+    ratingMode: RatingMode;
+}
+
+/**
+ * @fileoverview The immutable ledger row for one AI call (or its hold), its
+ * lifecycle status, the ledger query filter, and the append insert type.
+ * @layer shared
+ */
+
+/** Lifecycle status of a usage record (see spec §8.3). */
+type UsageStatus = 'pending' | 'posted' | 'reversed' | 'released';
+/**
+ * One append-only ledger entry for a single AI call (or its hold). All money is
+ * integer nano-USD; token counts are plain `number`.
+ */
+interface UsageRecord {
+    id: string;
+    tenantId: string;
+    /** The PAYER — the subject whose wallet/budget is consumed. */
+    scope: MeteringScope;
+    /** Optional distinct beneficiary (reporting dimension only). */
+    beneficiary?: MeteringScope;
+    /** Optional actor who triggered the call (audit). */
+    requestedBy?: string;
+    provider: ProviderId;
+    /** Model reported by the response (pricing follows this). */
+    model: string;
+    /** Model the host requested, when supplied (drift audit; §6.6). */
+    requestedModel?: string;
+    operation: AiOperation;
+    serviceTier: ServiceTier;
+    /** Caller-supplied logical operation, e.g. `'workout.generate'`. */
+    feature: string;
+    /** Free-form cost-attribution labels (≤ 10), e.g. `['team:research']`. */
+    tags: string[];
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    reasoningTokens: number;
+    audioInTokens: number;
+    audioOutTokens: number;
+    imageInTokens: number;
+    imageOutTokens: number;
+    totalTokens: number;
+    /** Non-token line items actually rated, e.g. `{ web_search_requests: 2 }`. */
+    extraUnits?: Record<string, number>;
+    /** `null` for provider-reported mode or a priceMissing record. */
+    priceVersionId: string | null;
+    /** Provider cost (tokens + surcharges). */
+    rawCostNanoUsd: bigint;
+    /** The non-token share of `rawCostNanoUsd`. */
+    surchargeNanoUsd: bigint;
+    /** After markup — what the customer pays. */
+    billedCostNanoUsd: bigint;
+    /** The resolved 4-dp markup value actually applied. */
+    markupMultiplier: number;
+    /** `'USD'` in v0.1 (§7.4). */
+    currency: string;
+    /** Rated at 0 in non-strict mode; a backfill target. */
+    priceMissing: boolean;
+    status: UsageStatus;
+    /** Set on a posted record when a compensating record reversed it (§8.5). */
+    reversedByRecordId?: string;
+    /** Set on a compensating record, pointing back at the record it negates. */
+    reversesRecordId?: string;
+    /** Unique per `(tenantId, idempotencyKey)`. */
+    idempotencyKey: string;
+    /** Ties an invoice line back to app logs. */
+    correlationId?: string;
+    /** Provider request id. */
+    requestId?: string;
+    /** Platform-absorbed — never consumes wallet/budget. */
+    isSystemCost: boolean;
+    /** e.g. `'workout_generation_retry'`. */
+    systemCostCategory?: string;
+    /** True when this record consumed wallet/budget (reconciliation predicate §10.7). */
+    enforced: boolean;
+    /** Previous chain hash (optional per-tenant hash chain, §8.6). */
+    prevHash?: string;
+    /** This record's chain hash (optional per-tenant hash chain, §8.6). */
+    hash?: string;
+    /** When the LLM call happened. */
+    occurredAt: Date;
+    createdAt: Date;
+    /** Pending-row settlements only. */
+    updatedAt: Date;
+}
+/**
+ * Caller-supplied fields for `ILedgerStore.append`. The store computes
+ * `id`/`hash`/`prevHash`/`createdAt`/`updatedAt`.
+ */
+type NewUsageRecord = Omit<UsageRecord, 'id' | 'prevHash' | 'hash' | 'createdAt' | 'updatedAt'>;
+/** Query filter for the ledger store. */
+interface LedgerFilter {
+    tenantId: string;
+    scope?: MeteringScope;
+    beneficiary?: MeteringScope;
+    feature?: string;
+    features?: string[];
+    provider?: ProviderId;
+    model?: string;
+    operation?: AiOperation;
+    serviceTier?: ServiceTier;
+    tags?: string[];
+    isSystemCost?: boolean;
+    systemCostCategory?: string;
+    status?: UsageStatus[];
+    enforcedOnly?: boolean;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * @fileoverview Append-only ledger field whitelists and the transition guard — the
+ * single source of truth shared by the ledger service and the store adapters so the
+ * two layers can never drift. `AMOUNT_FIELDS` are the money/token amounts that stay
+ * immutable after a record posts; `SETTLEMENT_FIELDS` are everything a settlement
+ * (`pending → posted`) may replace with actuals; `RELEASE_FIELDS` are the audit
+ * annotations a void (`pending → released`) may set; `REVERSAL_LINKAGE_FIELD` is the
+ * sole annotation a `posted → reversed` flip may set. `isLegalLedgerTransition` and
+ * `isLegalTransitionPatchKey` encode the state machine and its per-transition patch
+ * contract so every layer accepts exactly the same patches (see spec §8.3/§8.5).
+ * @layer shared
+ */
+
+/**
+ * The money/token amount columns that are append-only once a record posts — a
+ * void (`pending → released`) or a reversal annotation may never patch them.
+ */
+declare const AMOUNT_FIELDS: readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWrite5mTokens", "cacheWrite1hTokens", "reasoningTokens", "audioInTokens", "audioOutTokens", "imageInTokens", "imageOutTokens", "totalTokens", "rawCostNanoUsd", "surchargeNanoUsd", "billedCostNanoUsd"];
+/**
+ * Every field a settlement (`pending → posted`) may replace with actuals: the
+ * append-only amounts plus the pricing metadata resolved at settlement time.
+ */
+declare const SETTLEMENT_FIELDS: readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWrite5mTokens", "cacheWrite1hTokens", "reasoningTokens", "audioInTokens", "audioOutTokens", "imageInTokens", "imageOutTokens", "totalTokens", "rawCostNanoUsd", "surchargeNanoUsd", "billedCostNanoUsd", "priceVersionId", "priceMissing", "markupMultiplier"];
+/**
+ * The audit-annotation columns a void (`pending → released`) may patch. A release
+ * never bills, so it may only annotate the voided hold with request/correlation
+ * linkage — never an append-only amount, the settlement pricing metadata, or an
+ * immutable identity column. Kept as an explicit column whitelist so the store
+ * boundary never interpolates an unknown identifier into raw SQL.
+ */
+declare const RELEASE_FIELDS: readonly ["correlationId", "requestId"];
+/** The sole field a `posted → reversed` annotation may set — the reversal linkage. */
+declare const REVERSAL_LINKAGE_FIELD: "reversedByRecordId";
+/**
+ * The only patch keys a settlement (`pending → posted`) may set — the settlement
+ * amount/cost/pricing columns plus the reversal-linkage field. An immutable
+ * identity column (`id`/`tenantId`/`idempotencyKey`) is never a member.
+ */
+declare const SETTLEMENT_PATCH_KEYS: ReadonlySet<string>;
+/**
+ * Whether `from → to` is a legal ledger state transition (§8.3): a hold settles
+ * (`pending → posted`) or is voided (`pending → released`), and a posted record may
+ * be annotated as reversed (`posted → reversed`). Every other pair is a caller bug.
+ *
+ * @param from The record's current lifecycle status.
+ * @param to The requested target status.
+ * @returns `true` when the transition is permitted by the state machine.
+ */
+declare function isLegalLedgerTransition(from: UsageStatus, to: UsageStatus): boolean;
+/**
+ * Whether `key` is a legal patch field for the `from → to` transition (§8.3/§8.5) —
+ * the single source of truth shared by the ledger service guard and every store
+ * adapter so the two layers can never drift:
+ * - `pending → posted` (settle): only the settlement fields (+ the reversal linkage).
+ * - `pending → released` (void): only the audit-annotation fields.
+ * - `posted → reversed` (annotate): only the reversal linkage.
+ * Any other (illegal) transition patches nothing. The result set is always drawn
+ * from the fixed column whitelists above, so a store may interpolate a passing key
+ * as a raw SQL identifier without risk of injection.
+ *
+ * @param from The record's current lifecycle status.
+ * @param to The requested target status.
+ * @param key The patch column a caller wishes to set.
+ * @returns `true` when the column may legally be patched on this transition.
+ */
+declare function isLegalTransitionPatchKey(from: UsageStatus, to: UsageStatus, key: string): boolean;
+
+/**
+ * @fileoverview Normalizer for the OpenAI Chat Completions `usage` shape. The
+ * critical rule (spec §5.3/§5.5): `completion_tokens` INCLUDES reasoning tokens,
+ * so `outputTokens = completion_tokens − reasoning_tokens` — double-billing that
+ * detail is the audit's #1 billing bug. Cached and audio prompt tokens are a
+ * subset of `prompt_tokens` and are split into their own categories.
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenAI Chat Completions response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenAiChatUsage({ model: 'gpt-5.2', usage: { prompt_tokens: 100, completion_tokens: 40 } })
+ */
+declare function normalizeOpenAiChatUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the OpenAI Responses API `usage` shape. Same
+ * reasoning-subtraction rule as Chat Completions, but the fields are renamed
+ * `input_tokens` / `output_tokens` with `input_tokens_details` /
+ * `output_tokens_details` (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenAI Responses API response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenAiResponsesUsage({ model: 'gpt-5.2', usage: { input_tokens: 100, output_tokens: 40 } })
+ */
+declare function normalizeOpenAiResponsesUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for OpenAI-compatible gateways (DeepSeek, xAI, Groq, …)
+ * that reuse the Chat Completions `prompt_tokens` / `completion_tokens` shape
+ * without OpenAI-specific detail guarantees. DeepSeek's `prompt_cache_hit_tokens`
+ * maps to `cacheReadTokens` when present. The provider id is left empty for the
+ * preset (`providerPresets.openaiCompatible(id)`) or context to supply (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenAI-compatible chat response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage; `provider` is `''` unless the preset overrides it.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenAiCompatibleUsage({ model: 'deepseek-chat', usage: { prompt_tokens: 100, completion_tokens: 40 } })
+ */
+declare function normalizeOpenAiCompatibleUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Anthropic Messages `usage` shape. Anthropic
+ * folds thinking into `output_tokens` with no sub-field, so `reasoningTokens`
+ * stays `0` (spec §5.3/§5.5). Cache writes split into 5-minute and 1-hour
+ * categories via `cache_creation`; an unsplit `cache_creation_input_tokens`
+ * total defaults to the 5-minute category. Server tool use maps to `serverToolUse`.
+ * @layer shared
+ */
+
+/**
+ * Normalize an Anthropic Messages response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeAnthropicUsage({ model: 'claude-opus', usage: { input_tokens: 100, output_tokens: 40 } })
+ */
+declare function normalizeAnthropicUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Google Gemini / Vertex `usageMetadata` shape.
+ * `candidatesTokenCount` EXCLUDES thoughts, so it maps directly to `outputTokens`
+ * with no subtraction; `thoughtsTokenCount` maps to `reasoningTokens`;
+ * `toolUsePromptTokenCount` folds into `inputTokens` (billed at the input rate);
+ * `cachedContentTokenCount` is the cache-read portion of the prompt (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Gemini / Vertex response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usageMetadata`).
+ * @returns The canonical usage.
+ * @throws {Error} When `usageMetadata` or its required token field is absent.
+ * @example
+ * normalizeGeminiUsage({ modelVersion: 'gemini-2.5-flash', usageMetadata: { promptTokenCount: 100, candidatesTokenCount: 40 } })
+ */
+declare function normalizeGeminiUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the AWS Bedrock Converse `usage` shape. Cache
+ * writes come either as a single `cacheWriteInputTokens` total (defaulting to the
+ * 5-minute category) or split across `cacheDetails[]` TTL entries (spec §5.3).
+ * Model ids like `us.anthropic.claude-…-v1:0` are region-prefixed and are
+ * resolved downstream (spec §6.6).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Bedrock Converse response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeBedrockConverseUsage({ model: 'us.anthropic.claude', usage: { inputTokens: 100, outputTokens: 40 } })
+ */
+declare function normalizeBedrockConverseUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Mistral `usage` shape. v0.1 maps
+ * `prompt_tokens` / `completion_tokens` only; any additional audio/cache detail
+ * fields are version-dependent and preserved verbatim in `raw` (spec §5.3/§20.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Mistral response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeMistralUsage({ model: 'mistral-large', usage: { prompt_tokens: 100, completion_tokens: 40 } })
+ */
+declare function normalizeMistralUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the OpenRouter `usage` shape. `usage.cost` is the
+ * real charged amount in USD (1 credit = 1 USD) and converts to
+ * `providerReportedCostNanoUsd`, enabling `'provider-reported'` rating with no
+ * price row. `completion_tokens` includes reasoning, so it is subtracted like
+ * OpenAI (spec §5.3/§5.5/§6.5). `cost_details` is preserved in `raw`.
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenRouter response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage, including `providerReportedCostNanoUsd` when `usage.cost` is present.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenRouterUsage({ model: 'gpt-5.2', usage: { prompt_tokens: 100, completion_tokens: 40, cost: 0.0123 } })
+ */
+declare function normalizeOpenRouterUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Vercel AI SDK `usage` shape. It reads BOTH the
+ * v5 shape (`usage.{inputTokens, outputTokens, cachedInputTokens, reasoningTokens}`)
+ * and the v6 shape (`inputTokenDetails.{cacheReadTokens, cacheWriteTokens}`,
+ * `outputTokenDetails.reasoningTokens`). `outputTokens` includes reasoning tokens,
+ * so they are subtracted. The provider id and model are supplied by the caller's
+ * preset/context and default to empty here (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Vercel AI SDK response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage; `provider` is `''` unless the context overrides it.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeVercelAiSdkUsage({ usage: { inputTokens: 100, outputTokens: 40 } })
+ */
+declare function normalizeVercelAiSdkUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Exact nano-USD money helpers. Every persisted monetary value is
+ * an integer number of nano-USD (`1e-9` USD) held as a `bigint`, so all
+ * arithmetic is exact integer math. Floating point appears only at the two
+ * documented boundaries: the OpenRouter `usage.cost` entry conversion
+ * ({@link floatUsdToNanoUsd}) and presentation ({@link formatNanoUsd}).
+ * @layer shared
+ */
+/**
+ * The building block for token pricing: cost of `tokens` at a rate expressed as
+ * nano-USD per 1,000,000 tokens, as exact integer math (spec §7.1).
+ *
+ * @param tokens Integer token count.
+ * @param ratePerMillionNano Rate in nano-USD per 1,000,000 tokens.
+ * @returns Cost in nano-USD, truncated toward zero on the division.
+ * @example
+ * perMillion(1000, 5_000_000_000n) // 5_000_000n  ($0.005 for 1k tokens at $5/M)
+ */
+declare function perMillion(tokens: number, ratePerMillionNano: bigint): bigint;
+/**
+ * Convert a floating-point USD amount (e.g. OpenRouter `usage.cost`) into
+ * nano-USD, rounding half away from zero at nano precision. The dollar and
+ * fractional parts are handled separately so no product overflows the 2^53
+ * exact-integer range: the result is exact for `|usd| < $1,000` (and for any
+ * value whose fractional dollars round cleanly). This is the only float→bigint
+ * entry point on a money path.
+ *
+ * @param usd The amount in USD.
+ * @returns The amount in nano-USD.
+ * @throws {RangeError} When `usd` is not finite.
+ * @example
+ * floatUsdToNanoUsd(0.005) // 5_000_000n
+ */
+declare function floatUsdToNanoUsd(usd: number): bigint;
+/** Options controlling how {@link formatNanoUsd} renders a value. */
+interface FormatNanoUsdOptions {
+    /** ISO currency code; `'USD'` renders a `$` prefix, others append the code. Default `'USD'`. */
+    currency?: string;
+    /** Presentation FX rate as target-currency nano-units per 1 USD; converts at read time. */
+    fxRateNano?: bigint;
+    /** Fractional digits to render, in the range `[0, 9]`. Default `6`. */
+    decimals?: number;
+}
+/**
+ * Render a nano-USD value as a human-readable currency string. Presentation
+ * only — rounding to the displayed precision is round-half-up computed in
+ * `bigint`, never floating point (spec §7.4).
+ *
+ * @param nanoUsd The value in nano-USD.
+ * @param opts Currency, FX, and precision options.
+ * @returns The formatted string, e.g. `"$0.005000"`.
+ * @throws {RangeError} When `opts.decimals` is not an integer in `[0, 9]`.
+ * @example
+ * formatNanoUsd(5_000_000n)                               // '$0.005000'
+ * formatNanoUsd(5_000_000n, { currency: 'BRL', fxRateNano: 5_000_000_000n }) // '0.025000 BRL'
+ */
+declare function formatNanoUsd(nanoUsd: bigint, opts?: FormatNanoUsdOptions): string;
+
+/**
+ * @fileoverview The effective-dated price row and its insert type. Rates are
+ * integer nano-USD per 1,000,000 tokens (or per unit for non-token line items),
+ * so every cost computation is exact integer math.
+ * @layer shared
+ */
+
+/**
+ * One immutable, effective-dated price version for a (provider, model, operation,
+ * serviceTier) tuple. A call is rated at the row in effect at its timestamp.
+ */
+interface PriceVersion {
+    id: string;
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    /** Part of the resolution key; `'standard'` is the default. */
+    serviceTier: ServiceTier;
+    /** Rates as integer nano-USD per 1,000,000 tokens. */
+    inputNanoUsdPerMillion: bigint;
+    outputNanoUsdPerMillion: bigint;
+    cacheReadNanoUsdPerMillion: bigint;
+    cacheWrite5mNanoUsdPerMillion: bigint;
+    cacheWrite1hNanoUsdPerMillion: bigint;
+    /** Usually equals output; kept separate for models that price reasoning differently. */
+    reasoningNanoUsdPerMillion: bigint;
+    audioInNanoUsdPerMillion: bigint;
+    audioOutNanoUsdPerMillion: bigint;
+    imageInNanoUsdPerMillion: bigint;
+    imageOutNanoUsdPerMillion: bigint;
+    /**
+     * Long-context tier threshold: when total input (all input-side categories)
+     * exceeds this, the tier rates replace the base input/output rates for the
+     * WHOLE call (all-or-nothing, matching Gemini's billing).
+     */
+    tierThresholdTokens?: number;
+    tierInputNanoUsdPerMillion?: bigint;
+    tierOutputNanoUsdPerMillion?: bigint;
+    /**
+     * Non-token line items in nano-USD PER UNIT, matched against
+     * `NormalizedUsage.serverToolUse` / `MeteringContext.extraUnits` by EXACT key —
+     * so the key must equal the count key the normalizer emits (e.g. Anthropic's
+     * `usage.server_tool_use.web_search_requests`) — e.g.
+     * `{ web_search_requests: 10_000_000n }` ($0.01 per web-search call).
+     */
+    unitRates?: Record<string, bigint>;
+    currency: 'USD';
+    effectiveFrom: Date;
+    /** `null` = current; set when a newer row supersedes it. */
+    effectiveTo: Date | null;
+    /** Provenance: `'snapshot' | 'manual' | 'import'`. */
+    source: string;
+}
+/**
+ * Caller-supplied fields for `upsertPrice`. Rates default to `0n` and
+ * `serviceTier` to `'standard'`; the store assigns `id` and closes the previous
+ * open row's `effectiveTo`.
+ */
+type NewPriceVersion = Partial<Omit<PriceVersion, 'id' | 'effectiveTo'>> & Pick<PriceVersion, 'provider' | 'model' | 'operation'>;
+
+/**
+ * @fileoverview The pure cost engine (spec §7.1). Computes the provider cost of a
+ * {@link NormalizedUsage} against a {@link PriceVersion} in exact bigint nano-USD.
+ * The long-context tier is all-or-nothing: when total input crosses the
+ * threshold, the tier rates replace the base input/output rates for the WHOLE
+ * call. Non-token line items are rated via `unitRates`. The token and surcharge
+ * parts are returned separately so reports can distinguish them.
+ * @layer shared
+ */
+
+/** The separable parts of a computed provider cost, all in nano-USD. */
+interface CostBreakdown {
+    /** Token cost plus surcharges. */
+    totalNanoUsd: bigint;
+    /** The token-only share. */
+    tokenNanoUsd: bigint;
+    /** The non-token (server tool use) share. */
+    surchargeNanoUsd: bigint;
+}
+/**
+ * Compute the provider cost of a normalized usage against a price version.
+ *
+ * @param usage The normalized usage.
+ * @param rate The effective-dated price version.
+ * @returns The exact cost broken into token and surcharge parts.
+ * @example
+ * // 1,000 Opus input tokens at $5/M → 5_000_000n nano-USD ($0.005).
+ * computeCostNanoUsd(usage, rate).totalNanoUsd
+ */
+declare function computeCostNanoUsd(usage: NormalizedUsage, rate: PriceVersion): CostBreakdown;
+
+/**
+ * @fileoverview Markup / margin math (spec §7.2). The multiplier is validated
+ * (finite, > 0) and rounded to 4 decimal places to match the persisted
+ * `Decimal(10,4)`; the billed amount is exact bigint with truncation toward zero
+ * on the final division. Markup applies in BOTH rating modes.
+ * @layer shared
+ */
+/**
+ * Validate and round a markup multiplier to 4 decimal places — the value that is
+ * persisted on each usage record.
+ *
+ * @param multiplier The raw multiplier.
+ * @returns The multiplier rounded to 4 decimal places.
+ * @throws {RangeError} When the multiplier is not finite or not > 0.
+ * @example
+ * resolveMultiplier4dp(1.23456) // 1.2346
+ */
+declare function resolveMultiplier4dp(multiplier: number): number;
+/**
+ * Apply a markup multiplier to a raw provider cost, in exact bigint nano-USD.
+ *
+ * @param rawCostNanoUsd The provider cost in nano-USD.
+ * @param multiplier The markup multiplier (e.g. `4.0` for 4× resale).
+ * @returns The billed cost in nano-USD (division truncates toward zero).
+ * @throws {RangeError} When the multiplier is not finite or not > 0.
+ * @example
+ * applyMarkup(5_000_000n, 4.0) // 20_000_000n
+ */
+declare function applyMarkup(rawCostNanoUsd: bigint, multiplier: number): bigint;
+
+/**
+ * @fileoverview Host-side derivation of a stable idempotency key from request
+ * content (spec §8.4). The payload is serialized to canonical JSON — object keys
+ * sorted recursively, array order preserved, `undefined` dropped, `bigint`
+ * encoded as a QUOTED, type-tagged string (e.g. `42n` → `"42n"`), `Date` as its
+ * ISO string — then hashed with a pure synchronous SHA-256. The `n`-suffixed
+ * quoted form makes a `bigint` unambiguous: it can never serialize to the same
+ * text as the number `42` (`42`) or a numeric string `"42"` (`"42"`), so
+ * `deriveIdempotencyKey(42)` and `deriveIdempotencyKey(42n)` never collide.
+ * Deriving the key from content means a retry after a 429/network failure reuses
+ * the same key and is deduplicated.
+ * @layer shared
+ */
+/**
+ * Derive a stable idempotency key from a request payload. Equal payloads (up to
+ * object-key order) yield the same key; distinct payloads yield distinct keys.
+ * Pure, synchronous, and edge-safe.
+ *
+ * @param payload Any JSON-like request content.
+ * @returns A 64-character lowercase hex SHA-256 digest.
+ * @example
+ * deriveIdempotencyKey({ a: 1, b: 2 }) === deriveIdempotencyKey({ b: 2, a: 1 }) // true
+ */
+declare function deriveIdempotencyKey(payload: unknown): string;
+
+/**
+ * @fileoverview Wallet types: the owner reference, the materialized wallet, and
+ * the append-only entry ledger whose signed sum is the balance (see spec §9.1).
+ * @layer shared
+ */
+
+/**
+ * Identifies the owner of a wallet. `'key'` scopes deliberately cannot own money
+ * — API keys spend their owner's wallet.
+ */
+interface WalletRef {
+    tenantId: string;
+    ownerType: 'tenant' | 'team' | 'user';
+    ownerId: string;
+}
+/** A prepaid credit wallet with a materialized nano-USD balance. */
+interface Wallet {
+    id: string;
+    tenantId: string;
+    ownerType: WalletRef['ownerType'];
+    ownerId: string;
+    /** Materialized, kept transactionally consistent with Σ entries. */
+    balanceNanoUsd: bigint;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** One append-only entry in a wallet's ledger. */
+interface WalletEntry {
+    id: string;
+    walletId: string;
+    type: WalletEntryType;
+    /** `+` = credit, `−` = debit. */
+    amountNanoUsd: bigint;
+    /** Grant burn priority (lower first). */
+    priority: number;
+    effectiveAt: Date;
+    /** Grants only. */
+    expiresAt?: Date;
+    /** Present on usage-driven debits/refunds. */
+    usageRecordId?: string;
+    /** Unique per wallet. */
+    idempotencyKey: string;
+    reason?: string;
+    createdAt: Date;
+}
+/** Caller-supplied fields for `IWalletStore.appendEntry`. The store assigns `id`/`createdAt`. */
+type NewWalletEntry = Omit<WalletEntry, 'id' | 'createdAt'>;
+
+/**
+ * @fileoverview Budget types: the budget definition, its window/policy unions,
+ * and the read-side status DTOs a usage meter renders (see spec §10).
+ * @layer shared
+ */
+
+/** How a budget's window repeats. `{ customSeconds }` is a fixed-length rolling window. */
+type BudgetWindowKind = 'day' | 'week' | 'month' | 'total' | {
+    customSeconds: number;
+};
+/** What happens when a budget is exceeded. */
+type BudgetPolicy = 'block' | 'throttle' | 'allow';
+/** A spend/token/count cap for a scope over a window. */
+interface Budget {
+    id: string;
+    tenantId: string;
+    scope: MeteringScope;
+    /** Restrict which usage counts; empty/absent = all features. */
+    features?: string[];
+    /** Billed-spend cap. */
+    limitNanoUsd?: bigint;
+    /** Total-token cap. */
+    limitTokens?: number;
+    /** Operation-count cap (posted, enforced, non-reversed records). */
+    limitCount?: number;
+    window: BudgetWindowKind;
+    /**
+     * Per-budget window anchor. Absent → calendar UTC anchoring. Month windows
+     * clamp short months (a Jan 31 anchor yields Feb 28/29, Mar 31, …).
+     */
+    anchorAt?: Date;
+    /** Optional budget lifetime: enforcement ignores the budget after this instant. */
+    expiresAt?: Date;
+    /** Fractions of the limit that trigger soft alert events. */
+    softThresholds: number[];
+    policy: BudgetPolicy;
+    createdAt: Date;
+}
+/** The read-side status of one budget window — powers a usage meter. */
+interface BudgetStatus {
+    budgetId: string;
+    features?: string[];
+    window: BudgetWindowKind;
+    windowStart: Date;
+    /** `null` for `'total'`. */
+    resetsAt: Date | null;
+    policy: BudgetPolicy;
+    limit: {
+        nanoUsd?: bigint;
+        tokens?: number;
+        count?: number;
+    };
+    spent: {
+        nanoUsd: bigint;
+        tokens: number;
+        count: number;
+    };
+    /** Absent dimension = unlimited. */
+    remaining: {
+        nanoUsd?: bigint;
+        tokens?: number;
+        count?: number;
+    };
+    /** Max across limited dimensions. */
+    usedFraction: number;
+}
+/** Aggregate access status for a scope (wallet + all matching budgets). */
+interface AccessStatus {
+    hasAccess: boolean;
+    blockedBy?: 'wallet' | 'budget';
+    wallet?: {
+        balanceNanoUsd: bigint;
+        credits: number;
+        overdraftRemainingNanoUsd: bigint;
+    };
+    budgets: BudgetStatus[];
+}
+
+/**
+ * @fileoverview Reporting types: the query filter and the aggregated usage
+ * summary (including the cache-savings figure) produced by `UsageReportService`.
+ * @layer shared
+ */
+
+/** Filter for a usage report query. */
+interface ReportFilter {
+    tenantId: string;
+    scope?: MeteringScope;
+    beneficiary?: MeteringScope;
+    feature?: string;
+    features?: string[];
+    provider?: ProviderId;
+    model?: string;
+    operation?: AiOperation;
+    serviceTier?: ServiceTier;
+    /** Records carrying ANY of these tags. */
+    tags?: string[];
+    isSystemCost?: boolean;
+    systemCostCategory?: string;
+    enforcedOnly?: boolean;
+    /** Default `['posted', 'reversed']`. */
+    status?: UsageStatus[];
+    from: Date;
+    to: Date;
+}
+/** One aggregated row of a usage report. */
+interface UsageSummary {
+    /** groupBy key → value; empty groupBy = one grand-total row. */
+    group: Record<string, string>;
+    records: number;
+    totalTokens: number;
+    tokens: Record<TokenCategory, number>;
+    rawCostNanoUsd: bigint;
+    surchargeNanoUsd: bigint;
+    billedCostNanoUsd: bigint;
+    /** Σ cacheReadTokens × (inputRate − cacheReadRate) — the "you saved $X via caching" figure. */
+    cacheSavingsNanoUsd: bigint;
+}
+
+/**
+ * @fileoverview The event envelope, the event-type union, and one payload type
+ * per event in the catalog (see spec §12). Delivery is at-least-once, so `id` is
+ * the consumer's dedupe key. `bigint` payload fields cross a JSON boundary as
+ * decimal strings (§15.5) — in-process delivery keeps them as `bigint`.
+ * @layer shared
+ */
+
+/** Every event `type` the library emits. */
+type AiTokensEventType = 'ai_tokens.usage.recorded' | 'ai_tokens.usage.reversed' | 'ai_tokens.hold.released' | 'ai_tokens.budget.threshold_crossed' | 'ai_tokens.budget.exceeded' | 'ai_tokens.budget.projected_exceeded' | 'ai_tokens.wallet.low_balance' | 'ai_tokens.wallet.depleted' | 'ai_tokens.wallet.granted' | 'ai_tokens.price.missing' | 'ai_tokens.audit';
+/** The at-least-once event envelope. */
+interface AiTokensEvent<T = unknown> {
+    /** UUID — the consumer's dedupe key. */
+    id: string;
+    type: AiTokensEventType;
+    occurredAt: Date;
+    tenantId: string;
+    scope?: MeteringScope;
+    data: T;
+}
+/** A per-window spend snapshot shared by budget event payloads. */
+interface BudgetDimensionSnapshot {
+    nanoUsd?: bigint;
+    tokens?: number;
+    count?: number;
+}
+/** `ai_tokens.usage.recorded` payload. */
+interface UsageRecordedEventData {
+    usageRecordId: string;
+    feature: string;
+    provider: ProviderId;
+    model: string;
+    serviceTier: ServiceTier;
+    totalTokens: number;
+    rawCostNanoUsd: bigint;
+    billedCostNanoUsd: bigint;
+    enforced: boolean;
+    isSystemCost: boolean;
+}
+/** `ai_tokens.usage.reversed` payload. */
+interface UsageReversedEventData {
+    usageRecordId: string;
+    reversalRecordId: string;
+    reason: string;
+}
+/** `ai_tokens.hold.released` payload. */
+interface HoldReleasedEventData {
+    holdId: string;
+    reason: string;
+    expired: boolean;
+}
+/** `ai_tokens.budget.threshold_crossed` payload. */
+interface BudgetThresholdCrossedEventData {
+    budgetId: string;
+    threshold: number;
+    usedFraction: number;
+    limit: BudgetDimensionSnapshot;
+    spent: BudgetDimensionSnapshot;
+    remaining: BudgetDimensionSnapshot;
+    resetsAt: Date | null;
+}
+/** `ai_tokens.budget.exceeded` payload. */
+interface BudgetExceededEventData {
+    budgetId: string;
+    policy: BudgetPolicy;
+    dimension: 'cost' | 'tokens' | 'count';
+    limit: BudgetDimensionSnapshot;
+    spent: BudgetDimensionSnapshot;
+    resetsAt: Date | null;
+}
+/** `ai_tokens.budget.projected_exceeded` payload. */
+interface BudgetProjectedExceededEventData {
+    budgetId: string;
+    projectedAt: Date;
+    usedFraction: number;
+    resetsAt: Date | null;
+}
+/** `ai_tokens.wallet.low_balance` payload. */
+interface WalletLowBalanceEventData {
+    walletId: string;
+    balanceNanoUsd: bigint;
+    thresholdFraction: number;
+}
+/** `ai_tokens.wallet.depleted` payload. */
+interface WalletDepletedEventData {
+    walletId: string;
+    balanceNanoUsd: bigint;
+}
+/** `ai_tokens.wallet.granted` payload. */
+interface WalletGrantedEventData {
+    walletId: string;
+    entryId: string;
+    amountNanoUsd: bigint;
+    expiresAt?: Date;
+}
+/** `ai_tokens.price.missing` payload. */
+interface PriceMissingEventData {
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    serviceTier: ServiceTier;
+    usageRecordId: string;
+}
+/** `ai_tokens.audit` payload — an admin-plane mutation (§14.4). */
+interface AuditEventData {
+    action: string;
+    actor?: string;
+    details: Record<string, unknown>;
+}
+
+/**
+ * @fileoverview The canonical error response body. `AiTokensException` (server
+ * layer) serializes to this shape so hosts get a stable `{ error: {...} }`
+ * envelope (see spec §16).
+ * @layer shared
+ */
+
+/** The JSON body every {@link AI_TOKENS_ERROR_CODES} failure serializes to. */
+interface AiTokensErrorResponse {
+    error: {
+        code: keyof typeof AI_TOKENS_ERROR_CODES;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+
+export { AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, type AccessStatus, type AiOperation, type AiTokensErrorCode, type AiTokensErrorResponse, type AiTokensEvent, type AiTokensEventType, type AuditEventData, type Budget, type BudgetDimensionSnapshot, type BudgetExceededEventData, type BudgetPolicy, type BudgetProjectedExceededEventData, type BudgetStatus, type BudgetThresholdCrossedEventData, type BudgetWindowKind, type CostBreakdown, type FormatNanoUsdOptions, type HoldReleasedEventData, type KnownProviderId, type LedgerFilter, type MeteringScope, type NewPriceVersion, type NewUsageRecord, type NewWalletEntry, type NormalizedUsage, PROVIDER_IDS, type PriceMissingEventData, type PriceVersion, type ProviderId, type ProviderPreset, RELEASE_FIELDS, REVERSAL_LINKAGE_FIELD, type RatingMode, type ReportFilter, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, type ScopeType, type ServiceTier, TOKEN_CATEGORIES, type TokenCategory, type UsageNormalizer, type UsageRecord, type UsageRecordedEventData, type UsageReversedEventData, type UsageStatus, type UsageSummary, WALLET_ENTRY_TYPES, type Wallet, type WalletDepletedEventData, type WalletEntry, type WalletEntryType, type WalletGrantedEventData, type WalletLowBalanceEventData, type WalletRef, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, resolveMultiplier4dp };