@lavapayments/nodejs
Version:
Backend SDK for Lava Payments API - enabling usage-based billing for AI services
429 lines (424 loc) • 12.7 kB
text/typescript
interface CreateCheckoutSessionParams {
checkout_mode: 'onboarding' | 'topup' | 'subscription';
origin_url: string;
reference_id?: string;
connection_id?: string;
subscription_config_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;
}
interface CreateSubscriptionConfigParams {
name: string;
period_amount: string;
rollover_type: 'full' | 'none';
}
interface UpdateSubscriptionConfigParams {
name?: string;
period_amount?: string;
rollover_type?: 'full' | 'none';
}
type RestCheckoutSession = {
checkout_session_id: string;
checkout_session_token: string;
checkout_mode: 'onboarding' | 'topup' | 'subscription';
origin_url: string;
connection_id?: string;
reference_id?: string;
subscription_config_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;
};
};
type RestSubscriptionConfig = {
subscription_config_id: string;
merchant_id: string;
name: string;
period_amount: string;
rollover_type: 'full' | 'none';
created_at: string;
};
type RestActiveSubscription = {
active_subscription_id: string;
wallet_id: string;
subscription_config_id: string;
started_at: string;
billing_anchor: number;
cancelled_at?: string;
status: 'active' | 'cancelled';
created_at: string;
subscription_config: RestSubscriptionConfig;
wallet: {
wallet_id: string;
phone: string;
email?: string;
first_name?: string;
last_name?: string;
active_balance: string;
created_at: string;
};
};
/** biome-ignore-all lint/style/noNamespace: package uses namespace */
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 class SubscriptionsResource extends BaseResource {
/**
* List subscription configurations
* @returns List of subscription configurations
*/
listConfigs(): Promise<RestSubscriptionConfig[]>;
/**
* Create a subscription configuration
* @param params Subscription configuration parameters
* @returns Created subscription configuration
*/
createConfig(params: CreateSubscriptionConfigParams): Promise<RestSubscriptionConfig>;
/**
* Update a subscription configuration
* @param id Subscription configuration ID
* @param params Update parameters
* @returns Updated subscription configuration
*/
updateConfig(id: string, params: UpdateSubscriptionConfigParams): Promise<RestSubscriptionConfig>;
/**
* Delete a subscription configuration
* @param id Subscription configuration ID
* @returns Success response
*/
deleteConfig(id: string): Promise<{
success: boolean;
}>;
/**
* List active subscriptions for a merchant
* @returns List of active subscriptions
*/
listActiveSubscriptions(): Promise<RestActiveSubscription[]>;
/**
* Cancel an active subscription
* @param id Active subscription ID
* @returns Success response
*/
cancelActiveSubscription(id: string): Promise<{
success: boolean;
}>;
}
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;
/**
* The subscriptions resource
*/
readonly subscriptions: Resources.SubscriptionsResource;
/**
* 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?: unknown;
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 CreateSubscriptionConfigParams, type ForwardTokenOptions, Lava, type ListResponse, type RequestsListParams, type RequestsListResponse, Resources, type RestActiveSubscription, type RestCheckoutSession, type RestConnection, type RestRequest, type RestSubscriptionConfig, type RestUsage, type UpdateSubscriptionConfigParams, type UsageParams };