@closeloop/sdk 0.1.0

package/dist/errors-B0i1OvBd.d.mts

@@ -0,0 +1,909 @@
+/**
+ * Credit balance for a wallet and plan
+ */
+interface CreditBalance {
+    /**
+     * Unique balance ID
+     */
+    id: string;
+    /**
+     * Wallet address of the balance owner
+     */
+    walletAddress: string;
+    /**
+     * Plan ID this balance is for
+     */
+    planId: string;
+    /**
+     * Plan name for display
+     */
+    planName: string;
+    /**
+     * Total credits purchased
+     */
+    totalCredits: number;
+    /**
+     * Credits consumed
+     */
+    usedCredits: number;
+    /**
+     * Remaining available credits
+     */
+    remainingCredits: number;
+    /**
+     * Whether the balance is active
+     */
+    isActive: boolean;
+    /**
+     * When the credits expire (if applicable)
+     */
+    expiresAt: string | null;
+    /**
+     * When the balance was created
+     */
+    createdAt: string;
+    /**
+     * When the balance was last updated
+     */
+    updatedAt: string;
+}
+/**
+ * Parameters for getting a specific balance
+ */
+interface GetBalanceParams {
+    /**
+     * The wallet address of the user
+     */
+    walletAddress: string;
+    /**
+     * The plan ID to get balance for
+     */
+    planId: string;
+}
+/**
+ * Parameters for listing balances
+ */
+interface ListBalancesParams {
+    /**
+     * The wallet address to get all balances for
+     */
+    walletAddress: string;
+    /**
+     * Only return active balances
+     */
+    activeOnly?: boolean;
+    /**
+     * Maximum number of results
+     */
+    limit?: number;
+    /**
+     * Cursor for pagination
+     */
+    cursor?: string;
+}
+/**
+ * Response from listing balances
+ */
+interface ListBalancesResponse {
+    /**
+     * Array of credit balances
+     */
+    balances: CreditBalance[];
+    /**
+     * Cursor for next page (null if no more)
+     */
+    nextCursor: string | null;
+    /**
+     * Total count of balances
+     */
+    totalCount: number;
+}
+/**
+ * Credit transaction record
+ */
+interface CreditTransaction {
+    /**
+     * Transaction ID
+     */
+    id: string;
+    /**
+     * Balance ID this transaction belongs to
+     */
+    balanceId: string;
+    /**
+     * Type of transaction
+     */
+    type: "PURCHASE" | "CONSUMPTION" | "REFUND" | "EXPIRATION";
+    /**
+     * Amount (positive for additions, negative for deductions)
+     */
+    amount: number;
+    /**
+     * Description of the transaction
+     */
+    description: string | null;
+    /**
+     * What consumed the credits (for CONSUMPTION type)
+     */
+    consumedBy: string | null;
+    /**
+     * Additional metadata
+     */
+    metadata: Record<string, unknown> | null;
+    /**
+     * When the transaction occurred
+     */
+    createdAt: string;
+}
+/**
+ * Parameters for listing transactions
+ */
+interface ListTransactionsParams {
+    /**
+     * Balance ID to get transactions for
+     */
+    balanceId: string;
+    /**
+     * Filter by transaction type
+     */
+    type?: "PURCHASE" | "CONSUMPTION" | "REFUND" | "EXPIRATION";
+    /**
+     * Maximum number of results
+     */
+    limit?: number;
+    /**
+     * Cursor for pagination
+     */
+    cursor?: string;
+}
+/**
+ * Response from listing transactions
+ */
+interface ListTransactionsResponse {
+    /**
+     * Array of transactions
+     */
+    transactions: CreditTransaction[];
+    /**
+     * Cursor for next page
+     */
+    nextCursor: string | null;
+}
+/**
+ * Aggregated stats for a wallet's credits
+ */
+interface CreditStats {
+    /**
+     * Total credits across all balances
+     */
+    totalCredits: number;
+    /**
+     * Total credits used
+     */
+    totalUsed: number;
+    /**
+     * Total remaining credits
+     */
+    totalRemaining: number;
+    /**
+     * Number of active balances
+     */
+    activeBalances: number;
+}
+
+interface HttpClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP client for making requests to the CloseLoop API
+ */
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(options: HttpClientOptions);
+    /**
+     * Make an HTTP request to the CloseLoop API
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    private handleErrorResponse;
+}
+
+/**
+ * Resource for querying credit balances and transaction history
+ */
+declare class Balances {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get a specific credit balance for a wallet and plan.
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.balances.get({
+     *   walletAddress: "0x1234...",
+     *   planId: "plan_abc123"
+     * })
+     *
+     * if (balance) {
+     *   console.log(`Credits: ${balance.remainingCredits}/${balance.totalCredits}`)
+     * }
+     * ```
+     *
+     * @returns The credit balance, or null if not found
+     * @throws {CloseLoopError} When input validation fails
+     */
+    get(params: GetBalanceParams): Promise<CreditBalance | null>;
+    /**
+     * List all credit balances for a wallet.
+     *
+     * @example
+     * ```typescript
+     * const { balances, nextCursor } = await client.balances.list({
+     *   walletAddress: "0x1234...",
+     *   activeOnly: true,
+     *   limit: 10
+     * })
+     *
+     * for (const balance of balances) {
+     *   console.log(`${balance.planName}: ${balance.remainingCredits} credits`)
+     * }
+     *
+     * // Paginate if needed
+     * if (nextCursor) {
+     *   const nextPage = await client.balances.list({
+     *     walletAddress: "0x1234...",
+     *     cursor: nextCursor
+     *   })
+     * }
+     * ```
+     *
+     * @throws {CloseLoopError} When input validation fails
+     */
+    list(params: ListBalancesParams): Promise<ListBalancesResponse>;
+    /**
+     * Get transaction history for a balance.
+     *
+     * @example
+     * ```typescript
+     * const { transactions } = await client.balances.transactions({
+     *   balanceId: "bal_xyz",
+     *   type: "CONSUMPTION",
+     *   limit: 50
+     * })
+     *
+     * for (const tx of transactions) {
+     *   console.log(`${tx.type}: ${tx.amount} - ${tx.description}`)
+     * }
+     * ```
+     *
+     * @throws {CloseLoopError} When input validation fails
+     */
+    transactions(params: ListTransactionsParams): Promise<ListTransactionsResponse>;
+    /**
+     * Get aggregated stats for a wallet's credits.
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.balances.stats("0x1234...")
+     * console.log(`Total: ${stats.totalCredits}, Used: ${stats.totalUsed}`)
+     * ```
+     *
+     * @throws {CloseLoopError} When input validation fails
+     */
+    stats(walletAddress: string): Promise<CreditStats>;
+    /**
+     * Build URL query string from params, filtering out undefined values
+     */
+    private buildQueryString;
+}
+
+/**
+ * Parameters for verifying credits
+ */
+interface VerifyCreditsParams {
+    /**
+     * The wallet address of the user
+     */
+    walletAddress: string;
+    /**
+     * The plan ID to check credits for
+     */
+    planId: string;
+    /**
+     * The number of credits required
+     */
+    amount: number;
+}
+/**
+ * Response from credit verification
+ */
+interface VerifyCreditsResponse {
+    /**
+     * Whether the user has enough credits
+     */
+    hasEnoughCredits: boolean;
+    /**
+     * Current remaining credits
+     */
+    remainingCredits: number;
+    /**
+     * When the credits expire (if applicable)
+     */
+    expiresAt: string | null;
+}
+/**
+ * Parameters for consuming credits
+ */
+interface ConsumeCreditsParams {
+    /**
+     * The wallet address of the user
+     */
+    walletAddress: string;
+    /**
+     * The plan ID to consume credits from
+     */
+    planId: string;
+    /**
+     * The number of credits to consume
+     */
+    amount: number;
+    /**
+     * Optional identifier for what consumed the credits
+     * (e.g., "ai-text-generation", "image-processing")
+     */
+    consumedBy?: string;
+    /**
+     * Optional metadata to attach to the transaction
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Idempotency key to prevent duplicate consumption
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Response from credit consumption
+ */
+interface ConsumeCreditsResponse {
+    /**
+     * Whether the consumption was successful
+     */
+    success: boolean;
+    /**
+     * Remaining credits after consumption
+     */
+    remainingCredits: number;
+    /**
+     * Total credits used
+     */
+    usedCredits: number;
+    /**
+     * The transaction ID for this consumption
+     */
+    transactionId: string;
+}
+/**
+ * Parameters for batch credit consumption
+ */
+interface BatchConsumeParams {
+    /**
+     * Array of consumption operations
+     */
+    operations: Array<{
+        walletAddress: string;
+        planId: string;
+        amount: number;
+        consumedBy?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    /**
+     * If true, fail the entire batch if any operation fails
+     */
+    atomic?: boolean;
+}
+/**
+ * Response from batch credit consumption
+ */
+interface BatchConsumeResponse {
+    /**
+     * Results for each operation
+     */
+    results: Array<{
+        success: boolean;
+        remainingCredits?: number;
+        error?: string;
+    }>;
+    /**
+     * Number of successful operations
+     */
+    successCount: number;
+    /**
+     * Number of failed operations
+     */
+    failedCount: number;
+}
+
+/**
+ * Resource for credit verification and consumption operations
+ */
+declare class Credits {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Verify if a user has enough credits without consuming them.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.credits.verify({
+     *   walletAddress: "0x1234...",
+     *   planId: "plan_abc123",
+     *   amount: 10
+     * })
+     *
+     * if (result.hasEnoughCredits) {
+     *   // Proceed with service
+     * }
+     * ```
+     *
+     * @throws {CloseLoopError} When input validation fails
+     */
+    verify(params: VerifyCreditsParams): Promise<VerifyCreditsResponse>;
+    /**
+     * Consume credits from a user's balance.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.credits.consume({
+     *   walletAddress: "0x1234...",
+     *   planId: "plan_abc123",
+     *   amount: 1,
+     *   consumedBy: "ai-generation",
+     *   metadata: { requestId: "req_xyz" }
+     * })
+     *
+     * console.log(`Remaining: ${result.remainingCredits}`)
+     * ```
+     *
+     * @throws {InsufficientCreditsError} When user doesn't have enough credits
+     * @throws {CreditsExpiredError} When credits have expired
+     * @throws {CloseLoopError} When input validation fails
+     */
+    consume(params: ConsumeCreditsParams): Promise<ConsumeCreditsResponse>;
+    /**
+     * Verify and consume credits in a single atomic operation.
+     * This is useful when you want to ensure credits are available
+     * before consuming them, without race conditions.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await client.credits.verifyAndConsume({
+     *     walletAddress: "0x1234...",
+     *     planId: "plan_abc123",
+     *     amount: 5,
+     *     consumedBy: "batch-processing"
+     *   })
+     *   // Credits were verified and consumed
+     * } catch (error) {
+     *   if (error instanceof InsufficientCreditsError) {
+     *     // Handle insufficient credits
+     *   }
+     * }
+     * ```
+     *
+     * @throws {InsufficientCreditsError} When user doesn't have enough credits
+     * @throws {CreditsExpiredError} When credits have expired
+     * @throws {CloseLoopError} When input validation fails
+     */
+    verifyAndConsume(params: ConsumeCreditsParams): Promise<ConsumeCreditsResponse>;
+    /**
+     * Consume credits in batch.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.credits.batchConsume({
+     *   operations: [
+     *     { walletAddress: "0x1234...", planId: "plan_a", amount: 1 },
+     *     { walletAddress: "0x5678...", planId: "plan_b", amount: 2 }
+     *   ],
+     *   atomic: false // Allow partial success
+     * })
+     *
+     * console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`)
+     * ```
+     *
+     * @throws {CloseLoopError} When input validation fails
+     */
+    batchConsume(params: BatchConsumeParams): Promise<BatchConsumeResponse>;
+    /**
+     * Build consumption request body with sanitized metadata
+     */
+    private buildConsumeBody;
+    /**
+     * Build idempotency headers if key is provided
+     */
+    private buildIdempotencyHeaders;
+    /**
+     * Assert credits are available, throw typed errors if not
+     */
+    private assertCreditsAvailable;
+}
+
+/**
+ * Webhook event types
+ */
+type WebhookEventType = "payment.success" | "credits.low" | "credits.expired";
+/**
+ * Webhook event wrapper
+ */
+interface WebhookEvent<T = WebhookPayload> {
+    /**
+     * Event type
+     */
+    type: WebhookEventType;
+    /**
+     * Unique event ID
+     */
+    id: string;
+    /**
+     * When the event was created
+     */
+    createdAt: string;
+    /**
+     * Event payload
+     */
+    data: T;
+}
+/**
+ * Payload for payment.success events
+ */
+interface PaymentSuccessPayload {
+    /**
+     * Transaction ID
+     */
+    transactionId: string;
+    /**
+     * Plan ID that was purchased
+     */
+    planId: string;
+    /**
+     * Plan name
+     */
+    planName: string;
+    /**
+     * Payment amount in USDC
+     */
+    amount: number;
+    /**
+     * Number of API requests (for API access type)
+     */
+    requests: number | null;
+    /**
+     * Number of credits (for CREDIT access type)
+     */
+    creditAmount: number | null;
+    /**
+     * Blockchain transaction hash
+     */
+    transactionHash: string;
+    /**
+     * Wallet address of the payer
+     */
+    payerAddress: string;
+    /**
+     * Access type of the plan
+     */
+    accessType: string;
+}
+/**
+ * Payload for credits.low events
+ */
+interface CreditsLowPayload {
+    /**
+     * Wallet address
+     */
+    walletAddress: string;
+    /**
+     * Plan ID
+     */
+    planId: string;
+    /**
+     * Remaining credits
+     */
+    remainingCredits: number;
+    /**
+     * Low balance threshold that triggered this event
+     */
+    threshold: number;
+}
+/**
+ * Payload for credits.expired events
+ */
+interface CreditsExpiredPayload {
+    /**
+     * Wallet address
+     */
+    walletAddress: string;
+    /**
+     * Plan ID
+     */
+    planId: string;
+    /**
+     * Number of credits that expired
+     */
+    expiredCredits: number;
+    /**
+     * When the credits expired
+     */
+    expiresAt: string;
+}
+/**
+ * Union of all webhook payloads
+ */
+type WebhookPayload = PaymentSuccessPayload | CreditsLowPayload | CreditsExpiredPayload;
+
+/**
+ * Parameters for verifying a webhook
+ */
+interface VerifyWebhookParams {
+    /**
+     * Raw request body as string or Buffer
+     */
+    payload: string | Buffer;
+    /**
+     * X-CloseLoop-Signature header value
+     */
+    signature: string;
+    /**
+     * Your webhook secret
+     */
+    secret: string;
+}
+/**
+ * Resource for webhook signature verification and event handling
+ */
+declare class Webhooks {
+    /**
+     * Verify a webhook signature and parse the event.
+     *
+     * @example
+     * ```typescript
+     * // Express handler
+     * app.post("/webhook", (req, res) => {
+     *   try {
+     *     const event = client.webhooks.verify({
+     *       payload: req.body,
+     *       signature: req.headers["x-closeloop-signature"],
+     *       secret: process.env.WEBHOOK_SECRET!
+     *     })
+     *
+     *     if (client.webhooks.isPaymentSuccess(event)) {
+     *       const { creditAmount, payerAddress } = event.data
+     *       // Handle credit purchase
+     *     }
+     *
+     *     res.json({ received: true })
+     *   } catch (error) {
+     *     res.status(400).json({ error: "Invalid signature" })
+     *   }
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Next.js App Router
+     * export async function POST(request: Request) {
+     *   const payload = await request.text()
+     *   const signature = request.headers.get("x-closeloop-signature")!
+     *
+     *   const event = client.webhooks.verify({
+     *     payload,
+     *     signature,
+     *     secret: process.env.WEBHOOK_SECRET!
+     *   })
+     *
+     *   // Handle event...
+     *   return Response.json({ received: true })
+     * }
+     * ```
+     *
+     * @throws {CloseLoopError} When signature is invalid or payload is malformed
+     */
+    verify(params: VerifyWebhookParams): WebhookEvent;
+    /**
+     * Type guard for payment.success events
+     * Also validates the payload structure
+     *
+     * @example
+     * ```typescript
+     * if (client.webhooks.isPaymentSuccess(event)) {
+     *   // TypeScript knows event.data is PaymentSuccessPayload
+     *   console.log(event.data.creditAmount)
+     * }
+     * ```
+     */
+    isPaymentSuccess(event: WebhookEvent<WebhookPayload>): event is WebhookEvent<PaymentSuccessPayload>;
+    /**
+     * Type guard for credits.low events
+     * Also validates the payload structure
+     *
+     * @example
+     * ```typescript
+     * if (client.webhooks.isCreditsLow(event)) {
+     *   // TypeScript knows event.data is CreditsLowPayload
+     *   console.log(`Low balance: ${event.data.remainingCredits}`)
+     * }
+     * ```
+     */
+    isCreditsLow(event: WebhookEvent<WebhookPayload>): event is WebhookEvent<CreditsLowPayload>;
+    /**
+     * Type guard for credits.expired events
+     * Also validates the payload structure
+     *
+     * @example
+     * ```typescript
+     * if (client.webhooks.isCreditsExpired(event)) {
+     *   // TypeScript knows event.data is CreditsExpiredPayload
+     *   console.log(`Expired: ${event.data.expiredCredits} credits`)
+     * }
+     * ```
+     */
+    isCreditsExpired(event: WebhookEvent<WebhookPayload>): event is WebhookEvent<CreditsExpiredPayload>;
+    /**
+     * Validate that all required parameters are present
+     */
+    private validateRequiredParams;
+    /**
+     * Convert payload to string regardless of input type
+     */
+    private normalizePayload;
+    /**
+     * Verify HMAC signature or throw error
+     */
+    private verifySignatureOrThrow;
+    /**
+     * Parse JSON payload or throw error
+     */
+    private parseJsonOrThrow;
+    /**
+     * Validate event structure using Zod schema
+     */
+    private validateEventStructure;
+}
+
+/**
+ * Configuration options for the CloseLoop client
+ */
+interface CloseLoopOptions {
+    /**
+     * Your CloseLoop API key.
+     * Get this from your CloseLoop dashboard.
+     */
+    apiKey: string;
+    /**
+     * Base URL for the CloseLoop API.
+     * Defaults to https://closeloop.app
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * Defaults to 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+/**
+ * CloseLoop SDK client for credit billing integration.
+ *
+ * @example
+ * ```typescript
+ * import { CloseLoop } from "@closeloop/sdk"
+ *
+ * const client = new CloseLoop({
+ *   apiKey: process.env.CLOSELOOP_API_KEY!
+ * })
+ *
+ * // Verify credits
+ * const verification = await client.credits.verify({
+ *   walletAddress: "0x1234...",
+ *   planId: "plan_abc123",
+ *   amount: 1
+ * })
+ *
+ * if (verification.hasEnoughCredits) {
+ *   // Process request...
+ *
+ *   // Consume credit
+ *   await client.credits.consume({
+ *     walletAddress: "0x1234...",
+ *     planId: "plan_abc123",
+ *     amount: 1,
+ *     consumedBy: "my-service"
+ *   })
+ * }
+ * ```
+ */
+declare class CloseLoop {
+    private httpClient;
+    /**
+     * Credit consumption and verification operations
+     */
+    readonly credits: Credits;
+    /**
+     * Credit balance queries
+     */
+    readonly balances: Balances;
+    /**
+     * Webhook signature verification utilities
+     */
+    readonly webhooks: Webhooks;
+    constructor(options: CloseLoopOptions);
+}
+
+/**
+ * Base error class for all CloseLoop SDK errors
+ */
+declare class CloseLoopError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when a user doesn't have enough credits for an operation
+ */
+declare class InsufficientCreditsError extends CloseLoopError {
+    remainingCredits: number;
+    requiredCredits: number;
+    constructor(remainingCredits: number, requiredCredits: number);
+}
+/**
+ * Thrown when credits have expired
+ */
+declare class CreditsExpiredError extends CloseLoopError {
+    expiresAt: Date;
+    constructor(expiresAt: Date);
+}
+/**
+ * Thrown when authentication fails (invalid API key)
+ */
+declare class AuthenticationError extends CloseLoopError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends CloseLoopError {
+    retryAfter?: number | undefined;
+    constructor(retryAfter?: number | undefined);
+}
+/**
+ * Thrown when a network error occurs
+ */
+declare class NetworkError extends CloseLoopError {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Thrown when a resource is not found
+ */
+declare class NotFoundError extends CloseLoopError {
+    constructor(resource: string);
+}
+/**
+ * Thrown when input validation fails
+ */
+declare class ValidationError extends CloseLoopError {
+    field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+
+export { AuthenticationError as A, Balances as B, CloseLoop as C, type GetBalanceParams as G, InsufficientCreditsError as I, type ListBalancesParams as L, NetworkError as N, type PaymentSuccessPayload as P, RateLimitError as R, type VerifyWebhookParams as V, Webhooks as W, type CloseLoopOptions as a, Credits as b, CloseLoopError as c, CreditsExpiredError as d, NotFoundError as e, ValidationError as f, type VerifyCreditsParams as g, type VerifyCreditsResponse as h, type ConsumeCreditsParams as i, type ConsumeCreditsResponse as j, type BatchConsumeParams as k, type BatchConsumeResponse as l, type CreditBalance as m, type ListBalancesResponse as n, type CreditTransaction as o, type ListTransactionsParams as p, type ListTransactionsResponse as q, type CreditStats as r, type WebhookEventType as s, type WebhookEvent as t, type CreditsLowPayload as u, type CreditsExpiredPayload as v, type WebhookPayload as w };