@lavapayments/nodejs/dist/index.d.ts

Backend SDK for Lava Payments API - enabling usage-based billing for AI services

interface CreateCheckoutSessionParams {
    checkout_mode: 'onboarding' | 'topup';
    origin_url: string;
    reference_id?: string;
    connection_id?: string;
}
interface CheckoutSessionsListParams {
    cursor?: string;
    limit?: number;
    reference_id?: string;
}
interface ConnectionsListParams {
    cursor?: string;
    limit?: number;
    reference_id?: string;
}
interface RequestsListParams {
    cursor?: string;
    limit?: number;
    connection_id?: string;
    product_id?: string;
    metadata_filters?: Record<string, string>;
}
interface CreateRequestParams {
    request_id: string;
    connection_secret: string;
    product_secret: string;
    metadata?: Record<string, string>;
    input_tokens?: number;
    output_tokens?: number;
    input_characters?: number;
    output_characters?: number;
    input_seconds?: number;
    output_seconds?: number;
}
interface RequestsListResponse {
    data: Request[];
    has_more: boolean;
    next_cursor?: string;
}
interface UsageParams {
    start: string;
    end?: string;
    connection_id?: string;
    product_id?: string;
    metadata_filters?: Record<string, string>;
}
interface ListResponse<T> {
    data: T[];
    has_more: boolean;
    next_cursor?: string;
}
type RestCheckoutSession = {
    checkout_session_id: string;
    checkout_session_token: string;
    checkout_mode: 'onboarding' | 'topup';
    origin_url: string;
    connection_id?: string;
    reference_id?: string;
    created_at: string;
    completed_at?: string;
};
type RestConnection = {
    connection_id: string;
    connection_secret: string;
    reference_id?: string;
    wallet: {
        balance: string;
        phone: string;
        email: string;
        first_name: string;
        last_name: string;
        autopay_enabled: boolean;
    };
    next_usage_reset: string;
    previous_usage_reset: string;
    created_at: string;
};
type RestRequest = {
    request_id: string;
    status: 'pending' | 'completed' | 'error';
    connection_id?: string;
    product_id?: string;
    provider: string;
    provider_key_type: 'managed' | 'unmanaged';
    model?: string;
    endpoint: string;
    response_id?: string;
    model_usage: {
        input_tokens: number;
        output_tokens: number;
        total_tokens: number;
        input_characters: number;
        output_characters: number;
        total_characters: number;
        input_seconds: number;
        output_seconds: number;
        total_seconds: number;
        input_cost: string;
        output_cost: string;
        total_cost: string;
        payer: 'wallet' | 'merchant';
    };
    fee: {
        amount: string;
        rate_type: 'fixed' | 'percentage';
        token_basis: 'input+output' | 'output';
        breakdown: {
            tier: {
                start: number;
                rate: string;
                type: 'tokens_1m' | 'characters_1m' | 'minutes' | 'requests';
            };
            tokens: number;
            characters: number;
            seconds: number;
            cost: string;
        }[];
    };
    service_charge: {
        amount: string;
        payer: 'wallet' | 'merchant';
    };
    total_request_cost: string;
    total_wallet_cost: string;
    total_merchant_cost: string;
    metadata: Record<string, string>;
    timestamp?: string;
    created_at: string;
};
type RestUsage = {
    items: {
        date: string;
        start: string;
        end: string;
        total_requests: number;
        total_usage_tokens: number;
        total_usage_cost: string;
        total_fee_amount: string;
        total_service_charge_amount: string;
        total_request_cost: string;
        total_wallet_cost: string;
        total_merchant_cost: string;
    }[];
    totals: {
        total_requests: number;
        total_usage_tokens: number;
        total_usage_cost: string;
        total_fee_amount: string;
        total_service_charge_amount: string;
        total_request_cost: string;
        total_wallet_cost: string;
        total_merchant_cost: string;
    };
};

/** biome-ignore-all lint/style/noNamespace: <explanation> */

declare namespace Resources {
    abstract class BaseResource {
        protected lava: Lava;
        constructor(lava: Lava);
    }
    /**
     * Checkout session related endpoints
     */
    export class CheckoutSessionsResource extends BaseResource {
        /**
         * Create a checkout session
         * @param params Checkout session parameters
         * @returns Created checkout session
         */
        create(params: CreateCheckoutSessionParams): Promise<RestCheckoutSession>;
        /**
         * List checkout sessions
         * @param params List parameters
         * @returns Paginated list of checkout sessions
         */
        list(params?: CheckoutSessionsListParams): Promise<ListResponse<RestCheckoutSession>>;
        /**
         * Retrieve a checkout session
         * @param checkoutSessionId Checkout session ID
         * @returns Checkout session details
         */
        retrieve(checkoutSessionId: string): Promise<RestCheckoutSession>;
    }
    /**
     * Connection related endpoints
     */
    export class ConnectionsResource extends BaseResource {
        /**
         * List connections
         * @param params List parameters
         * @returns Paginated list of connections
         */
        list(params?: ConnectionsListParams): Promise<ListResponse<RestConnection>>;
        /**
         * Retrieve a connection
         * @param connectionId Connection ID
         * @returns Connection details
         */
        retrieve(connectionId: string): Promise<RestConnection>;
        /**
         * Delete a connection
         * @param connectionId Connection ID
         * @returns Success status
         */
        delete(connectionId: string): Promise<{
            success: boolean;
        }>;
    }
    /**
     * Request related endpoints
     */
    export class RequestsResource extends BaseResource {
        /**
         * List requests
         * @param params List parameters
         * @returns Paginated list of requests
         */
        list(params?: RequestsListParams): Promise<ListResponse<RestRequest>>;
        /**
         * Create a request
         * @param params Request parameters
         * @returns Created request details
         */
        create(params: CreateRequestParams): Promise<RestRequest>;
        /**
         * Retrieve a request
         * @param requestId Request ID
         * @returns Request details
         */
        retrieve(requestId: string): Promise<RestRequest>;
    }
    /**
     * Usage related endpoints
     */
    export class UsageResource extends BaseResource {
        /**
         * Retrieve usage statistics
         * @param params Usage parameters
         * @returns Usage data
         */
        retrieve(params: UsageParams): Promise<RestUsage>;
    }
    export {  };
}

type ApiVersion = '2025-04-28.v1';
interface Config {
    apiVersion: ApiVersion;
    /**
     * Base URL for the API.
     * If not provided, it will be inferred from the secret key (production or sandbox).
     */
    baseUrl?: string;
}
type ForwardTokenOptions = {
    connection_secret: string;
    product_secret: string;
    provider_key?: string;
} | {
    connection_secret: null;
    product_secret: null;
    provider_key: string;
};
declare class Lava {
    private readonly secretKey;
    private readonly baseUrl;
    private readonly apiVersion;
    /**
     * The checkout sessions resource
     */
    readonly checkoutSessions: Resources.CheckoutSessionsResource;
    /**
     * The connections resource
     */
    readonly connections: Resources.ConnectionsResource;
    /**
     * The requests resource
     */
    readonly requests: Resources.RequestsResource;
    /**
     * The usage resource
     */
    readonly usage: Resources.UsageResource;
    /**
     * Provider URLs for convenience
     */
    readonly providers: {
        openai: string;
        anthropic: string;
        mistral: string;
        deepseek: string;
        xai: string;
        google: string;
        googleOpenaiCompatible: string;
        kluster: string;
        inference: string;
        groq: string;
        novita: string;
        vercel: string;
        together: string;
        hyperbolic: string;
        elevenlabs: string;
        sambanova: string;
        deepinfra: string;
        cohere: string;
        parasail: string;
        nebius: string;
        fireworks: string;
        cerebras: string;
        targon: string;
        gmicloud: string;
        chutes: string;
        baseten: string;
    };
    /**
     * Create a new Lava client
     * @param secretKey Your Lava secret key
     * @param config Configuration options
     */
    constructor(secretKey: string, config: Config);
    /**
     * Make a request to the Lava API
     * @param method HTTP method
     * @param path API path
     * @param options Request options
     * @returns Response data
     */
    request<T>(method: string, path: string, { data, query }?: {
        data?: any;
        query?: Record<string, string>;
    }): Promise<T>;
    /**
     * Generate a token for the forward endpoint
     * @param options Token options
     * @returns Base64 encoded token
     */
    generateForwardToken(options: ForwardTokenOptions): string;
}

export { type ApiVersion, type CheckoutSessionsListParams, type Config, type ConnectionsListParams, type CreateCheckoutSessionParams, type CreateRequestParams, type ForwardTokenOptions, Lava, type ListResponse, type RequestsListParams, type RequestsListResponse, Resources, type RestCheckoutSession, type RestConnection, type RestRequest, type RestUsage, type UsageParams };