@usagetap/sdk 0.1.0

package/dist/openai-CKyw08rB.d.cts

@@ -0,0 +1,398 @@
+import OpenAI from 'openai';
+
+type ReasoningLevel = "NONE" | "LOW" | "MEDIUM" | "HIGH";
+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 {
+    remaining: number | null;
+    limit: number | null;
+    used: number | null;
+    unlimited: boolean;
+    ratio: number | null;
+}
+type MeterSnapshot = Record<string, MeterSummary>;
+type RemainingRatios = Record<string, number | null | undefined>;
+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 BeginCallRequest {
+    customerId: string;
+    requested?: RequestedEntitlements;
+    feature?: string;
+    tags?: string[];
+    idempotency?: string;
+    customerName?: string;
+    customerEmail?: string;
+    stripeCustomerId?: string;
+}
+interface BalanceSummary {
+    standardCallsRemaining?: number;
+    premiumCallsRemaining?: number;
+    tokensRemaining?: number;
+    searchesRemaining?: number;
+    audioSecondsRemaining?: number;
+}
+interface PlanSummary {
+    id: string | null;
+    name: string | null;
+    version: string | null;
+}
+interface BeginCallResponseBody {
+    callId: string;
+    startTime: string;
+    feature?: string;
+    tags?: string[];
+    newCustomer: boolean;
+    canceled: boolean;
+    policy: LimitType;
+    allowed: AllowedEntitlements;
+    entitlementHints: EntitlementHints;
+    meters: MeterSnapshot;
+    remainingRatios: RemainingRatios;
+    subscription: SubscriptionSnapshot;
+    models?: ModelHints;
+    idempotency?: IdempotencyMetadata;
+    vendorHints?: VendorHints;
+    plan?: PlanSummary;
+    balances?: BalanceSummary;
+    stripeCustomerId?: string | null;
+}
+interface EndCallRequest {
+    callId: string;
+    modelUsed?: string;
+    inputTokens?: number;
+    responseTokens?: number;
+    cachedTokens?: number;
+    reasoningTokens?: number;
+    searches?: number;
+    audio?: number;
+    audioSeconds?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+    stripeCustomerId?: string;
+}
+interface MeteredUsage {
+    calls?: number;
+    tokens?: number;
+    reasoningTokens?: number;
+    searches?: number;
+    audio?: number;
+    audioSeconds?: number;
+}
+interface EndCallResponseBody {
+    callId: string;
+    costUSD: number;
+    metered?: MeteredUsage;
+    balances?: BalanceSummary;
+    stripeCustomerId?: string | null;
+}
+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 {
+    apiKey: string;
+    baseUrl: 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;
+    /**
+     * 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;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    retries?: RetryOptions;
+}
+interface BeginCallOptions extends RequestOptions {
+    correlationId?: string;
+}
+interface EndCallOptions extends RequestOptions {
+    correlationId?: string;
+}
+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;
+}
+
+declare class UsageTapClient {
+    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 authHeader;
+    private readonly autoIdempotency;
+    constructor(options: UsageTapClientOptions);
+    beginCall(request: BeginCallRequest, options?: BeginCallOptions): Promise<UsageTapSuccessResponse<BeginCallResponseBody>>;
+    endCall(request: EndCallRequest, options?: EndCallOptions): Promise<UsageTapSuccessResponse<EndCallResponseBody>>;
+    withUsage<T>(beginRequest: BeginCallRequest, handler: (context: WithUsageContext) => Promise<T>, options?: WithUsageOptions): Promise<T>;
+    private request;
+    private performFetch;
+    private composeHeaders;
+    private log;
+    private mergeTags;
+    private shouldRetry;
+    private toHttpError;
+    private toApiError;
+}
+
+interface OpenAIAdapterInit {
+    client: OpenAI;
+    usageTap: UsageTapClient;
+}
+interface OpenAIRequestContext {
+    hints?: VendorHints;
+    begin: UsageTapSuccessResponse<BeginCallResponseBody>;
+}
+interface OpenAIInvokeParams<TResponse> {
+    begin: BeginCallRequest;
+    call: (client: OpenAI, ctx: OpenAIRequestContext) => Promise<TResponse>;
+    extractUsage?: (response: TResponse) => Partial<Omit<EndCallRequest, "callId" | "error">> | void;
+    withUsageOptions?: WithUsageOptions;
+}
+interface OpenAIInvokeResult<TResponse> {
+    data: TResponse;
+    begin: UsageTapSuccessResponse<BeginCallResponseBody>;
+}
+interface OpenAIStreamCallResult<TStream> {
+    stream: AsyncIterable<TStream>;
+    onComplete?: () => Promise<Partial<Omit<EndCallRequest, "callId" | "error">> | void> | Partial<Omit<EndCallRequest, "callId" | "error">> | void;
+}
+interface OpenAIStreamParams<TStream> {
+    begin: BeginCallRequest;
+    call: (client: OpenAI, ctx: OpenAIRequestContext) => Promise<OpenAIStreamCallResult<TStream>>;
+    withUsageOptions?: WithUsageOptions;
+}
+interface OpenAIStreamResult<TStream> {
+    stream: AsyncIterable<TStream> & {
+        __usageTapFinalize?: () => Promise<void>;
+    };
+    begin: UsageTapSuccessResponse<BeginCallResponseBody>;
+    finalize: () => Promise<void>;
+}
+interface OpenAIAdapter {
+    invoke<TResponse>(params: OpenAIInvokeParams<TResponse>): Promise<OpenAIInvokeResult<TResponse>>;
+    invokeStream<TStream>(params: OpenAIStreamParams<TStream>): Promise<OpenAIStreamResult<TStream>>;
+}
+type ReplaceProperty<T, K extends keyof T, V> = Omit<T, K> & Record<K, V>;
+type WrapOpenAIContext = BeginCallRequest;
+interface WrapOpenAIOptions {
+    defaultContext?: Partial<WrapOpenAIContext>;
+    applyVendorHints?: boolean;
+}
+type ChatCompletionsResource = OpenAI["chat"]["completions"];
+type ChatCompletionCreate = ChatCompletionsResource["create"];
+type ChatCompletionCreateParams = Parameters<ChatCompletionCreate>[0];
+type ChatCompletionCreateOptions = Parameters<ChatCompletionCreate>[1];
+type ChatCompletionCreateReturn = ReturnType<ChatCompletionCreate>;
+type WrapOpenAICallOptions = (ChatCompletionCreateOptions extends undefined ? {
+    usageTap?: Partial<WrapOpenAIContext>;
+    withUsage?: WithUsageOptions;
+} : ChatCompletionCreateOptions & {
+    usageTap?: Partial<WrapOpenAIContext>;
+    withUsage?: WithUsageOptions;
+});
+interface WrappedChatCompletions extends Omit<ChatCompletionsResource, "create"> {
+    create: (params: ChatCompletionCreateParams, options?: WrapOpenAICallOptions) => ChatCompletionCreateReturn;
+}
+type ResponsesResource = OpenAI extends {
+    responses: infer R;
+} ? R : never;
+type ResponsesCreate = ResponsesResource extends {
+    create: infer T;
+} ? T : never;
+type ResponsesCreateParams = ResponsesCreate extends (...args: infer P) => unknown ? P[0] : never;
+type ResponsesCreateOptions = ResponsesCreate extends (...args: infer P) => unknown ? P[1] : never;
+type ResponsesCreateReturn = ResponsesCreate extends (...args: unknown[]) => infer R ? R : never;
+type WrapOpenAIResponseCallOptions = (ResponsesCreateOptions extends undefined ? {
+    usageTap?: Partial<WrapOpenAIContext>;
+    withUsage?: WithUsageOptions;
+} : ResponsesCreateOptions & {
+    usageTap?: Partial<WrapOpenAIContext>;
+    withUsage?: WithUsageOptions;
+});
+type WrappedResponses = ResponsesResource extends undefined ? undefined : Omit<NonNullable<ResponsesResource>, "create"> & {
+    create: (params: ResponsesCreateParams, options?: WrapOpenAIResponseCallOptions) => ResponsesCreateReturn;
+};
+type WrappedOpenAI = OpenAI & {
+    chat: ReplaceProperty<OpenAI["chat"], "completions", WrappedChatCompletions>;
+} & (ResponsesResource extends undefined ? {
+    responses?: undefined;
+} : {
+    responses: WrappedResponses;
+}) & {
+    toNextResponse: typeof toNextResponse;
+    pipeToResponse: typeof pipeToResponse;
+    unwrap: () => OpenAI;
+};
+interface StreamOpenAIRouteOptions {
+    getRequest: (req: Request) => Promise<{
+        params: ChatCompletionCreateParams;
+        usageTap?: Partial<WrapOpenAIContext>;
+        withUsage?: WithUsageOptions;
+    }>;
+    wrapOptions?: WrapOpenAIOptions;
+    defaultContext?: Partial<WrapOpenAIContext>;
+    stream?: {
+        mode?: StreamMode;
+        headers?: Record<string, string>;
+        responseInit?: ResponseInit;
+    };
+}
+type StreamMode = "text" | "sse";
+interface StreamToResponseOptions {
+    mode?: StreamMode;
+    headers?: Record<string, string>;
+    contentType?: string;
+    sse?: {
+        event?: string;
+        retry?: number;
+    };
+}
+declare function createOpenAIAdapter(init: OpenAIAdapterInit): OpenAIAdapter;
+type UsageTapStream<T> = AsyncIterable<T> & {
+    __usageTapFinalize?: () => Promise<void>;
+};
+declare function toNextResponse<T>(stream: UsageTapStream<T>, options?: StreamToResponseOptions): Response;
+declare function pipeToResponse<T>(stream: UsageTapStream<T>, res: NodeResponseLike, options?: StreamToResponseOptions): Promise<void>;
+declare function wrapOpenAI(client: OpenAI, usageTap: UsageTapClient, options?: WrapOpenAIOptions): WrappedOpenAI;
+declare function streamOpenAIRoute(usageTap: UsageTapClient, openai: OpenAI, options: StreamOpenAIRouteOptions): (req: Request) => Promise<Response>;
+interface NodeResponseLike {
+    write(chunk: string | Uint8Array | Buffer): unknown;
+    end(chunk?: string | Uint8Array | Buffer): unknown;
+    setHeader?(name: string, value: string): void;
+    headersSent?: boolean;
+    statusCode?: number;
+    status?(code: number): void;
+    flush?(): void;
+}
+
+export { type AllowedEntitlements as A, type BeginCallRequest as B, type UsageTapClientOptions as C, type UsageTapSuccessResponse as D, type EndCallOptions as E, type UsageTapErrorResponse as F, type UsageTapResultEnvelope as G, type UsageTapResultStatus as H, type UsageTapLogEntry as I, type WithUsageContext as J, type WithUsageOptions as K, type LimitType as L, type MeterSummary as M, type NodeResponseLike as N, type OpenAIAdapter as O, type PlanSummary as P, type SubscriptionSnapshot as Q, type RemainingRatios as R, type StreamMode as S, type ModelHints as T, UsageTapClient as U, type VendorHints as V, type WrapOpenAIContext as W, type IdempotencyMetadata as X, type OpenAIRequestContext as Y, type OpenAIStreamCallResult as Z, type UsageTapStream as _, type WrapOpenAIOptions as a, type OpenAIAdapterInit as b, createOpenAIAdapter as c, type OpenAIInvokeParams as d, type OpenAIInvokeResult as e, type OpenAIStreamParams as f, type OpenAIStreamResult as g, type StreamToResponseOptions as h, type WrapOpenAICallOptions as i, type WrapOpenAIResponseCallOptions as j, type WrappedOpenAI as k, type StreamOpenAIRouteOptions as l, type BeginCallOptions as m, type BeginCallResponseBody as n, type EndCallRequest as o, pipeToResponse as p, type EndCallResponseBody as q, type BalanceSummary as r, streamOpenAIRoute as s, toNextResponse as t, type EntitlementHints as u, type MeterSnapshot as v, wrapOpenAI as w, type MeteredUsage as x, type RequestedEntitlements as y, type RetryOptions as z };