@zorveus/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,919 @@
+interface ZorveusInferenceClientOptions {
+    /**
+     * API Key used for gateway inference.
+     * Accepts an Inference Key (`zrv_...`) or an API Key issued via OAuth code exchange (`access_token`).
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Zorveus API Control Plane.
+     * @default "https://api.zorveus.com"
+     */
+    baseURL?: string;
+    /**
+     * Base URL for the Zorveus Inference Gateway (Data Plane).
+     * @default "https://api.zorveus.com/v1"
+     */
+    gatewayBaseURL?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 60000 (60 seconds)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of request retries on rate limits (429) or transient 5xx errors for idempotent operations.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Default headers merged into every outgoing HTTP request.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Optional custom fetch implementation (defaults to globalThis.fetch).
+     */
+    fetch?: typeof globalThis.fetch;
+}
+interface ZorveusServiceClientOptions {
+    /**
+     * Organization Service Key used for server-side management authentication (`zrv_service_...`).
+     * WARNING: Never expose this key in browser client applications.
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Zorveus Management Control Plane API.
+     * @default "https://api.zorveus.com"
+     */
+    baseURL?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 60000 (60 seconds)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of request retries for idempotent operations.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Default headers merged into every outgoing HTTP request.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Optional custom fetch implementation.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+type ZorveusClientOptions = ZorveusInferenceClientOptions;
+interface RequestOptions {
+    /**
+     * Request timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom headers for this specific request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Maximum retries for this specific request.
+     */
+    maxRetries?: number;
+    /**
+     * Explicitly mark non-GET request as idempotent to enable automatic retries.
+     */
+    isIdempotent?: boolean;
+    /**
+     * Optional Idempotency key header.
+     */
+    idempotencyKey?: string;
+    /**
+     * AbortSignal for external request cancellation.
+     */
+    signal?: AbortSignal;
+}
+interface InferenceKeyUsageResponse {
+    status: "active" | "inactive" | "suspended" | string;
+    app_id: string | null;
+    app_connection_id: string | null;
+    currency: string;
+    period: "daily" | "weekly" | "monthly" | "lifetime" | string;
+    spend_cap: string | null;
+    spent_this_period: string;
+    remaining_balance: string | null;
+    reset_at: string | null;
+}
+
+interface HttpRequestOptions extends RequestOptions {
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    body?: unknown;
+    query?: Record<string, unknown>;
+    isGateway?: boolean;
+    stream?: boolean;
+}
+declare class HTTPTransport {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly gatewayBaseURL: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly defaultHeaders: Record<string, string>;
+    readonly fetchFn: typeof globalThis.fetch;
+    constructor(options: {
+        apiKey: string;
+        baseURL?: string;
+        gatewayBaseURL?: string;
+        timeout?: number;
+        maxRetries?: number;
+        defaultHeaders?: Record<string, string>;
+        fetch?: typeof globalThis.fetch;
+    });
+    /**
+     * Executes an HTTP request with timeout, strict idempotency-aware retries, and error mapping.
+     */
+    request<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    private buildUrl;
+    private parseResponseBody;
+    private extractHeaders;
+    private shouldRetryStatus;
+    private calculateRetryDelay;
+    private sleep;
+}
+
+type ChatCompletionRole = "system" | "user" | "assistant" | "tool" | "function";
+interface ChatMessageToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ChatMessage {
+    role: ChatCompletionRole;
+    content: string | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ChatMessageToolCall[];
+}
+interface ChatCompletionTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+interface ZorveusMetadata {
+    /**
+     * The startup's external customer ID (e.g. "usr_ext_8842").
+     */
+    externalUserId?: string;
+    /**
+     * Customer's display name.
+     */
+    displayName?: string;
+    /**
+     * Customer's email.
+     */
+    userEmail?: string;
+    /**
+     * Custom metadata key-value pairs (e.g. `{ plan: "pro", teamId: "team_402" }`).
+     */
+    metadata?: Record<string, unknown>;
+}
+interface ZorveusGatewayProductUserMetadata {
+    display_name?: string | null;
+    email?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface ZorveusGatewayMetadata {
+    external_user_id?: string;
+    product_user?: ZorveusGatewayProductUserMetadata;
+}
+/**
+ * Formats SDK metadata into Gateway request body contract format.
+ */
+declare function formatGatewayMetadata(meta?: ZorveusMetadata): ZorveusGatewayMetadata | undefined;
+interface ChatCompletionCreateParamsBase {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    n?: number;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    logit_bias?: Record<string, number>;
+    user?: string;
+    tools?: ChatCompletionTool[];
+    tool_choice?: "none" | "auto" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    response_format?: {
+        type: "text" | "json_object" | "json_schema";
+        json_schema?: Record<string, unknown>;
+    };
+    seed?: number;
+    /**
+     * Inline Zorveus product-user metadata attribution.
+     */
+    zorveusMetadata?: ZorveusMetadata;
+    /**
+     * Gateway request body metadata payload override.
+     */
+    metadata?: Record<string, unknown>;
+}
+interface ChatCompletionCreateParamsNonStreaming extends ChatCompletionCreateParamsBase {
+    stream?: false;
+}
+interface ChatCompletionCreateParamsStreaming extends ChatCompletionCreateParamsBase {
+    stream: true;
+}
+type ChatCompletionCreateParams = ChatCompletionCreateParamsNonStreaming | ChatCompletionCreateParamsStreaming;
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | null;
+    logprobs?: unknown;
+}
+interface ChatCompletionChunkChoiceDelta {
+    role?: ChatCompletionRole;
+    content?: string | null;
+    tool_calls?: Array<{
+        index: number;
+        id?: string;
+        type?: "function";
+        function?: {
+            name?: string;
+            arguments?: string;
+        };
+    }>;
+}
+interface ChatCompletionChunkChoice {
+    index: number;
+    delta: ChatCompletionChunkChoiceDelta;
+    finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | null;
+    logprobs?: unknown;
+}
+interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
+interface ChatCompletion {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: ChatCompletionUsage;
+    system_fingerprint?: string;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+    usage?: ChatCompletionUsage;
+    system_fingerprint?: string;
+}
+
+declare class Completions {
+    private readonly transport;
+    constructor(transport: HTTPTransport);
+    /**
+     * Creates a model response for the given chat conversation.
+     * Supports standard single-response and Server-Sent Events (SSE) streaming modes.
+     */
+    create(params: ChatCompletionCreateParamsStreaming, options?: RequestOptions): Promise<AsyncIterableIterator<ChatCompletionChunk>>;
+    create(params: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParams, options?: RequestOptions): Promise<ChatCompletion | AsyncIterableIterator<ChatCompletionChunk>>;
+}
+
+declare class Chat {
+    readonly completions: Completions;
+    constructor(transport: HTTPTransport);
+}
+
+interface EmbeddingCreateParams {
+    model: string;
+    input: string | string[] | number[] | number[][];
+    encoding_format?: "float" | "base64";
+    dimensions?: number;
+    user?: string;
+    /**
+     * Inline Zorveus product-user metadata attribution.
+     */
+    zorveusMetadata?: ZorveusMetadata;
+}
+interface EmbeddingData {
+    index: number;
+    object: "embedding";
+    embedding: number[];
+}
+interface EmbeddingUsage {
+    prompt_tokens: number;
+    total_tokens: number;
+}
+interface EmbeddingCreateResponse {
+    object: "list";
+    data: EmbeddingData[];
+    model: string;
+    usage: EmbeddingUsage;
+}
+
+interface Model {
+    id: string;
+    object: "model";
+    created: number;
+    owned_by: string;
+    provider?: string;
+    mode?: string;
+    max_input_tokens?: number;
+    max_output_tokens?: number;
+    route_status?: "available" | "degraded" | "unavailable";
+}
+interface ModelListParams {
+    routeStatus?: "available" | "degraded" | "unavailable";
+}
+interface ModelListResponse {
+    object: "list";
+    data: Model[];
+}
+
+type ProductUserStatus = "active" | "suspended";
+interface ProductUserCapResponse {
+    source: string;
+    cap_rule_id: string;
+    amount: string;
+    currency: string;
+    period: "daily" | "weekly" | "monthly" | "lifetime" | string;
+    spent_this_period: string;
+    reset_at: string | null;
+    status: string;
+    updated_at: string;
+}
+interface ProductUserUsageMetrics {
+    sell_cost: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    request_count: number;
+}
+interface ProductUserUsageSummary {
+    this_month: ProductUserUsageMetrics;
+    total: ProductUserUsageMetrics;
+}
+interface ProductUserCreditSummaryResponse {
+    currency: string;
+    available_credits: string;
+    active_grant_count: number;
+    expiring_soon_amount: string;
+    spent_this_month: string;
+    spent_total: string;
+    last_grant_at?: string | null;
+    last_used_at?: string | null;
+    product_end_user_id?: string;
+    total_granted?: string;
+    total_remaining?: string;
+    active_grants_count?: number;
+}
+interface ProductUserResponse {
+    product_end_user_id: string;
+    org_id: string;
+    app_id: string;
+    external_user_id: string;
+    display_name: string | null;
+    email_hash: string | null;
+    status: ProductUserStatus;
+    metadata: Record<string, unknown> | null;
+    usage?: ProductUserUsageSummary | Record<string, unknown>;
+    cap?: ProductUserCapResponse | null;
+    credits?: ProductUserCreditSummaryResponse | null;
+}
+type ProductUser = ProductUserResponse;
+interface UpsertProductUserResponse {
+    product_user: ProductUserResponse;
+    created: boolean;
+}
+interface ProductUserListResponse {
+    product_users: ProductUserResponse[];
+}
+interface UpsertProductUserParams {
+    orgId?: string;
+    appId?: string;
+    externalUserId: string;
+    displayName?: string | null;
+    email?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface GetProductUserByExternalIdParams {
+    appId: string;
+    externalUserId: string;
+    orgId?: string;
+}
+interface GetProductUserCreditSummaryByExternalIdParams {
+    appId: string;
+    externalUserId: string;
+    currency?: string;
+    orgId?: string;
+}
+type CreditGrantStatus = "active" | "exhausted" | "expired" | "revoked";
+type CreditGrantSource = "admin_adjustment" | "service_key" | "purchase" | "promotion" | "monthly_allowance" | "support_credit" | "import" | (string & {});
+interface ProductUserCreditGrantResponse {
+    credit_grant_id: string;
+    org_id: string;
+    app_id: string;
+    product_end_user_id: string;
+    amount: string;
+    remaining_amount: string;
+    currency: string;
+    source: string;
+    reason: string | null;
+    status: CreditGrantStatus;
+    expires_at: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+}
+type CreditGrant = ProductUserCreditGrantResponse;
+interface GrantProductUserCreditsResponse {
+    product_user: ProductUserResponse;
+    credit_grant: ProductUserCreditGrantResponse;
+    credit_summary: ProductUserCreditSummaryResponse;
+}
+interface ProductUserCreditGrantListResponse {
+    credit_grants: ProductUserCreditGrantResponse[];
+}
+interface RevokeProductUserCreditGrantResponse {
+    credit_grant: ProductUserCreditGrantResponse;
+    credit_summary: ProductUserCreditSummaryResponse;
+    revoked: boolean;
+}
+interface GrantCreditParams {
+    orgId?: string;
+    appId?: string;
+    amount: string;
+    currency?: string;
+    reason?: string | null;
+    expiresAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface GrantCreditByExternalIdParams {
+    appId: string;
+    externalUserId: string;
+    amount: string;
+    displayName?: string | null;
+    email?: string | null;
+    currency?: string;
+    source?: CreditGrantSource;
+    reason?: string | null;
+    expiresAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+    orgId?: string;
+}
+interface ListCreditGrantsParams {
+    appId?: string;
+    orgId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListCreditGrantsByExternalIdParams {
+    appId: string;
+    externalUserId: string;
+    status?: CreditGrantStatus;
+    source?: CreditGrantSource;
+    limit?: number;
+    orgId?: string;
+}
+interface ProductUserListParams {
+    orgId?: string;
+    limit?: number;
+    offset?: number;
+}
+
+type ProviderCredentialStatus = "active" | "disabled" | "invalid";
+type ProviderCredentialRoutingMode = "auto_resolve" | "manual";
+type ProviderCredentialSecretKind = "api_key" | "service_account" | "oauth_token";
+interface ProviderCredentialResponse {
+    provider_credential_id: string;
+    org_id: string;
+    provider: string;
+    credential_name: string;
+    status: ProviderCredentialStatus;
+    routing_mode: ProviderCredentialRoutingMode;
+    routing_priority: number;
+    default_model_policy: string[];
+    provider_config: Record<string, unknown> | null;
+    active_secret_version_id: string | null;
+    secret_fingerprint: string | null;
+    last_validated_at: string | null;
+    last_used_at: string | null;
+}
+type ProviderCredential = ProviderCredentialResponse;
+interface ProviderCredentialListResponse {
+    provider_credentials: ProviderCredentialResponse[];
+}
+interface RotateProviderCredentialResponse {
+    provider_credential: ProviderCredentialResponse;
+    rotated: boolean;
+}
+interface ProviderCredentialProviderInfo {
+    provider: string;
+    display_name: string;
+    supported_auth_types: string[];
+    docs_url?: string;
+}
+interface ProviderCredentialProviderCatalogResponse {
+    providers: ProviderCredentialProviderInfo[];
+}
+interface CreateProviderCredentialParams {
+    orgId?: string;
+    provider: string;
+    credentialName: string;
+    apiKey: string;
+    secretKind?: ProviderCredentialSecretKind;
+    modelPolicies?: string[];
+    providerConfig?: Record<string, unknown> | null;
+    routingMode?: ProviderCredentialRoutingMode;
+    routingPriority?: number;
+}
+interface RotateProviderCredentialParams {
+    orgId?: string;
+    apiKey: string;
+    secretKind?: ProviderCredentialSecretKind;
+}
+interface ListProviderCredentialsParams {
+    orgId?: string;
+    status?: string;
+}
+
+interface PKCEData {
+    /**
+     * High-entropy cryptographic random string (43-128 chars).
+     */
+    codeVerifier: string;
+    /**
+     * Base64URL-encoded SHA-256 hash of the code_verifier.
+     */
+    codeChallenge: string;
+    /**
+     * Cryptographically secure random state parameter for CSRF protection.
+     */
+    state: string;
+}
+interface AuthorizationUrlParams {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+    scopes?: string[] | string;
+    baseURL?: string;
+}
+interface TokenExchangeParams {
+    clientId: string;
+    clientSecret?: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+    baseURL?: string;
+}
+interface TokenRevocationParams {
+    token: string;
+    clientId?: string;
+    clientSecret?: string;
+    baseURL?: string;
+}
+interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number | null;
+    scope: string;
+    app_connection_id: string;
+    api_base: string;
+}
+interface CallbackValidationOptions {
+    urlOrParams: string | URLSearchParams | Record<string, string>;
+    expectedState?: string;
+}
+interface CallbackValidationResult {
+    valid: boolean;
+    code?: string;
+    state?: string;
+    error?: string;
+    errorDescription?: string;
+}
+
+declare class Embeddings {
+    private readonly transport;
+    constructor(transport: HTTPTransport);
+    /**
+     * Creates an embedding vector representing the input text.
+     */
+    create(params: EmbeddingCreateParams, options?: RequestOptions): Promise<EmbeddingCreateResponse>;
+}
+
+declare class Models {
+    private readonly transport;
+    constructor(transport: HTTPTransport);
+    /**
+     * Lists available models on the Zorveus gateway.
+     */
+    list(params?: ModelListParams, options?: RequestOptions): Promise<ModelListResponse>;
+    /**
+     * Retrieves information about a specific model.
+     */
+    retrieve(modelId: string, options?: RequestOptions): Promise<Model>;
+}
+
+/**
+ * Zorveus Inference Client (Gateway Data Plane).
+ * Authenticated via Inference Key (`zrv_...`) or API Key issued via OAuth (`access_token`).
+ */
+declare class ZorveusInferenceClient {
+    readonly chat: Chat;
+    readonly embeddings: Embeddings;
+    readonly models: Models;
+    protected readonly transport: HTTPTransport;
+    constructor(options: ZorveusInferenceClientOptions);
+    /**
+     * Retrieves live spend, budget cap, and balance for the active inference key (`GET /inference-keys/usage`).
+     */
+    getUsage(options?: RequestOptions): Promise<InferenceKeyUsageResponse>;
+}
+/**
+ * Primary Zorveus client class for gateway inference.
+ */
+declare class Zorveus extends ZorveusInferenceClient {
+}
+
+declare class ProductUsers {
+    private readonly transport;
+    constructor(transport: HTTPTransport);
+    /**
+     * Upserts a product user by external user ID (`PUT /product-users/by-external-id`).
+     * Creates the user if they do not exist, or updates their profile if they do.
+     */
+    createOrUpdate(params: UpsertProductUserParams, options?: RequestOptions): Promise<UpsertProductUserResponse>;
+    /**
+     * Alias for `createOrUpdate` (`PUT /product-users/by-external-id`).
+     */
+    upsert(params: UpsertProductUserParams, options?: RequestOptions): Promise<UpsertProductUserResponse>;
+    /**
+     * Retrieves a single product end-user by ID (`GET /product-users/{product_end_user_id}`).
+     */
+    get(productEndUserId: string, options?: RequestOptions): Promise<ProductUserResponse>;
+    /**
+     * Retrieves a product user profile by external ID (`GET /product-users/by-external-id`).
+     * Returns complete profile with usage, active cap, and live credits.
+     */
+    getByExternalId(params: GetProductUserByExternalIdParams, options?: RequestOptions): Promise<ProductUserResponse>;
+    /**
+     * Retrieves a product user's live credit summary by external ID (`GET /product-users/by-external-id/credit-summary`).
+     */
+    getCreditSummaryByExternalId(params: GetProductUserCreditSummaryByExternalIdParams, options?: RequestOptions): Promise<ProductUserCreditSummaryResponse>;
+    /**
+     * Lists product end-users for an organization (`GET /product-users`).
+     */
+    list(params?: ProductUserListParams, options?: RequestOptions): Promise<ProductUserListResponse>;
+    /**
+     * Grants startup-funded AI credits to a product user (`POST /product-users/{id}/credit-grants`).
+     * Validates amount as a strict financial decimal string.
+     */
+    grantCredit(productEndUserId: string, params: GrantCreditParams, options?: RequestOptions): Promise<GrantProductUserCreditsResponse>;
+    /**
+     * Grants credits to an end user by external ID (`POST /product-users/by-external-id/credit-grants`).
+     * Automatically provisions the product user if they do not exist yet.
+     */
+    grantCreditByExternalId(params: GrantCreditByExternalIdParams, options?: RequestOptions): Promise<GrantProductUserCreditsResponse>;
+    /**
+     * Lists credit grants for a product user (`GET /product-users/{id}/credit-grants`).
+     * Accepts either an external user ID or a Zorveus product user ID.
+     */
+    listCreditGrants(userIdentifier: string, params?: ListCreditGrantsParams, options?: RequestOptions): Promise<ProductUserCreditGrantListResponse>;
+    /**
+     * Lists credit grants for a product user by external ID (`GET /product-users/by-external-id/credit-grants`).
+     */
+    listCreditGrantsByExternalId(params: ListCreditGrantsByExternalIdParams, options?: RequestOptions): Promise<ProductUserCreditGrantListResponse>;
+    /**
+     * Revokes an active credit grant (`POST /product-users/{id}/credit-grants/{grantId}/revoke`).
+     */
+    revokeCredit(productEndUserId: string, creditGrantId: string, options?: RequestOptions): Promise<RevokeProductUserCreditGrantResponse>;
+}
+
+declare class ProviderCredentials {
+    private readonly transport;
+    constructor(transport: HTTPTransport);
+    /**
+     * Registers an organization BYOK provider credential via Service Key (`POST /provider-credentials/org-programmatic`).
+     */
+    create(params: CreateProviderCredentialParams, options?: RequestOptions): Promise<ProviderCredentialResponse>;
+    /**
+     * Lists BYOK provider credentials for an organization (`GET /provider-credentials/org-programmatic`).
+     */
+    list(params?: ListProviderCredentialsParams, options?: RequestOptions): Promise<ProviderCredentialListResponse>;
+    /**
+     * Rotates a provider credential secret (`POST /provider-credentials/org-programmatic/{id}/rotate`).
+     */
+    rotate(providerCredentialId: string, params: RotateProviderCredentialParams, options?: RequestOptions): Promise<RotateProviderCredentialResponse>;
+    /**
+     * Deletes a provider credential (`DELETE /provider-credentials/org-programmatic/{id}`).
+     */
+    delete(providerCredentialId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Lists supported AI provider catalog (`GET /provider-credentials/providers`).
+     */
+    listProviders(options?: RequestOptions): Promise<ProviderCredentialProviderCatalogResponse>;
+}
+
+/**
+ * Zorveus Service Client (Server-to-Server Management Control Plane).
+ * Authenticated via Organization Service Key (`zrv_service_...`).
+ * WARNING: Never export or use this client in browser applications.
+ */
+declare class ZorveusServiceClient {
+    readonly productUsers: ProductUsers;
+    readonly providerCredentials: ProviderCredentials;
+    protected readonly transport: HTTPTransport;
+    constructor(options: ZorveusServiceClientOptions);
+}
+
+/**
+ * Isomorphic OAuth PKCE and token management utilities for Zorveus.
+ */
+declare class ZorveusOAuth {
+    /**
+     * Generates an RFC 7636 PKCE code_verifier, code_challenge (S256), and CSRF state parameter.
+     */
+    static generatePKCE(byteLength?: number): Promise<PKCEData>;
+    /**
+     * Constructs the Zorveus OAuth PKCE consent URL.
+     */
+    static getAuthorizationUrl(params: AuthorizationUrlParams): string;
+    /**
+     * Validates OAuth redirect parameters against expected CSRF state.
+     */
+    static validateCallback(options: CallbackValidationOptions): CallbackValidationResult;
+    /**
+     * Exchanges an OAuth authorization code for a Zorveus inference key using application/x-www-form-urlencoded.
+     */
+    static exchangeToken(params: TokenExchangeParams): Promise<OAuthTokenResponse>;
+    /**
+     * Revokes an existing OAuth token or app connection using application/x-www-form-urlencoded.
+     */
+    static revokeToken(params: TokenRevocationParams): Promise<void>;
+}
+
+/**
+ * Base class for all Zorveus SDK errors.
+ */
+declare class ZorveusError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly param?: string;
+    readonly type?: string;
+    readonly headers?: Record<string, string>;
+    readonly rawBody?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        param?: string;
+        type?: string;
+        headers?: Record<string, string>;
+        rawBody?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an HTTP request fails before receiving a response (network drops, DNS failures, aborts/timeouts).
+ */
+declare class APIConnectionError extends ZorveusError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Base class for all HTTP 4xx and 5xx responses from the Zorveus API.
+ */
+declare class APIStatusError extends ZorveusError {
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        param?: string;
+        type?: string;
+        headers?: Record<string, string>;
+        rawBody?: unknown;
+    });
+}
+/**
+ * HTTP 401: Invalid or expired API key, Service key, or OAuth access token.
+ */
+declare class AuthenticationError extends APIStatusError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof APIStatusError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 403: Forbidden access, insufficient scope, or model not permitted.
+ */
+declare class PermissionDeniedError extends APIStatusError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof APIStatusError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 404: Requested resource (app, user, credential, model) was not found.
+ */
+declare class NotFoundError extends APIStatusError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof APIStatusError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 422: Request schema validation failure.
+ */
+declare class UnprocessableEntityError extends APIStatusError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof APIStatusError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 429: Rate limit exceeded or quota exhausted.
+ */
+declare class RateLimitError extends APIStatusError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof APIStatusError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 500, 502, 503, 504: Zorveus internal server or upstream gateway error.
+ */
+declare class InternalServerError extends APIStatusError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof APIStatusError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * Base class for Zorveus financial and business constraint errors.
+ */
+declare class ZorveusBusinessError extends APIStatusError {
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        param?: string;
+        type?: string;
+        headers?: Record<string, string>;
+        rawBody?: unknown;
+    });
+}
+/**
+ * HTTP 402: Organization or product-user wallet balance is exhausted.
+ */
+declare class InsufficientFundsError extends ZorveusBusinessError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof ZorveusBusinessError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 402/403: Monthly or daily spending cap reached for organization, app connection, or product user.
+ */
+declare class CapExceededError extends ZorveusBusinessError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof ZorveusBusinessError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * HTTP 403: Product user credit grant has expired.
+ */
+declare class CreditGrantExpiredError extends ZorveusBusinessError {
+    constructor(message?: string, options?: Omit<ConstructorParameters<typeof ZorveusBusinessError>[1], "status"> & {
+        status?: number;
+    });
+}
+/**
+ * Factory that parses HTTP status code and response payload into the most specific ZorveusError subclass.
+ */
+declare function createAPIError(status: number, body: unknown, headers?: Record<string, string>): APIStatusError;
+
+/**
+ * Validates that a monetary value is a valid decimal string (e.g., "15.0000").
+ * Financial safety rule: floating-point arithmetic is avoided for monetary amounts.
+ */
+declare function isValidDecimalString(value: unknown): value is string;
+/**
+ * Asserts that a given balance or monetary parameter is a valid decimal string.
+ */
+declare function assertDecimalString(value: unknown, fieldName: string): string;
+
+export { APIConnectionError, APIStatusError, AuthenticationError, type AuthorizationUrlParams, type CallbackValidationOptions, type CallbackValidationResult, CapExceededError, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionChunkChoice, type ChatCompletionChunkChoiceDelta, type ChatCompletionCreateParams, type ChatCompletionCreateParamsBase, type ChatCompletionCreateParamsNonStreaming, type ChatCompletionCreateParamsStreaming, type ChatCompletionRole, type ChatCompletionTool, type ChatCompletionUsage, type ChatMessage, type ChatMessageToolCall, type CreateProviderCredentialParams, type CreditGrant, CreditGrantExpiredError, type CreditGrantSource, type CreditGrantStatus, type EmbeddingCreateParams, type EmbeddingCreateResponse, type EmbeddingData, type EmbeddingUsage, type GetProductUserByExternalIdParams, type GetProductUserCreditSummaryByExternalIdParams, type GrantCreditByExternalIdParams, type GrantCreditParams, type GrantProductUserCreditsResponse, type InferenceKeyUsageResponse, InsufficientFundsError, InternalServerError, type ListCreditGrantsByExternalIdParams, type ListCreditGrantsParams, type ListProviderCredentialsParams, type Model, type ModelListParams, type ModelListResponse, NotFoundError, type OAuthTokenResponse, type PKCEData, PermissionDeniedError, type ProductUser, type ProductUserCapResponse, type ProductUserCreditGrantListResponse, type ProductUserCreditGrantResponse, type ProductUserCreditSummaryResponse, type ProductUserListParams, type ProductUserListResponse, type ProductUserResponse, type ProductUserStatus, type ProductUserUsageMetrics, type ProductUserUsageSummary, type ProviderCredential, type ProviderCredentialListResponse, type ProviderCredentialProviderCatalogResponse, type ProviderCredentialProviderInfo, type ProviderCredentialResponse, type ProviderCredentialRoutingMode, type ProviderCredentialSecretKind, type ProviderCredentialStatus, RateLimitError, type RequestOptions, type RevokeProductUserCreditGrantResponse, type RotateProviderCredentialParams, type RotateProviderCredentialResponse, type TokenExchangeParams, type TokenRevocationParams, UnprocessableEntityError, type UpsertProductUserParams, type UpsertProductUserResponse, Zorveus, ZorveusBusinessError, type ZorveusClientOptions, ZorveusError, type ZorveusGatewayMetadata, type ZorveusGatewayProductUserMetadata, ZorveusInferenceClient, type ZorveusInferenceClientOptions, type ZorveusMetadata, ZorveusOAuth, ZorveusServiceClient, type ZorveusServiceClientOptions, assertDecimalString, createAPIError, formatGatewayMetadata, isValidDecimalString };