@zorveus/sdk 0.1.8 → 0.2.1

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { U as UpsertProductUserParams, a as UpsertProductUserResponse, P as ProductUserResponse, G as GetProductUserByExternalIdParams, b as GetProductUserCreditSummaryByExternalIdParams, c as ProductUserCreditSummaryResponse, d as ProductUserListParams, e as ProductUserListResponse, f as GrantCreditParams, g as GrantProductUserCreditsResponse, h as GrantCreditByExternalIdParams, L as ListCreditGrantsParams, i as ProductUserCreditGrantListResponse, j as ListCreditGrantsByExternalIdParams, R as RevokeProductUserCreditGrantResponse } from './zorveus-error-DbltWNhC.mjs';
+export { A as APIConnectionError, k as APIStatusError, l as AppConnectionCreditMode, m as AppConnectionNotFoundError, n as AuthenticationError, C as CapExceededError, o as CreditGrant, q as CreditGrantExpiredError, r as CreditGrantSource, s as CreditGrantStatus, t as CreditMode, I as InsufficientFundsError, u as InternalServerError, N as NotFoundError, v as PermissionDeniedError, w as ProductUser, x as ProductUserAllowanceInsufficientError, y as ProductUserAllowanceInsufficientParams, z as ProductUserCapResponse, B as ProductUserCreditGrantResponse, D as ProductUserStatus, E as ProductUserUsageMetrics, F as ProductUserUsageSummary, H as RateLimitError, J as ReservationConflictError, K as UnprocessableEntityError, Z as ZorveusBusinessError, M as ZorveusError, O as createAPIError, p as parseZorveusGatewayError } from './zorveus-error-DbltWNhC.mjs';
+
 interface ZorveusInferenceClientOptions {
     /**
      * API Key used for gateway inference.
@@ -98,6 +101,8 @@ interface InferenceKeyUsageResponse {
     period: "daily" | "weekly" | "monthly" | "lifetime" | string;
     spend_cap: string | null;
     spent_this_period: string;
+    /** Explicit reference-priced spend, when returned by newer API versions. */
+    virtual_spend_this_period?: string;
     remaining_balance: string | null;
     reset_at: string | null;
 }
@@ -167,6 +172,10 @@ interface ZorveusMetadata {
      * The startup's external customer ID (e.g. "usr_ext_8842").
      */
     externalUserId?: string;
+    /**
+     * Zorveus product end-user ID (e.g. "peu_...").
+     */
+    productEndUserId?: string;
     /**
      * Customer's display name.
      */
@@ -187,6 +196,7 @@ interface ZorveusGatewayProductUserMetadata {
 }
 interface ZorveusGatewayMetadata {
     external_user_id?: string;
+    product_end_user_id?: string;
     product_user?: ZorveusGatewayProductUserMetadata;
 }
 /**
@@ -265,6 +275,11 @@ interface ChatCompletionUsage {
     total_tokens: number;
     prompt_tokens_details?: {
         cached_tokens?: number;
+        cache_creation_tokens?: number;
+        cache_creation_token_details?: {
+            ephemeral_5m_input_tokens?: number;
+            ephemeral_1h_input_tokens?: number;
+        };
     };
     completion_tokens_details?: {
         reasoning_tokens?: number;
@@ -352,157 +367,6 @@ interface ModelListResponse {
     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";
@@ -615,6 +479,75 @@ interface CallbackValidationResult {
     errorDescription?: string;
 }
 
+/** Values are open-ended so newer API enum values do not break older clients. */
+type CacheUsageBreakdownStatus = "reported" | "not_reported" | "invalid" | (string & {});
+type CacheServiceTier = "standard" | "flex" | "priority" | (string & {});
+type CachePricingFallbackReason = "invalid_token_breakdown" | "cache_read_price_missing" | "cache_creation_price_missing" | "cache_duration_unsupported" | "cached_audio_breakdown_unavailable" | "service_tier_unavailable" | (string & {});
+type UsageBillingMode = "wallet" | "byok_external" | (string & {});
+type UsageEventStatus = "succeeded" | "partially_settled" | "failed" | (string & {});
+interface UsageEvent {
+    usage_event_id: string;
+    zorveus_request_id: string;
+    app_id: string | null;
+    app_connection_id: string | null;
+    product_end_user_id: string | null;
+    external_user_id: string | null;
+    member_user_id: string | null;
+    org_member_id: string | null;
+    org_id: string;
+    model: string;
+    provider: string | null;
+    provider_model: string | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_creation_1h_input_tokens: number;
+    cache_usage_breakdown_status: CacheUsageBreakdownStatus;
+    pricing_service_tier: CacheServiceTier | null;
+    cache_pricing_fallback_reason: CachePricingFallbackReason | null;
+    cache_savings: string;
+    provider_cost: string;
+    sell_cost: string;
+    virtual_spend: string;
+    uncovered_virtual_spend: string;
+    unfunded_wallet_charge: string;
+    usage_cost: string;
+    billing_mode: UsageBillingMode;
+    status: UsageEventStatus;
+    overrun_policy?: string | null;
+    overrun_reason?: string | null;
+    requested_max_output_tokens?: number | null;
+    applied_max_output_tokens?: number | null;
+    provider_credential_id?: string | null;
+    provider_credential_version_id?: string | null;
+    reservation_id?: string | null;
+    latency_ms?: number | null;
+    created_at: string;
+    [key: string]: unknown;
+}
+interface UsageEventListParams {
+    orgId?: string;
+    appId?: string;
+    appConnectionId?: string;
+    productEndUserId?: string;
+    model?: string;
+    provider?: string;
+    billingMode?: UsageBillingMode;
+    status?: UsageEventStatus;
+    createdAfter?: string;
+    createdBefore?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface UsageEventListResponse {
+    events: UsageEvent[];
+    next_cursor: string | null;
+    has_more: boolean;
+    limit: number;
+}
+declare function normalInputTokens(event: UsageEvent): number | null;
+
 declare class Embeddings {
     private readonly transport;
     constructor(transport: HTTPTransport);
@@ -716,13 +649,15 @@ declare class ProviderCredentials {
     private readonly transport;
     constructor(transport: HTTPTransport);
     /**
-     * Registers an organization BYOK provider credential via Service Key (`POST /provider-credentials/org-programmatic`).
+     * Registers an organization BYOK provider credential via Service Key (`POST /provider-credentials`).
      */
     create(params: CreateProviderCredentialParams, options?: RequestOptions): Promise<ProviderCredentialResponse>;
     /**
-     * Lists BYOK provider credentials for an organization (`GET /provider-credentials/org-programmatic`).
+     * Lists BYOK provider credentials for an organization (`GET /provider-credentials`).
      */
     list(params?: ListProviderCredentialsParams, options?: RequestOptions): Promise<ProviderCredentialListResponse>;
+    /** Retrieves one BYOK provider credential by ID. */
+    get(providerCredentialId: string, options?: RequestOptions): Promise<ProviderCredentialResponse>;
     /**
      * Rotates a provider credential secret (`POST /provider-credentials/org-programmatic/{id}/rotate`).
      */
@@ -737,6 +672,13 @@ declare class ProviderCredentials {
     listProviders(options?: RequestOptions): Promise<ProviderCredentialProviderCatalogResponse>;
 }
 
+declare class UsageEvents {
+    private readonly transport;
+    constructor(transport: HTTPTransport);
+    /** Lists immutable usage events with cursor pagination. */
+    list(params?: UsageEventListParams, options?: RequestOptions): Promise<UsageEventListResponse>;
+}
+
 /**
  * Zorveus Service Client (Server-to-Server Management Control Plane).
  * Authenticated via Organization Service Key (`zrv_service_...`).
@@ -745,6 +687,7 @@ declare class ProviderCredentials {
 declare class ZorveusServiceClient {
     readonly productUsers: ProductUsers;
     readonly providerCredentials: ProviderCredentials;
+    readonly usageEvents: UsageEvents;
     protected readonly transport: HTTPTransport;
     constructor(options: ZorveusServiceClientOptions);
 }
@@ -775,137 +718,6 @@ declare class ZorveusOAuth {
     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.
@@ -915,5 +727,9 @@ 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;
+/** Formats a decimal string without converting the monetary value to a Number. */
+declare function formatDecimalString(value: string, fractionDigits?: number): string;
+/** Returns a percentage for display while keeping the decimal division in integer arithmetic. */
+declare function decimalPercentage(numerator: string, denominator: string): number;
 
-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 };
+export { type AuthorizationUrlParams, type CachePricingFallbackReason, type CacheServiceTier, type CacheUsageBreakdownStatus, type CallbackValidationOptions, type CallbackValidationResult, 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 EmbeddingCreateParams, type EmbeddingCreateResponse, type EmbeddingData, type EmbeddingUsage, GetProductUserByExternalIdParams, GetProductUserCreditSummaryByExternalIdParams, GrantCreditByExternalIdParams, GrantCreditParams, GrantProductUserCreditsResponse, type InferenceKeyUsageResponse, ListCreditGrantsByExternalIdParams, ListCreditGrantsParams, type ListProviderCredentialsParams, type Model, type ModelListParams, type ModelListResponse, type OAuthTokenResponse, type PKCEData, ProductUserCreditGrantListResponse, ProductUserCreditSummaryResponse, ProductUserListParams, ProductUserListResponse, ProductUserResponse, type ProviderCredential, type ProviderCredentialListResponse, type ProviderCredentialProviderCatalogResponse, type ProviderCredentialProviderInfo, type ProviderCredentialResponse, type ProviderCredentialRoutingMode, type ProviderCredentialSecretKind, type ProviderCredentialStatus, type RequestOptions, RevokeProductUserCreditGrantResponse, type RotateProviderCredentialParams, type RotateProviderCredentialResponse, type TokenExchangeParams, type TokenRevocationParams, UpsertProductUserParams, UpsertProductUserResponse, type UsageBillingMode, type UsageEvent, type UsageEventListParams, type UsageEventListResponse, type UsageEventStatus, Zorveus, type ZorveusClientOptions, type ZorveusGatewayMetadata, type ZorveusGatewayProductUserMetadata, ZorveusInferenceClient, type ZorveusInferenceClientOptions, type ZorveusMetadata, ZorveusOAuth, ZorveusServiceClient, type ZorveusServiceClientOptions, assertDecimalString, decimalPercentage, formatDecimalString, formatGatewayMetadata, isValidDecimalString, normalInputTokens };