@omnicross/contracts 0.1.6 → 0.1.7

package/dist/account-tokens-types.d.cts

@@ -291,7 +291,7 @@ type SubscriptionAccountSanitized = {
      * currently excluded from the pool (multi-account) or would surface the
      * upstream's error (single-account). Secret-free.
      */
-    health?: 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'blocked';
+    health?: 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'quota_exhausted' | 'blocked';
     /**
      * ISO instant the current health cooldown elapses (absent for healthy /
      * permanently-blocked). Lets the admin view render "rate-limited until .

package/dist/account-tokens-types.d.ts

@@ -291,7 +291,7 @@ type SubscriptionAccountSanitized = {
      * currently excluded from the pool (multi-account) or would surface the
      * upstream's error (single-account). Secret-free.
      */
-    health?: 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'blocked';
+    health?: 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'quota_exhausted' | 'blocked';
     /**
      * ISO instant the current health cooldown elapses (absent for healthy /
      * permanently-blocked). Lets the admin view render "rate-limited until .

package/dist/audit-types.cjs

@@ -26,7 +26,7 @@ module.exports = __toCommonJS(audit_types_exports);
 var DEFAULT_AUDIT_CONFIG = {
   enabled: false,
   captureBodies: false,
-  maxBodyBytes: 8192,
+  maxBodyBytes: -1,
   retentionDays: 7,
   trustForwardedFor: false
 };

package/dist/audit-types.d.cts

@@ -19,8 +19,9 @@
 /**
  * One per-request audit entry (design D1). The metadata fields are recorded
  * whenever audit is `enabled`; the two body snapshots are present ONLY when
- * `captureBodies` is ALSO on, and always after truncation + redaction. NO field
- * ever holds key material, an upstream token, or an Authorization/api-key header.
+ * `captureBodies` is ALSO on, and always after optional truncation + redaction.
+ * NO field ever holds key material, an upstream token, or an
+ * Authorization/api-key header.
  */
 interface AuditRecord {
     /** Unique record id (a generated request id — NOT any secret). */
@@ -54,14 +55,13 @@ interface AuditRecord {
     /** Sanitized error message (present only on a failed relay). */
     error?: string;
     /**
-     * Request body snapshot — present ONLY when `captureBodies`, truncated to the
-     * configured cap, and ALWAYS run through the secret-redaction pass first.
+     * Request body snapshot — present ONLY when `captureBodies`, optionally
+     * truncated to the configured cap, and ALWAYS run through secret redaction.
      */
     requestBody?: string;
     /**
-     * Response body snapshot — present ONLY when `captureBodies` AND the response
-     * was NON-streaming (a streaming response records metadata only), truncated +
-     * redacted like `requestBody`.
+     * Response body snapshot — present ONLY when `captureBodies`; streaming
+     * responses are included. Optionally truncated + redacted like `requestBody`.
      */
     responseBody?: string;
 }
@@ -74,9 +74,9 @@ interface AuditRecord {
 interface AuditConfig {
     /** Master switch; default FALSE (zero regression). */
     enabled: boolean;
-    /** Capture request/response bodies too (redacted+truncated); default FALSE. */
+    /** Capture request/response bodies too (redacted and optionally truncated); default FALSE. */
     captureBodies: boolean;
-    /** Per-body truncation cap in bytes; default 8192, clamped. */
+    /** Per-body truncation cap in bytes. `-1` disables truncation; default `-1`. */
     maxBodyBytes: number;
     /** TTL retention in days; default 7, clamped `[1, 365]`. */
     retentionDays: number;
@@ -94,5 +94,12 @@ declare const DEFAULT_AUDIT_CONFIG: AuditConfig;
 interface AuditQueryResult {
     records: AuditRecord[];
 }
+/** Metadata-only aggregate for an audit time window (body payloads are never returned). */
+interface AuditStats {
+    requestCount: number;
+    errorCount: number;
+    /** False when the store could not produce an exact aggregate. */
+    complete: boolean;
+}
 
-export { type AuditConfig, type AuditQueryResult, type AuditRecord, DEFAULT_AUDIT_CONFIG };
+export { type AuditConfig, type AuditQueryResult, type AuditRecord, type AuditStats, DEFAULT_AUDIT_CONFIG };

package/dist/audit-types.d.ts

@@ -19,8 +19,9 @@
 /**
  * One per-request audit entry (design D1). The metadata fields are recorded
  * whenever audit is `enabled`; the two body snapshots are present ONLY when
- * `captureBodies` is ALSO on, and always after truncation + redaction. NO field
- * ever holds key material, an upstream token, or an Authorization/api-key header.
+ * `captureBodies` is ALSO on, and always after optional truncation + redaction.
+ * NO field ever holds key material, an upstream token, or an
+ * Authorization/api-key header.
  */
 interface AuditRecord {
     /** Unique record id (a generated request id — NOT any secret). */
@@ -54,14 +55,13 @@ interface AuditRecord {
     /** Sanitized error message (present only on a failed relay). */
     error?: string;
     /**
-     * Request body snapshot — present ONLY when `captureBodies`, truncated to the
-     * configured cap, and ALWAYS run through the secret-redaction pass first.
+     * Request body snapshot — present ONLY when `captureBodies`, optionally
+     * truncated to the configured cap, and ALWAYS run through secret redaction.
      */
     requestBody?: string;
     /**
-     * Response body snapshot — present ONLY when `captureBodies` AND the response
-     * was NON-streaming (a streaming response records metadata only), truncated +
-     * redacted like `requestBody`.
+     * Response body snapshot — present ONLY when `captureBodies`; streaming
+     * responses are included. Optionally truncated + redacted like `requestBody`.
      */
     responseBody?: string;
 }
@@ -74,9 +74,9 @@ interface AuditRecord {
 interface AuditConfig {
     /** Master switch; default FALSE (zero regression). */
     enabled: boolean;
-    /** Capture request/response bodies too (redacted+truncated); default FALSE. */
+    /** Capture request/response bodies too (redacted and optionally truncated); default FALSE. */
     captureBodies: boolean;
-    /** Per-body truncation cap in bytes; default 8192, clamped. */
+    /** Per-body truncation cap in bytes. `-1` disables truncation; default `-1`. */
     maxBodyBytes: number;
     /** TTL retention in days; default 7, clamped `[1, 365]`. */
     retentionDays: number;
@@ -94,5 +94,12 @@ declare const DEFAULT_AUDIT_CONFIG: AuditConfig;
 interface AuditQueryResult {
     records: AuditRecord[];
 }
+/** Metadata-only aggregate for an audit time window (body payloads are never returned). */
+interface AuditStats {
+    requestCount: number;
+    errorCount: number;
+    /** False when the store could not produce an exact aggregate. */
+    complete: boolean;
+}
 
-export { type AuditConfig, type AuditQueryResult, type AuditRecord, DEFAULT_AUDIT_CONFIG };
+export { type AuditConfig, type AuditQueryResult, type AuditRecord, type AuditStats, DEFAULT_AUDIT_CONFIG };

package/dist/audit-types.js

@@ -2,7 +2,7 @@
 var DEFAULT_AUDIT_CONFIG = {
   enabled: false,
   captureBodies: false,
-  maxBodyBytes: 8192,
+  maxBodyBytes: -1,
   retentionDays: 7,
   trustForwardedFor: false
 };

package/dist/index.cjs

@@ -79,7 +79,7 @@ module.exports = __toCommonJS(index_exports);
 var DEFAULT_AUDIT_CONFIG = {
   enabled: false,
   captureBodies: false,
-  maxBodyBytes: 8192,
+  maxBodyBytes: -1,
   retentionDays: 7,
   trustForwardedFor: false
 };

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 export { AccountClientIdentity, AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, ProxyConfig, SanitizedProxyConfig, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus } from './account-tokens-types.cjs';
 import { SubscriptionProviderId } from './subscription-types.cjs';
 export { OpenCodeGoModelEntry, OpenCodeGoScenario, OpenCodeGoTokenConfig, OpenCodeGoTokenSanitized, ProviderChannel, SubscriptionListEntry, SubscriptionStatusEntry, legacyCliBackendToSubscriptionProvider, subscriptionTargetForSession } from './subscription-types.cjs';
-export { AuditConfig, AuditQueryResult, AuditRecord, DEFAULT_AUDIT_CONFIG } from './audit-types.cjs';
+export { AuditConfig, AuditQueryResult, AuditRecord, AuditStats, DEFAULT_AUDIT_CONFIG } from './audit-types.cjs';
 export { BillingConfig, BillingDeliveryStatus, BillingEvent, DEFAULT_BILLING_CONFIG } from './billing-types.cjs';
 export { KNOWN_MODELS, KnownModelCapabilities, MODEL_ALIASES, ResolvedModelCapabilities, applyAlias, lookupCanonicalCapabilities, normalizeModelId, resolveModelCapabilities } from './canonical-models.cjs';
 export { AnthropicAudioContent, AnthropicChatRequest, AnthropicChatResponse, AnthropicContentPart, AnthropicImageContent, AnthropicMessage, AnthropicSystemContent, AnthropicTextContent, AnthropicThinkingContent, AnthropicTool, AnthropicToolResultContent, AnthropicToolUseContent, AnthropicVideoContent, ConversionConfig, OpenAIChatRequest, OpenAIChatResponse, OpenAIContentPart, OpenAIMessage, OpenAIStreamChunk, OpenAITool, OpenAIToolCall, SimpleChatAudio, SimpleChatImage, SimpleChatMessage, SimpleChatSession, SimpleChatVideo } from './completion-types.cjs';
@@ -16,7 +16,7 @@ export { DEFAULT_LITELLM_PRICING_URL, DEFAULT_OPENROUTER_PRICING_URL, PricingCon
 export { CATALOG_VERSION, CODING_PLAN_URL_PRESETS, DEFAULT_SEED_PRESET_IDS, LLM_PROVIDER_PRESETS, MAX_CONCURRENCY_DEFAULTS, PROVIDER_MODEL_MAPPINGS, PROVIDER_SEARCH_CONFIGS, getAllProviderPresets, getCodingPlanBaseUrl, getPresetById, getPresetRevision, getProviderSearchConfig, resolveFollowProviderModel } from './provider-presets/index.cjs';
 export { SUBSCRIPTION_MODEL_CATALOG, subscriptionProviderHasCatalog } from './subscription-model-catalog.cjs';
 export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel } from './thinking-config.cjs';
-export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals } from './usage-stats-types.cjs';
+export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageCacheKeySource, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals } from './usage-stats-types.cjs';
 export { UsageEngineOrigin, UsageTokens } from './usage-types.cjs';
 export { DEFAULT_VOUCHER_CONFIG, VoucherConfig, VoucherCreated, VoucherGrant, VoucherInfo, VoucherRecord, VoucherRedeemResult, VoucherStatus, VoucherType } from './voucher-types.cjs';
 export { SanitizedWebhookConfig, SanitizedWebhookDestination, WEBHOOK_DESTINATION_TYPES, WEBHOOK_EVENT_KINDS, WebhookAnomalyState, WebhookConfig, WebhookDestination, WebhookDestinationType, WebhookEvent, WebhookEventKind, WebhookQuotaScope } from './webhook-types.cjs';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { AccountClientIdentity, AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, ProxyConfig, SanitizedProxyConfig, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus } from './account-tokens-types.js';
 import { SubscriptionProviderId } from './subscription-types.js';
 export { OpenCodeGoModelEntry, OpenCodeGoScenario, OpenCodeGoTokenConfig, OpenCodeGoTokenSanitized, ProviderChannel, SubscriptionListEntry, SubscriptionStatusEntry, legacyCliBackendToSubscriptionProvider, subscriptionTargetForSession } from './subscription-types.js';
-export { AuditConfig, AuditQueryResult, AuditRecord, DEFAULT_AUDIT_CONFIG } from './audit-types.js';
+export { AuditConfig, AuditQueryResult, AuditRecord, AuditStats, DEFAULT_AUDIT_CONFIG } from './audit-types.js';
 export { BillingConfig, BillingDeliveryStatus, BillingEvent, DEFAULT_BILLING_CONFIG } from './billing-types.js';
 export { KNOWN_MODELS, KnownModelCapabilities, MODEL_ALIASES, ResolvedModelCapabilities, applyAlias, lookupCanonicalCapabilities, normalizeModelId, resolveModelCapabilities } from './canonical-models.js';
 export { AnthropicAudioContent, AnthropicChatRequest, AnthropicChatResponse, AnthropicContentPart, AnthropicImageContent, AnthropicMessage, AnthropicSystemContent, AnthropicTextContent, AnthropicThinkingContent, AnthropicTool, AnthropicToolResultContent, AnthropicToolUseContent, AnthropicVideoContent, ConversionConfig, OpenAIChatRequest, OpenAIChatResponse, OpenAIContentPart, OpenAIMessage, OpenAIStreamChunk, OpenAITool, OpenAIToolCall, SimpleChatAudio, SimpleChatImage, SimpleChatMessage, SimpleChatSession, SimpleChatVideo } from './completion-types.js';
@@ -16,7 +16,7 @@ export { DEFAULT_LITELLM_PRICING_URL, DEFAULT_OPENROUTER_PRICING_URL, PricingCon
 export { CATALOG_VERSION, CODING_PLAN_URL_PRESETS, DEFAULT_SEED_PRESET_IDS, LLM_PROVIDER_PRESETS, MAX_CONCURRENCY_DEFAULTS, PROVIDER_MODEL_MAPPINGS, PROVIDER_SEARCH_CONFIGS, getAllProviderPresets, getCodingPlanBaseUrl, getPresetById, getPresetRevision, getProviderSearchConfig, resolveFollowProviderModel } from './provider-presets/index.js';
 export { SUBSCRIPTION_MODEL_CATALOG, subscriptionProviderHasCatalog } from './subscription-model-catalog.js';
 export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel } from './thinking-config.js';
-export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals } from './usage-stats-types.js';
+export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageCacheKeySource, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals } from './usage-stats-types.js';
 export { UsageEngineOrigin, UsageTokens } from './usage-types.js';
 export { DEFAULT_VOUCHER_CONFIG, VoucherConfig, VoucherCreated, VoucherGrant, VoucherInfo, VoucherRecord, VoucherRedeemResult, VoucherStatus, VoucherType } from './voucher-types.js';
 export { SanitizedWebhookConfig, SanitizedWebhookDestination, WEBHOOK_DESTINATION_TYPES, WEBHOOK_EVENT_KINDS, WebhookAnomalyState, WebhookConfig, WebhookDestination, WebhookDestinationType, WebhookEvent, WebhookEventKind, WebhookQuotaScope } from './webhook-types.js';

package/dist/index.js

@@ -2,7 +2,7 @@
 var DEFAULT_AUDIT_CONFIG = {
   enabled: false,
   captureBodies: false,
-  maxBodyBytes: 8192,
+  maxBodyBytes: -1,
   retentionDays: 7,
   trustForwardedFor: false
 };

package/dist/usage-stats-types.d.cts

@@ -12,6 +12,11 @@ import { UsageEngineOrigin } from './usage-types.cjs';
  * @module usage-stats-types
  */
 
+/**
+ * How the prompt-cache key attached to a request was obtained. Values describe
+ * only the extraction path; raw session ids and cache keys are never persisted.
+ */
+type UsageCacheKeySource = 'client' | 'session-header' | 'thread-header' | 'body-session-id' | 'body-thread-id' | 'content-fingerprint' | 'none';
 /**
  * One captured LLM request, as persisted by the host store.
  *
@@ -43,6 +48,10 @@ interface UsageEventRecord {
     runId?: string | null;
     /** Host event-correlation id for this LLM call. NULL when unknown. Additive / nullable. */
     eventId?: string | null;
+    /** Safe prompt-cache-key provenance; absent on historical/non-attributed rows. */
+    cacheKeySource?: UsageCacheKeySource;
+    /** True only when the gateway generated and attached the prompt-cache key. */
+    cacheKeyInjected?: boolean;
 }
 /** Input shape for inserting a new event. `id` and `ts` are filled by the recorder/store. */
 type UsageEventInput = Omit<UsageEventRecord, 'id' | 'ts'> & {
@@ -69,6 +78,12 @@ interface UsageTotals {
     costSavedByCacheUsd: number;
     /** Number of events contributing to these totals. */
     eventCount: number;
+    /** Events with at least one prompt-side token, eligible for cache-rate metrics. */
+    cacheEligibleEventCount: number;
+    /** Eligible events that read zero tokens from cache. */
+    coldCacheEventCount: number;
+    /** Median of per-event cache-read ratios; null when no event is eligible. */
+    medianCacheHitRate: number | null;
 }
 /** Granularity for a usage time-series query. `week` is NOT a bucket — a "week" view is a `day` bucket over a 7-day range. */
 type UsageTimeBucket = 'hour' | 'day' | 'month';
@@ -161,4 +176,4 @@ interface MessageUsageRow {
     costSavedByCacheUsd: number;
 }
 
-export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageCacheKeySource, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };

package/dist/usage-stats-types.d.ts

@@ -12,6 +12,11 @@ import { UsageEngineOrigin } from './usage-types.js';
  * @module usage-stats-types
  */
 
+/**
+ * How the prompt-cache key attached to a request was obtained. Values describe
+ * only the extraction path; raw session ids and cache keys are never persisted.
+ */
+type UsageCacheKeySource = 'client' | 'session-header' | 'thread-header' | 'body-session-id' | 'body-thread-id' | 'content-fingerprint' | 'none';
 /**
  * One captured LLM request, as persisted by the host store.
  *
@@ -43,6 +48,10 @@ interface UsageEventRecord {
     runId?: string | null;
     /** Host event-correlation id for this LLM call. NULL when unknown. Additive / nullable. */
     eventId?: string | null;
+    /** Safe prompt-cache-key provenance; absent on historical/non-attributed rows. */
+    cacheKeySource?: UsageCacheKeySource;
+    /** True only when the gateway generated and attached the prompt-cache key. */
+    cacheKeyInjected?: boolean;
 }
 /** Input shape for inserting a new event. `id` and `ts` are filled by the recorder/store. */
 type UsageEventInput = Omit<UsageEventRecord, 'id' | 'ts'> & {
@@ -69,6 +78,12 @@ interface UsageTotals {
     costSavedByCacheUsd: number;
     /** Number of events contributing to these totals. */
     eventCount: number;
+    /** Events with at least one prompt-side token, eligible for cache-rate metrics. */
+    cacheEligibleEventCount: number;
+    /** Eligible events that read zero tokens from cache. */
+    coldCacheEventCount: number;
+    /** Median of per-event cache-read ratios; null when no event is eligible. */
+    medianCacheHitRate: number | null;
 }
 /** Granularity for a usage time-series query. `week` is NOT a bucket — a "week" view is a `day` bucket over a 7-day range. */
 type UsageTimeBucket = 'hour' | 'day' | 'month';
@@ -161,4 +176,4 @@ interface MessageUsageRow {
     costSavedByCacheUsd: number;
 }
 
-export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageCacheKeySource, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };

package/dist/webhook-types.d.cts

@@ -20,7 +20,7 @@
  * @module webhook-types
  */
 /** The coarse anomaly state an account transitioned into (secret-free). */
-type WebhookAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded';
+type WebhookAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded' | 'quota_exhausted';
 /** The cost-limit scope a key quota event refers to. */
 type WebhookQuotaScope = 'daily' | 'weekly' | 'total';
 /**

package/dist/webhook-types.d.ts

@@ -20,7 +20,7 @@
  * @module webhook-types
  */
 /** The coarse anomaly state an account transitioned into (secret-free). */
-type WebhookAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded';
+type WebhookAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded' | 'quota_exhausted';
 /** The cost-limit scope a key quota event refers to. */
 type WebhookQuotaScope = 'daily' | 'weekly' | 'total';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnicross/contracts",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Dependency-light, host-agnostic contract types + runtime-value helpers shared by the @omnicross/* packages.",
   "license": "MIT",
   "author": "Sayo (https://github.com/Dumoedss)",