@usagetap/sdk 1.3.2 → 1.4.0

package/dist/client-CExQ8e1T.d.ts

@@ -0,0 +1,1225 @@
+type ReasoningLevel = "NONE" | "LOW" | "MEDIUM" | "HIGH";
+/** Provider execution setting used for a completed call. */
+type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/** How UsageTap learned the execution reasoning effort. */
+type ReasoningEffortSource = "provider_response" | "provider_request" | "gateway_config" | "model_default";
+type LimitType = "NONE" | "BLOCK" | "DOWNGRADE";
+interface RequestedEntitlements {
+    standard?: boolean;
+    premium?: boolean;
+    audio?: boolean;
+    image?: boolean;
+    search?: boolean;
+    reasoningLevel?: ReasoningLevel;
+}
+type AllowedEntitlements = Required<RequestedEntitlements>;
+type ModelTier = "premium" | "standard" | "none";
+interface EntitlementDowngradeHint {
+    reason: string;
+    fallbackTier?: ModelTier;
+}
+interface EntitlementHints {
+    suggestedModelTier: ModelTier;
+    reasoningLevel: ReasoningLevel;
+    policy: LimitType;
+    downgrade?: EntitlementDowngradeHint;
+}
+interface MeterSummary {
+    /** Always numeric. Check the `unlimited` flag to detect unbounded meters. */
+    remaining: number;
+    limit: number | null;
+    /** Always numeric (0 when no usage recorded). */
+    used: number;
+    /** When true this meter is unbounded; `remaining` is informational only. */
+    unlimited: boolean;
+    /** remaining / limit (0-1). null when unlimited or limit is null/0. */
+    ratio: number | null;
+    label?: string;
+}
+type MeterSnapshot = Record<string, MeterSummary>;
+type RemainingRatios = Record<string, number | null | undefined>;
+interface RollingCallsRateLimitState {
+    windowType: "rolling_calls";
+    limit: number;
+    used: number;
+    remaining: number;
+    windowSeconds: number;
+    state: "fresh" | "estimated" | "stale" | "unknown";
+    source?: "current_rolling_check" | "call_records";
+    nextAvailableAt?: string;
+    scope?: {
+        callType?: "standard" | "API";
+        tier?: "standard" | "premium";
+    };
+}
+interface RateLimitsSnapshot {
+    rollingCalls?: RollingCallsRateLimitState | Record<string, RollingCallsRateLimitState>;
+}
+interface SubscriptionSnapshot {
+    id: string | null;
+    usagePlanVersionId: string | null;
+    planName: string | null;
+    planVersion: string | null;
+    limitType: LimitType;
+    reasoningLevel: ReasoningLevel;
+    lastReplenishedAt: string | null;
+    nextReplenishAt: string | null;
+    subscriptionVersion: number | null;
+    customerFriendlyName?: string | null;
+    customerEmail?: string | null;
+    pending?: {
+        usagePlanVersionId: string | null;
+        strategy: string | null;
+        effectiveAt: string | null;
+    };
+    stripeCustomerId?: string | null;
+}
+type ModelHints = Record<string, string[]>;
+interface IdempotencyMetadata {
+    key: string;
+    source: "explicit" | "derived";
+}
+interface VendorHints {
+    preferredModel?: string;
+    reasoning?: ReasoningLevel;
+    maxInputTokens?: number;
+    maxResponseTokens?: number;
+}
+interface PromptCompressionRequest {
+    callId: string;
+    input?: unknown;
+    text?: string;
+    provider?: "heuristic" | "toon" | "thetokencompany" | "usagetap";
+    model?: string;
+    tokenCompanyModel?: string;
+    /** Provider-neutral compression aggressiveness from 0.0 to 1.0. */
+    aggressiveness?: number;
+    /** @deprecated Use aggressiveness instead. */
+    tokenCompanyAggressiveness?: number;
+    tokenCompanyAppId?: string;
+    usageTapCompressionModel?: string;
+    /** @deprecated Use aggressiveness instead. */
+    usageTapCompressionAggressiveness?: number;
+}
+interface PromptCompressionTelemetry {
+    provider: "heuristic" | "toon" | "thetokencompany" | "usagetap";
+    originalTokens: number;
+    compressedTokens: number;
+    savedTokens: number;
+    tokenSavingsRatio: number;
+    techniques: string[];
+}
+interface BeginCallRequest {
+    customerId: string;
+    /**
+     * Identifies one application workflow or agent run for local circuit-breaker
+     * enforcement. This value is used by the SDK only and is not sent to UsageTap.
+     */
+    runId?: string;
+    requested?: RequestedEntitlements;
+    feature?: string;
+    tags?: string[];
+    /**
+     * Optional PAYG hold hint (USD) to authorize upfront during call_begin.
+     * When provided, overrides the plan's default hold for this call only.
+     */
+    holdUsd?: number;
+    /**
+     * Idempotency key for safe retries.
+     * The SDK generates a unique key by default. Direct API callers should send
+     * one explicitly and reuse it only when retrying the same logical call.
+     * @deprecated Use idempotencyKey instead
+     */
+    idempotency?: string;
+    /**
+     * Idempotency key for safe retries.
+     * The SDK generates a unique key by default. Direct API callers should send
+     * one explicitly and reuse it only when retrying the same logical call.
+     */
+    idempotencyKey?: string;
+    customerName?: string;
+    customerEmail?: string;
+    /** Stable identifier for the end user who initiated this call. */
+    customerUserId?: string;
+    /** Display name for the end user who initiated this call. */
+    customerUserName?: string;
+    /** Email address for the end user who initiated this call. */
+    customerUserEmail?: string;
+    stripeCustomerId?: string;
+    /**
+     * Compatibility flag for batch pricing (typically 50% of standard rates).
+     * When both fields are supplied, pricingMode is authoritative.
+     */
+    batch?: boolean;
+    /**
+     * Explicit pricing mode for this call. Takes precedence over batch.
+     */
+    pricingMode?: "batch" | "standard";
+    /**
+     * Runtime Compression Policy resolution context. SDK adapters populate this
+     * automatically; direct integrations may provide it explicitly.
+     */
+    runtimeCompressionContext?: {
+        assignmentKey?: string;
+        projectId?: string;
+        provider?: string;
+        model?: string;
+    };
+}
+interface RuntimeCompressionPolicyDecision {
+    policyId: string;
+    policyVersionId: string;
+    version: number;
+    mode: "DRAFT" | "SHADOW" | "CANARY" | "ACTIVE" | "PAUSED" | "ARCHIVED";
+    selected: boolean;
+    snapshot: {
+        scope: {
+            minimumTokens: number;
+            messageRoles: string[];
+            contentTypes: string[];
+        };
+        methods: {
+            deterministic: {
+                enabled: true;
+            };
+            deepText: {
+                enabled: boolean;
+            };
+        };
+        gates: {
+            minimumTokensRemoved: number;
+            minimumReductionPercentage: number;
+            maximumLatencyMs: number;
+            maximumCompressionCostUsd?: number;
+            minimumProjectedNetSavingUsd?: number;
+        };
+        rollout: {
+            deterministicOnly: boolean;
+            deepTextCanaryAllowed: boolean;
+        };
+        capturePayloads: boolean;
+        payloadRetentionDays: number;
+    };
+}
+interface RuntimeCompressionMeasurement {
+    policyId: string;
+    policyVersionId: string;
+    policyVersion: number;
+    rolloutMode: RuntimeCompressionPolicyDecision["mode"];
+    decision: "compressed" | "skipped" | "fallback" | "bypassed" | "error";
+    reasonCode?: string;
+    methodsAttempted: string[];
+    methodsApplied: string[];
+    originalTokens: number;
+    resultTokens: number;
+    savedTokens: number;
+    reductionPercentage: number;
+    compressionLatencyMs: number;
+    compressionComputeCostUsd: number;
+    financialsEstimated: boolean;
+}
+interface BalanceSummary {
+    standardCallsRemaining?: number;
+    premiumCallsRemaining?: number;
+    tokensRemaining?: number;
+    searchesRemaining?: number;
+    audioSecondsRemaining?: number;
+    customMeter1Remaining?: number;
+    customMeter2Remaining?: number;
+}
+type SpendVelocityWindowKey = "hour" | "day";
+interface SpendVelocityWindow {
+    bucket: string;
+    windowMinutes: number;
+    startedAt: string;
+    endedAt: string;
+    completedCostUsd: number;
+    completedCalls: number;
+}
+interface SpendVelocitySnapshot {
+    currency: "USD";
+    source: "usage_aggregate";
+    generatedAt: string;
+    customerId: string;
+    currentCallCostUsd: number;
+    windows: Record<SpendVelocityWindowKey, SpendVelocityWindow>;
+}
+interface PlanSummary {
+    id: string | null;
+    name: string | null;
+    version: string | null;
+}
+interface BeginCallResponseBody {
+    callId: string;
+    callType?: "standard" | "API";
+    startTime: string;
+    feature?: string;
+    tags?: string[];
+    newCustomer: boolean;
+    canceled: boolean;
+    policy: LimitType;
+    allowed: AllowedEntitlements;
+    entitlementHints: EntitlementHints;
+    rateLimits?: RateLimitsSnapshot;
+    meters: MeterSnapshot;
+    remainingRatios: RemainingRatios;
+    subscription: SubscriptionSnapshot;
+    models?: ModelHints;
+    idempotency?: IdempotencyMetadata;
+    vendorHints?: VendorHints;
+    plan?: PlanSummary;
+    balances?: BalanceSummary;
+    stripeCustomerId?: string | null;
+    batch?: boolean;
+    pricingMode?: "batch" | "standard";
+    runtimeCompressionPolicy?: RuntimeCompressionPolicyDecision;
+}
+interface EndCallRequest {
+    callId: string;
+    /** Optional customer ID for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    customerId?: string;
+    /** Optional feature for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    feature?: string;
+    /** Optional tags for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    tags?: string[];
+    /** Vendor that executed the request, for example `openai` or `anthropic`. */
+    providerUsed?: string;
+    modelUsed?: string;
+    /** Reasoning effort actually used, or the best-known requested/configured value. */
+    reasoningEffort?: ReasoningEffort;
+    /** Provenance for reasoningEffort. Provider responses are most authoritative. */
+    reasoningEffortSource?: ReasoningEffortSource;
+    /** Provider-specific reasoning mode, such as `enabled` or `adaptive`. */
+    reasoningMode?: string;
+    /** Explicit reasoning/thinking token budget when the provider supports one. */
+    reasoningBudgetTokens?: number;
+    /**
+     * Total prompt/input tokens for the call (including any cached prompt tokens).
+     */
+    inputTokens?: number;
+    responseTokens?: number;
+    /**
+     * Prompt/input tokens served from cache.
+     * Preferred over legacy aliases.
+     */
+    cachedInputTokens?: number;
+    /**
+     * Prompt/input tokens written to a provider prompt cache.
+     * inputTokens must include these tokens.
+     */
+    cacheWriteInputTokens?: number;
+    reasoningTokens?: number;
+    searches?: number;
+    audio?: number;
+    audioSeconds?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * Optional downstream status metadata for direct integrations.
+     * Prefer `error` for failed provider calls.
+     */
+    responseStatusCode?: number;
+    /**
+     * Optional downstream error metadata for direct integrations.
+     * Prefer `error` for failed provider calls.
+     */
+    responseErrorMessage?: string;
+    /**
+     * Advanced compatibility override for model-tier classification.
+     */
+    isPremium?: boolean;
+    stripeCustomerId?: string;
+    /**
+     * Compatibility flag for batch pricing (typically 50% of standard rates).
+     * When both fields are supplied, pricingMode is authoritative.
+     */
+    batch?: boolean;
+    /**
+     * Explicit pricing mode for this call. Takes precedence over batch.
+     */
+    pricingMode?: "batch" | "standard";
+    runtimeCompression?: RuntimeCompressionMeasurement;
+}
+interface MeteredUsage {
+    calls?: number;
+    tokens?: number;
+    reasoningTokens?: number;
+    searches?: number;
+    audio?: number;
+    audioSeconds?: number;
+}
+interface EndCallResponseBody {
+    callId: string;
+    status?: "COMPLETED" | "FAILED";
+    error?: {
+        code: string;
+        message: string;
+    };
+    providerUsed?: string;
+    modelUsed?: string;
+    reasoningEffort?: ReasoningEffort;
+    reasoningEffortSource?: ReasoningEffortSource;
+    reasoningMode?: string;
+    reasoningBudgetTokens?: number;
+    /** Final model cost after the selected pricing mode is applied. */
+    costUSD: number;
+    /** Integer decimal representation used by the API for high-precision cost storage. */
+    costUsdNano?: string;
+    costBreakdown?: Record<string, unknown>;
+    /** Model cost before a vendor-batch discount is applied. */
+    standardCostUSD?: number;
+    /** Multiplier applied to standardCostUSD (0.5 for batch, 1 for standard). */
+    pricingMultiplier?: number;
+    usage?: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        cacheWriteInputTokens: number;
+        billableInputTokens: number;
+        responseTokens: number;
+        reasoningTokens: number;
+    };
+    metered?: MeteredUsage;
+    spendVelocity?: SpendVelocitySnapshot;
+    policy?: LimitType;
+    allowed?: AllowedEntitlements;
+    entitlementHints?: EntitlementHints;
+    meters?: MeterSnapshot;
+    remainingRatios?: RemainingRatios;
+    subscription?: SubscriptionSnapshot;
+    models?: ModelHints;
+    plan?: PlanSummary;
+    balances?: BalanceSummary;
+    stripeCustomerId?: string | null;
+    batch?: boolean;
+    pricingMode?: "batch" | "standard";
+}
+type UsageTapResultStatus = "ACCEPTED" | "ERROR";
+interface UsageTapResultEnvelope {
+    status: UsageTapResultStatus;
+    code?: string;
+    message?: string;
+    timestamp?: string;
+}
+interface UsageTapErrorPayload {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface UsageTapSuccessResponse<TData> {
+    result: UsageTapResultEnvelope;
+    data: TData;
+    correlationId: string;
+}
+interface UsageTapErrorResponse {
+    result: UsageTapResultEnvelope;
+    error: UsageTapErrorPayload;
+    correlationId: string;
+}
+interface RetryOptions {
+    /**
+     * Maximum number of attempts including the initial try.
+     * @default 3
+     */
+    maxAttempts?: number;
+    /**
+     * Base backoff delay in milliseconds.
+     * @default 250
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum backoff delay in milliseconds.
+     * @default 5000
+     */
+    maxDelayMs?: number;
+    /**
+     * Jitter ratio between 0 and 1 applied to the computed delay.
+     * @default 0.2
+     */
+    jitterRatio?: number;
+}
+interface UsageTapLogEntry {
+    event: "request:start" | "request:success" | "request:error" | "retry:scheduled" | "retry:exhausted";
+    path: string;
+    attempt: number;
+    elapsedMs?: number;
+    idempotencyKey?: string;
+    correlationId?: string;
+    error?: unknown;
+}
+interface UsageTapClientOptions {
+    /**
+     * UsageTap API key. Defaults to the server-side USAGETAP_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * UsageTap API base URL. Defaults to USAGETAP_BASE_URL, then https://api.usagetap.com.
+     */
+    baseUrl?: string;
+    /**
+     * UsageTap Gateway base URL. Defaults to USAGETAP_GATEWAY_URL, then
+     * https://gateway.usagetap.com.
+     */
+    gatewayBaseUrl?: string;
+    defaultFeature?: string;
+    defaultTags?: string[];
+    fetchImpl?: typeof fetch;
+    headers?: Record<string, string>;
+    retries?: RetryOptions;
+    idempotencyGenerator?: () => string;
+    /**
+     * When true (default), the client auto-generates an idempotency key when one is not provided.
+     * Set to false to rely on the backend's deterministic fallback.
+     */
+    autoIdempotency?: boolean;
+    onLog?: (entry: UsageTapLogEntry) => void;
+    /**
+     * Callback invoked when usage metrics are recorded (call_end, custom_meter).
+     * Use this to export metrics to OpenTelemetry or other observability systems.
+     */
+    onUsageMetric?: (event: UsageMetricEvent) => void;
+    /**
+     * Override the default Authorization header with x-api-key when true.
+     */
+    useApiKeyHeader?: boolean;
+    /**
+     * Allow constructing the client in browser-like environments for testing.
+     */
+    allowBrowser?: boolean;
+    /** API key for The Token Company Bear compression API. */
+    tokenCompanyApiKey?: string;
+    /** Override endpoint for The Token Company compatible compression APIs. */
+    tokenCompanyEndpoint?: string;
+    /** Default model for The Token Company compression. */
+    model?: string;
+    tokenCompanyModel?: string;
+    /** Default compression aggressiveness, from 0.0 to 1.0. */
+    aggressiveness?: number;
+    /** @deprecated Use aggressiveness instead. */
+    tokenCompanyAggressiveness?: number;
+    /** Optional application identifier sent to The Token Company. */
+    tokenCompanyAppId?: string;
+    /** API key for UsageTap prompt compression. Defaults to apiKey when omitted. */
+    usageTapCompressionApiKey?: string;
+    /** Override endpoint for UsageTap-compatible prompt compression APIs. */
+    usageTapCompressionEndpoint?: string;
+    /** Override endpoint for UsageTap-compatible message/request compression APIs. */
+    usageTapCompressionMessagesEndpoint?: string;
+    /** Default model for UsageTap prompt compression. */
+    usageTapCompressionModel?: string;
+    /** @deprecated Use aggressiveness instead. */
+    usageTapCompressionAggressiveness?: number;
+    /** Local policy override. Omit to load the saved UsageTap policy; false disables sampling. */
+    sampling?: SamplingOptions | false;
+    /** Maximum local lifetime for remotely loaded sampling settings. Defaults to 5 minutes. */
+    samplingSettingsCacheMs?: number;
+    /**
+     * Optional local hard stop for recursive or runaway workflows.
+     * Calls without a runId are not affected.
+     */
+    circuitBreaker?: CircuitBreakerOptions | false;
+}
+interface CircuitBreakerOptions {
+    /** Maximum call_begin attempts allowed for one customerId + runId pair. */
+    maxCallsPerRun: number;
+    /**
+     * Forget inactive runs after this many milliseconds.
+     * Defaults to 60 minutes. Call resetRun() when a run completes to release it sooner.
+     */
+    runInactivityMs?: number;
+}
+interface CircuitBreakerDecision {
+    allowed: boolean;
+    reason?: "max_calls_per_run";
+    customerId: string;
+    runId: string;
+    calls: number;
+    limit: number;
+    remaining: number;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    retries?: RetryOptions;
+}
+interface SamplingOptions {
+    /** Fraction of eligible calls to retain, from 0 to 1. */
+    rate: number;
+    /** Skip inputs below this local estimated-token threshold. */
+    minInputTokens?: number;
+    features?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    customers?: {
+        exclude?: string[];
+    };
+    /** Optional deterministic random source, primarily for testing. */
+    random?: () => number;
+}
+interface SamplingDecisionInput {
+    customerId?: string;
+    feature?: string;
+    input: unknown;
+}
+interface SamplingSettings extends Omit<SamplingOptions, "random"> {
+    version: string;
+    retentionDays: number;
+    cacheSeconds: number;
+    settingsExpiresAt: string;
+}
+interface GetSamplingSettingsOptions extends RequestOptions {
+    correlationId?: string;
+    forceRefresh?: boolean;
+}
+interface SamplingDecisionRequest {
+    samplingKey?: string;
+    customerId?: string;
+    feature?: string;
+    inputTokens?: number;
+    inputCharacters?: number;
+}
+interface SamplingDecisionResponseBody {
+    sample: boolean;
+    reason: "selected" | "rate_disabled" | "customer_excluded" | "feature_excluded" | "feature_not_included" | "below_minimum_tokens" | "rate_not_selected";
+    decisionId: string;
+    samplingKey: string;
+    policyVersion: string;
+    settingsExpiresAt: string;
+    score?: number;
+}
+interface SamplingDecisionOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface CaptureSampleRequest extends SamplingDecisionInput {
+    sampleId?: string;
+    /** Exact UsageTap call ID when this sample belongs to a metered call. */
+    callId?: string;
+    environment?: string;
+    tags?: string[];
+    provider: string;
+    model?: string;
+    output?: unknown;
+    usage?: unknown;
+    latencyMs?: number;
+    error?: unknown;
+    decisionId?: string;
+    policyVersion?: string;
+}
+interface CaptureSampleOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface CaptureSampleResponseBody {
+    sampleId: string;
+    stored?: boolean;
+    receivedAt: string;
+    expiresAt: string;
+    retentionDays: number;
+    policyVersion?: string;
+    payloadStorage?: "dynamodb" | "s3";
+}
+interface PromptCompressionStandaloneOptions {
+    signal?: AbortSignal;
+    provider?: "heuristic" | "toon" | "thetokencompany" | "usagetap";
+    failOpen?: boolean;
+    model?: string;
+    tokenCompanyModel?: string;
+    /** Provider-neutral compression aggressiveness from 0.0 to 1.0. */
+    aggressiveness?: number;
+    /** @deprecated Use aggressiveness instead. */
+    tokenCompanyAggressiveness?: number;
+    tokenCompanyAppId?: string;
+    usageTapCompressionModel?: string;
+    /** @deprecated Use aggressiveness instead. */
+    usageTapCompressionAggressiveness?: number;
+}
+type PromptCompressionMessageRole$1 = "system" | "user" | "tool" | "assistant";
+type PromptCompressionRoleAggressiveness$1 = Partial<Record<PromptCompressionMessageRole$1, number>>;
+type PromptCompressionMessagesAggressiveness$1 = number | PromptCompressionRoleAggressiveness$1;
+interface PromptCompressionMessagesOptions extends RequestOptions {
+    provider?: "usagetap";
+    failOpen?: boolean;
+    /** Select deterministic-only, automatic model gating, or a forced model pass. */
+    mode?: "deterministic" | "model_auto" | "model_force";
+    /** Provider-neutral scalar or per-role compression aggressiveness. */
+    aggressiveness?: PromptCompressionMessagesAggressiveness$1;
+    /** Maximum compression latency the service should target. */
+    latencyBudgetMs?: number;
+    /** Remove empty user messages before compression. */
+    compactEmptyUserMessages?: boolean;
+    /** Deduplicate repeated text parts within user messages. */
+    compactDuplicateUserTextParts?: boolean;
+    /** @deprecated Use aggressiveness instead. */
+    usageTapCompressionAggressiveness?: PromptCompressionMessagesAggressiveness$1;
+}
+interface RecordPromptCompressionRequest {
+    callId: string;
+    promptCompression: PromptCompressionTelemetry;
+}
+interface BeginCallOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface EndCallOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface PromptCompressionOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface PromptCompressionResponseBody extends PromptCompressionTelemetry {
+    callId: string;
+    updated: boolean;
+}
+interface WithUsageContext {
+    begin: UsageTapSuccessResponse<BeginCallResponseBody>;
+    setUsage: (usage: Partial<Omit<EndCallRequest, "callId" | "error">>) => void;
+    setError: (error: EndCallRequest["error"]) => void;
+}
+interface WithUsageOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    retries?: RetryOptions;
+    correlationId?: string;
+    /**
+     * Default error payload applied when the handler throws and setError was never invoked.
+     */
+    defaultErrorCode?: string;
+}
+interface CheckUsageRequest {
+    customerId: string;
+}
+interface CheckUsageOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface CheckUsageResponseBody {
+    customerId: string;
+    canceled: boolean;
+    policy: LimitType;
+    allowed: AllowedEntitlements;
+    entitlementHints: EntitlementHints;
+    rateLimits?: RateLimitsSnapshot;
+    meters: MeterSnapshot;
+    remainingRatios: RemainingRatios;
+    subscription: SubscriptionSnapshot;
+    models?: ModelHints;
+    plan?: PlanSummary;
+    balances?: BalanceSummary;
+    stripeCustomerId?: string | null;
+}
+interface CreateCustomerRequest {
+    customerId: string;
+    customerFriendlyName?: string;
+    customerName?: string;
+    customerEmail?: string;
+    stripeCustomerId?: string;
+}
+interface CreateCustomerOptions extends RequestOptions {
+    correlationId?: string;
+    idempotencyKey?: string;
+}
+interface CreateCustomerResponseBody extends CheckUsageResponseBody {
+    newCustomer: boolean;
+}
+type ChangePlanStrategy = "IMMEDIATE_RESET" | "IMMEDIATE_PRORATED" | "AT_NEXT_REPLENISH";
+interface ChangePlanRequest {
+    customerId: string;
+    planId: string;
+    strategy?: ChangePlanStrategy;
+}
+interface ChangePlanOptions extends RequestOptions {
+    correlationId?: string;
+    idempotencyKey?: string;
+}
+interface ChangePlanResponseBody {
+    success: boolean;
+    subscription: SubscriptionSnapshot;
+}
+type CustomMeterSlot = "CUSTOM1" | "CUSTOM2";
+interface IncrementCustomMeterRequest {
+    customerId: string;
+    /** Stable identifier for the end user responsible for this meter event. */
+    customerUserId?: string;
+    /** Display name for the end user responsible for this meter event. */
+    customerUserName?: string;
+    /** Email address for the end user responsible for this meter event. */
+    customerUserEmail?: string;
+    meterSlot: CustomMeterSlot;
+    amount: number;
+    feature?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface IncrementCustomMeterOptions extends RequestOptions {
+    correlationId?: string;
+    idempotencyKey?: string;
+}
+interface IncrementCustomMeterResponseBody {
+    success: boolean;
+    eventId: string;
+    meterSlot: CustomMeterSlot;
+    amount: number;
+    meter: MeterSummary;
+    blocked: boolean;
+}
+/**
+ * Event emitted when usage metrics are recorded.
+ * Use with `onUsageMetric` callback to export to OpenTelemetry or other observability systems.
+ */
+interface UsageMetricEvent {
+    /** Type of metric event */
+    type: "call_end" | "custom_meter";
+    /** Timestamp in ISO 8601 format */
+    timestamp: string;
+    /** Customer identifier */
+    customerId: string;
+    /** Unique call identifier (for call_end events) */
+    callId?: string;
+    /** Feature tag */
+    feature?: string;
+    /** Additional tags */
+    tags?: string[];
+    /** Model used for the call */
+    modelUsed?: string;
+    /** Vendor that executed the request */
+    providerUsed?: string;
+    /** Reasoning effort used for the call */
+    reasoningEffort?: ReasoningEffort;
+    /** Provenance for the reasoning effort */
+    reasoningEffortSource?: ReasoningEffortSource;
+    /** Provider-specific reasoning mode */
+    reasoningMode?: string;
+    /** Explicit reasoning/thinking token budget */
+    reasoningBudgetTokens?: number;
+    /** Usage metrics */
+    metrics: {
+        inputTokens?: number;
+        cachedInputTokens?: number;
+        cacheWriteInputTokens?: number;
+        responseTokens?: number;
+        reasoningTokens?: number;
+        searches?: number;
+        audioSeconds?: number;
+        costUsd?: number;
+        /** Custom meter slot (for custom_meter events) */
+        customMeterSlot?: CustomMeterSlot;
+        /** Custom meter amount (for custom_meter events) */
+        customMeterAmount?: number;
+    };
+    /** Correlation ID for tracing */
+    correlationId?: string;
+}
+
+type PromptCompressionProvider = "heuristic" | "toon" | "thetokencompany" | "usagetap";
+type PromptCompressionMessageRole = "system" | "user" | "tool" | "assistant";
+type PromptCompressionMode = "deterministic" | "model_auto" | "model_force";
+type PromptCompressionRoleAggressiveness = Partial<Record<PromptCompressionMessageRole, number>>;
+type PromptCompressionMessagesAggressiveness = number | PromptCompressionRoleAggressiveness;
+interface PromptCompressionInput {
+    input?: unknown;
+    text?: string;
+    provider?: PromptCompressionProvider;
+    tokenCompanyApiKey?: string;
+    tokenCompanyEndpoint?: string;
+    model?: string;
+    tokenCompanyModel?: string;
+    aggressiveness?: number;
+    tokenCompanyAggressiveness?: number;
+    tokenCompanyAppId?: string;
+    usageTapCompressionApiKey?: string;
+    usageTapCompressionEndpoint?: string;
+    usageTapCompressionModel?: string;
+    usageTapCompressionAggressiveness?: number;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    failOpen?: boolean;
+}
+interface PromptCompressionMessagesInput<TInput = unknown> {
+    input: TInput;
+    provider?: Extract<PromptCompressionProvider, "usagetap">;
+    usageTapCompressionApiKey?: string;
+    usageTapCompressionMessagesEndpoint?: string;
+    aggressiveness?: PromptCompressionMessagesAggressiveness;
+    usageTapCompressionAggressiveness?: PromptCompressionMessagesAggressiveness;
+    /** Select deterministic-only, automatic model gating, or a forced model pass. */
+    mode?: PromptCompressionMode;
+    /** Maximum compression latency the service should target. */
+    latencyBudgetMs?: number;
+    /** Remove empty user messages before compression. */
+    compactEmptyUserMessages?: boolean;
+    /** Deduplicate repeated text parts within user messages. */
+    compactDuplicateUserTextParts?: boolean;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    failOpen?: boolean;
+}
+interface PromptCompressionResult<TInput = unknown> {
+    input: TInput;
+    compressedInput: unknown;
+    provider: PromptCompressionProvider;
+    originalCharacters: number;
+    compressedCharacters: number;
+    savedCharacters: number;
+    originalTokens: number;
+    compressedTokens: number;
+    savedTokens: number;
+    tokenSavingsRatio: number;
+    savingsRatio: number;
+    techniques: string[];
+}
+declare function protectPromptText(text: string): string;
+declare const protect: typeof protectPromptText;
+declare function compressPrompt<TInput = unknown>(options: PromptCompressionInput): Promise<PromptCompressionResult<TInput>>;
+declare function compressPromptHeuristic<TInput = unknown>(input: TInput): PromptCompressionResult<TInput>;
+declare function compressPromptToon<TInput = unknown>(input: TInput): PromptCompressionResult<TInput>;
+declare function compressPromptMessages<TInput = unknown>(options: PromptCompressionMessagesInput<TInput>): Promise<PromptCompressionResult<TInput>>;
+declare function estimatePromptTokens(input: unknown): number;
+
+type JsonRecord = Record<string, unknown>;
+interface ResourceRequestOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+}
+interface WaitOptions extends ResourceRequestOptions {
+    /** Delay between status requests. */
+    pollIntervalMs?: number;
+    /** Maximum total polling time. */
+    timeoutMs?: number;
+}
+interface SummarizationContext {
+    id: string;
+    type: string;
+    content: string;
+    version?: string;
+    contentType?: string;
+}
+type SummarizationStatus = "QUEUED" | "RUNNING" | "COMPLETE" | "FAILED";
+interface SummarizationJob {
+    jobId: string;
+    status: SummarizationStatus;
+    phase?: string;
+    profile?: string;
+    version?: number;
+    statusUrl?: string;
+    progress?: JsonRecord;
+    billing?: JsonRecord;
+    result?: JsonRecord;
+    error?: string;
+}
+interface SummarizationCreateParams {
+    profile: string;
+    context: SummarizationContext;
+    wait?: boolean;
+}
+interface SummarizationBatchCreateParams {
+    profile: string;
+    items: SummarizationContext[];
+}
+interface SummarizationBatchJob extends Partial<SummarizationJob> {
+    jobId: string;
+    contextId?: string;
+}
+interface SummarizationBatch {
+    batchId: string;
+    status: SummarizationStatus;
+    profile?: string;
+    version?: number;
+    submittedAt?: string;
+    statusUrl?: string;
+    jobs: SummarizationBatchJob[];
+}
+interface SummarizationProfile {
+    profile: string;
+    version: number;
+    name: string;
+    description?: string;
+    settings: {
+        model: string;
+        reasoningEffort?: string;
+        maxOutputTokens?: number;
+        outputFormat?: string;
+        outputSchema?: unknown;
+        temperature?: number;
+    };
+    prompt: {
+        system: string;
+        userTemplate: string;
+        contextPlaceholder: string;
+        assetId?: string;
+        schemaVersion?: string;
+    };
+    measurementUrl: string;
+}
+interface SummarizationMeasurementCreateParams {
+    profile: string;
+    contextId?: string;
+    source: {
+        tokens: number;
+    };
+    summary: {
+        tokens: number;
+    };
+    provider?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        costUsd?: number;
+    };
+}
+interface SummarizationMeasurement {
+    measurementId: string;
+    tokensSaved: number;
+    reported: boolean;
+}
+interface GatewayChatMessage {
+    role: string;
+    content: unknown;
+    [key: string]: unknown;
+}
+interface GatewayChatCompletionCreateParams {
+    model?: string;
+    models?: string[];
+    messages: GatewayChatMessage[];
+    stream?: false;
+    [key: string]: unknown;
+}
+interface GatewayChatCompletion {
+    id?: string;
+    object?: string;
+    created?: number;
+    model?: string;
+    choices: Array<{
+        index?: number;
+        message?: {
+            role?: string;
+            content?: string | null;
+            [key: string]: unknown;
+        };
+        finish_reason?: string | null;
+        [key: string]: unknown;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        [key: string]: unknown;
+    };
+    usagetap?: JsonRecord;
+    [key: string]: unknown;
+}
+interface GatewayModel {
+    id: string;
+    object?: string;
+    created?: number;
+    owned_by?: string;
+    [key: string]: unknown;
+}
+interface GatewayModelList {
+    object: string;
+    data: GatewayModel[];
+}
+type GatewayBatchStatus = "queued" | "submitting" | "in_progress" | "finalizing" | "cancelling" | "completed" | "failed" | "expired" | "cancelled";
+interface GatewayBatchRequest {
+    custom_id: string;
+    body: GatewayChatCompletionCreateParams;
+}
+interface GatewayBatchCreateParams {
+    requests: GatewayBatchRequest[];
+}
+interface GatewayBatch {
+    id: string;
+    object: "batch";
+    status: GatewayBatchStatus;
+    provider?: string;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+    request_counts: {
+        total: number;
+        completed: number;
+        failed: number;
+    };
+    calls: Array<{
+        custom_id: string;
+        call_id: string;
+        status: number;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }>;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface GatewayBatchResult {
+    custom_id: string;
+    call_id: string;
+    status: number;
+    response?: GatewayChatCompletion;
+    usage?: JsonRecord;
+    compression?: {
+        applied: boolean;
+        status: "applied" | "no_savings" | "failed_open";
+        original_input_tokens?: number;
+        compressed_input_tokens?: number;
+        tokens_saved?: number;
+        reduction_percent?: number;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface ResourceClientConfig {
+    apiKey: string;
+    apiBaseUrl: string;
+    gatewayBaseUrl?: string;
+    fetchImpl: typeof fetch;
+    headers?: Record<string, string>;
+    sdkVersion: string;
+    idempotencyGenerator?: () => string;
+}
+declare class SummarizationResource {
+    readonly summaries: {
+        create: (params: SummarizationCreateParams, options?: ResourceRequestOptions) => Promise<SummarizationJob>;
+        retrieve: (jobId: string, options?: ResourceRequestOptions) => Promise<SummarizationJob>;
+        wait: (job: string | SummarizationJob, options?: WaitOptions) => Promise<SummarizationJob>;
+    };
+    readonly batches: {
+        create: (params: SummarizationBatchCreateParams, options?: ResourceRequestOptions) => Promise<SummarizationBatch>;
+        retrieve: (batchId: string, options?: ResourceRequestOptions) => Promise<SummarizationBatch>;
+        wait: (batch: string | SummarizationBatch, options?: WaitOptions) => Promise<SummarizationBatch>;
+    };
+    readonly profiles: {
+        retrieve: (profile: string, options?: ResourceRequestOptions) => Promise<SummarizationProfile>;
+    };
+    readonly measurements: {
+        create: (params: SummarizationMeasurementCreateParams, options?: ResourceRequestOptions) => Promise<SummarizationMeasurement>;
+    };
+    private readonly transport;
+    constructor(config: ResourceClientConfig);
+    private waitForSummary;
+    private waitForBatch;
+}
+declare class GatewayResource {
+    readonly chat: {
+        completions: {
+            create: <T extends GatewayChatCompletion = GatewayChatCompletion>(params: GatewayChatCompletionCreateParams, options?: ResourceRequestOptions) => Promise<T>;
+        };
+    };
+    readonly models: {
+        list: (options?: ResourceRequestOptions) => Promise<GatewayModelList>;
+    };
+    readonly batches: {
+        create: (params: GatewayBatchCreateParams, options?: ResourceRequestOptions) => Promise<GatewayBatch>;
+        retrieve: (batchId: string, options?: ResourceRequestOptions) => Promise<GatewayBatch>;
+        wait: (batch: string | GatewayBatch, options?: WaitOptions) => Promise<GatewayBatch>;
+        cancel: (batchId: string, options?: ResourceRequestOptions) => Promise<GatewayBatch>;
+        results: (batchId: string, options?: ResourceRequestOptions) => Promise<GatewayBatchResult[]>;
+    };
+    private readonly transport;
+    private readonly idempotencyGenerator;
+    constructor(config: ResourceClientConfig);
+    private waitForBatch;
+}
+
+type UsageTapCompressOptions = Omit<PromptCompressionStandaloneOptions, "provider">;
+type UsageTapCompressResult = Omit<PromptCompressionResult<string>, "compressedInput"> & {
+    /** The compressed text, ready to pass to an LLM. */
+    output: string;
+    /** Alias retained for consistency with the lower-level compression APIs. */
+    compressedInput: string;
+};
+type MeterRequest = string | BeginCallRequest;
+declare class UsageTapClient {
+    /** OpenAI-compatible chat, model, and native batch operations. */
+    readonly gateway: GatewayResource;
+    /** Published-profile context summarization operations. */
+    readonly summarization: SummarizationResource;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly defaultFeature?;
+    private readonly defaultTags?;
+    private readonly defaultHeaders;
+    private readonly retryDefaults;
+    private readonly idempotencyGenerator;
+    private readonly logFn?;
+    private readonly metricFn?;
+    private readonly authHeader;
+    private readonly autoIdempotency;
+    private readonly tokenCompanyApiKey?;
+    private readonly tokenCompanyEndpoint?;
+    private readonly model?;
+    private readonly tokenCompanyModel?;
+    private readonly aggressiveness?;
+    private readonly tokenCompanyAggressiveness?;
+    private readonly tokenCompanyAppId?;
+    private readonly usageTapCompressionApiKey?;
+    private readonly usageTapCompressionEndpoint?;
+    private readonly usageTapCompressionMessagesEndpoint?;
+    private readonly usageTapCompressionModel?;
+    private readonly usageTapCompressionAggressiveness?;
+    private readonly sampling?;
+    private readonly samplingSettingsCacheMs;
+    private readonly circuitBreaker?;
+    private readonly circuitBreakerRuns;
+    private samplingSettingsCache?;
+    constructor(options?: UsageTapClientOptions);
+    shouldSample(request: SamplingDecisionInput, policy?: SamplingOptions | undefined): boolean;
+    getSamplingSettings(options?: GetSamplingSettingsOptions): Promise<UsageTapSuccessResponse<SamplingSettings>>;
+    shouldSampleAsync(request: SamplingDecisionInput, policy?: SamplingOptions): Promise<boolean>;
+    decideSample(request: SamplingDecisionRequest, options?: SamplingDecisionOptions): Promise<UsageTapSuccessResponse<SamplingDecisionResponseBody>>;
+    captureSample(request: CaptureSampleRequest, options?: CaptureSampleOptions): Promise<UsageTapSuccessResponse<CaptureSampleResponseBody>>;
+    beginCall(request: BeginCallRequest, options?: BeginCallOptions): Promise<UsageTapSuccessResponse<BeginCallResponseBody>>;
+    /**
+     * Inspect a configured run circuit breaker without consuming another call.
+     */
+    canRunContinue(request: Pick<BeginCallRequest, "customerId" | "runId">): CircuitBreakerDecision;
+    /**
+     * Release local state after a workflow finishes. Returns true when state existed.
+     */
+    resetRun(request: Pick<BeginCallRequest, "customerId" | "runId">): boolean;
+    promptCompress(request: PromptCompressionRequest, options?: PromptCompressionOptions): Promise<PromptCompressionResult & {
+        callId: string;
+    }>;
+    compressPromptInput<TInput = unknown>(input: TInput, options?: PromptCompressionStandaloneOptions): Promise<PromptCompressionResult<TInput>>;
+    /**
+     * Compress text with UsageTap's hosted compression service.
+     *
+     * This is the short, standalone path. It does not create a metered call and
+     * fails open to the original text unless failOpen is explicitly disabled.
+     */
+    compress(text: string, options?: UsageTapCompressOptions): Promise<UsageTapCompressResult>;
+    compressPromptMessages<TInput = unknown>(input: TInput, options?: PromptCompressionMessagesOptions): Promise<PromptCompressionResult<TInput>>;
+    recordPromptCompression(request: RecordPromptCompressionRequest, options?: PromptCompressionOptions): Promise<UsageTapSuccessResponse<PromptCompressionResponseBody>>;
+    endCall(request: EndCallRequest, options?: EndCallOptions): Promise<UsageTapSuccessResponse<EndCallResponseBody>>;
+    checkUsage(request: CheckUsageRequest, options?: CheckUsageOptions): Promise<UsageTapSuccessResponse<CheckUsageResponseBody>>;
+    createCustomer(request: CreateCustomerRequest, options?: CreateCustomerOptions): Promise<UsageTapSuccessResponse<CreateCustomerResponseBody>>;
+    changePlan(request: ChangePlanRequest, options?: ChangePlanOptions): Promise<UsageTapSuccessResponse<ChangePlanResponseBody>>;
+    incrementCustomMeter(request: IncrementCustomMeterRequest, options?: IncrementCustomMeterOptions): Promise<UsageTapSuccessResponse<IncrementCustomMeterResponseBody>>;
+    withUsage<T>(beginRequest: BeginCallRequest, handler: (context: WithUsageContext) => Promise<T>, options?: WithUsageOptions): Promise<T>;
+    /**
+     * Meter one operation. Pass only a customer ID for the common path, or the
+     * existing begin-call request object when feature, tags, or entitlements are needed.
+     */
+    meter<T>(request: MeterRequest, handler: (context: WithUsageContext) => Promise<T>, options?: WithUsageOptions): Promise<T>;
+    private toPromptCompressionTelemetry;
+    private reserveRunCall;
+    private resolveRunIdentity;
+    private createCircuitBreakerDecision;
+    private expireInactiveRuns;
+    private request;
+    private requestGet;
+    private performFetch;
+    private composeHeaders;
+    private log;
+    private emitUsageMetric;
+    private mergeTags;
+    private shouldRetry;
+    private toHttpError;
+    private toApiError;
+}
+
+export { type PromptCompressionResponseBody as $, compressPrompt as A, type BeginCallRequest as B, compressPromptMessages as C, compressPromptHeuristic as D, type EndCallRequest as E, compressPromptToon as F, type GatewayBatch as G, estimatePromptTokens as H, protect as I, protectPromptText as J, type PromptCompressionInput as K, type PromptCompressionMessagesAggressiveness as L, type MeterRequest as M, type PromptCompressionMessagesInput as N, type PromptCompressionMessageRole as O, type PromptCompressionProvider as P, type PromptCompressionResult as Q, type ResourceRequestOptions as R, type SamplingOptions as S, type PromptCompressionRoleAggressiveness as T, UsageTapClient as U, type VendorHints as V, type WithUsageOptions as W, type BeginCallOptions as X, type PromptCompressionRequest as Y, type PromptCompressionOptions as Z, type PromptCompressionMessagesOptions as _, type PromptCompressionMode as a, type PromptCompressionStandaloneOptions as a0, type RecordPromptCompressionRequest as a1, type CreateCustomerOptions as a2, type CreateCustomerRequest as a3, type CreateCustomerResponseBody as a4, type CheckUsageOptions as a5, type CheckUsageRequest as a6, type CheckUsageResponseBody as a7, type ChangePlanOptions as a8, type ChangePlanRequest as a9, type UsageTapClientOptions as aA, type UsageTapErrorResponse as aB, type UsageTapResultEnvelope as aC, type UsageTapResultStatus as aD, type UsageTapLogEntry as aE, type WithUsageContext as aF, type LimitType as aG, type SubscriptionSnapshot as aH, type ModelHints as aI, type IdempotencyMetadata as aJ, type UsageMetricEvent as aK, type SamplingDecisionInput as aL, type CaptureSampleRequest as aM, type CaptureSampleOptions as aN, type CaptureSampleResponseBody as aO, type SamplingSettings as aP, type GetSamplingSettingsOptions as aQ, type SamplingDecisionRequest as aR, type SamplingDecisionResponseBody as aS, type SamplingDecisionOptions as aT, type CircuitBreakerOptions as aU, type CircuitBreakerDecision as aV, type ChangePlanResponseBody as aa, type ChangePlanStrategy as ab, type IncrementCustomMeterOptions as ac, type IncrementCustomMeterRequest as ad, type IncrementCustomMeterResponseBody as ae, type CustomMeterSlot as af, type EndCallOptions as ag, type EndCallResponseBody as ah, type BalanceSummary as ai, type SpendVelocitySnapshot as aj, type SpendVelocityWindow as ak, type SpendVelocityWindowKey as al, type EntitlementHints as am, type PlanSummary as an, type MeterSummary as ao, type MeterSnapshot as ap, type MeteredUsage as aq, type RateLimitsSnapshot as ar, type RemainingRatios as as, type RollingCallsRateLimitState as at, type RequestedEntitlements as au, type AllowedEntitlements as av, type ReasoningLevel as aw, type ReasoningEffort as ax, type ReasoningEffortSource as ay, type RetryOptions as az, type PromptCompressionTelemetry as b, type UsageTapSuccessResponse as c, type BeginCallResponseBody as d, type UsageTapCompressOptions as e, type UsageTapCompressResult as f, type GatewayBatchCreateParams as g, type GatewayBatchRequest as h, type GatewayBatchResult as i, type GatewayBatchStatus as j, type GatewayChatCompletion as k, type GatewayChatCompletionCreateParams as l, type GatewayChatMessage as m, type GatewayModel as n, type GatewayModelList as o, type SummarizationBatch as p, type SummarizationBatchCreateParams as q, type SummarizationBatchJob as r, type SummarizationContext as s, type SummarizationCreateParams as t, type SummarizationJob as u, type SummarizationMeasurement as v, type SummarizationMeasurementCreateParams as w, type SummarizationProfile as x, type SummarizationStatus as y, type WaitOptions as z };