@closeloop/sdk 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -1,4 +1,845 @@
-export { A as AuthenticationError, B as Balances, k as BatchConsumeParams, l as BatchConsumeResponse, C as CloseLoop, c as CloseLoopError, a as CloseLoopOptions, i as ConsumeCreditsParams, j as ConsumeCreditsResponse, m as CreditBalance, r as CreditStats, o as CreditTransaction, b as Credits, d as CreditsExpiredError, v as CreditsExpiredPayload, u as CreditsLowPayload, G as GetBalanceParams, I as InsufficientCreditsError, L as ListBalancesParams, n as ListBalancesResponse, p as ListTransactionsParams, q as ListTransactionsResponse, N as NetworkError, e as NotFoundError, P as PaymentSuccessPayload, R as RateLimitError, f as ValidationError, g as VerifyCreditsParams, h as VerifyCreditsResponse, V as VerifyWebhookParams, t as WebhookEvent, s as WebhookEventType, w as WebhookPayload, W as Webhooks } from './errors-CNnLzjDZ.js';
+/**
+ * Credit balance for a wallet and plan
+ */
+interface CreditBalance {
+    /**
+     * Unique balance ID
+     */
+    id: string;
+    /**
+     * The product ID
+     */
+    productId: string;
+    /**
+     * Wallet address of the balance owner
+     */
+    walletAddress: 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 product ID
+     */
+    productId: string;
+    /**
+     * The wallet address of the user
+     */
+    walletAddress: 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..."
+     * })
+     *
+     * 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.totalCredits}: ${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({
+     *   walletAddress: "0x1234...",
+     *   productId: "prod_123"
+     * })
+     * console.log(`Total: ${stats.totalCredits}, Used: ${stats.totalUsed}`)
+     * ```
+     *
+     * @throws {CloseLoopError} When input validation fails
+     */
+    stats(params: {
+        walletAddress: string;
+        productId: string;
+    }): Promise<CreditStats>;
+}
+
+/**
+ * Parameters for verifying credits
+ */
+interface VerifyCreditsParams {
+    /**
+     * The product ID
+     */
+    productId: string;
+    /**
+     * The wallet address of the user
+     */
+    walletAddress: string;
+    /**
+     * The number of credits required
+     */
+    amount: number;
+}
+/**
+ * Response from credit verification
+ */
+interface VerifyCreditsResponse {
+    /**
+     * Whether the user has enough credits
+     */
+    hasEnough: boolean;
+    /**
+     * Current remaining credits
+     */
+    totalRemaining: number;
+    /**
+     * When the credits expire (if applicable)
+     */
+    expiresAt: string | null;
+}
+/**
+ * Parameters for consuming credits
+ */
+interface ConsumeCreditsParams {
+    /**
+     * The product ID
+     */
+    productId: string;
+    /**
+     * The wallet address of the user
+     */
+    walletAddress: 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
+     */
+    totalRemaining: number;
+    /**
+     * The transaction ID for this consumption
+     */
+    transactionId: string;
+}
+
+/**
+ * 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...",
+     *   amount: 10
+     * })
+     *
+     * if (result.hasEnough) {
+     *   // 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...",
+     *   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 two-step operation.
+     *
+     * **Important**: This method performs TWO separate API calls (verify, then consume).
+     * There is a potential race condition between the verify and consume steps where
+     * another request could consume credits. For critical operations, consider:
+     * - Using an `idempotencyKey` to prevent duplicate consumption
+     * - Implementing server-side locking if your use case requires strict atomicity
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await client.credits.verifyAndConsume({
+     *     walletAddress: "0x1234...",
+     *     amount: 5,
+     *     consumedBy: "batch-processing",
+     *     idempotencyKey: "unique-request-id" // Recommended for safety
+     *   })
+     *   // 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>;
+    /**
+     * 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 {
+    /**
+     * Type of access
+     */
+    type: string;
+    /**
+     * Product ID
+     */
+    productId: string;
+    /**
+     * Plan ID
+     */
+    planId: string;
+    /**
+     * Transaction ID
+     */
+    transactionId: string;
+    /**
+     * Wallet address of the payer
+     */
+    walletAddress: string;
+    /**
+     * Allow additional properties for extensibility
+     */
+    [key: string]: unknown;
+}
+/**
+ * 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;
+    /**
+     * Optional: Custom timestamp tolerance in seconds.
+     * Webhooks older than this will be rejected to prevent replay attacks.
+     * @default 300 (5 minutes)
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * 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 { type, walletAddress, planId, amount } = event.data
+     *       // Handle payment success
+     *     }
+     *
+     *     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.planId, event.data.walletAddress)
+     * }
+     * ```
+     */
+    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;
+    /**
+     * Validate webhook timestamp to prevent replay attacks
+     * Rejects webhooks older than the specified tolerance
+     */
+    private validateTimestamp;
+}
+
+/**
+ * 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);
+}
 
 /**
  * Generic schema interface for validation
@@ -23,4 +864,4 @@ interface ValidationSchema<T> {
  */
 declare function validateInput<T>(schema: ValidationSchema<T>, data: unknown): T;
 
-export { validateInput };
+export { AuthenticationError, Balances, CloseLoop, CloseLoopError, type CloseLoopOptions, type ConsumeCreditsParams, type ConsumeCreditsResponse, type CreditBalance, type CreditStats, type CreditTransaction, Credits, CreditsExpiredError, type CreditsExpiredPayload, type CreditsLowPayload, type GetBalanceParams, InsufficientCreditsError, type ListBalancesParams, type ListBalancesResponse, type ListTransactionsParams, type ListTransactionsResponse, NetworkError, NotFoundError, type PaymentSuccessPayload, RateLimitError, ValidationError, type VerifyCreditsParams, type VerifyCreditsResponse, type VerifyWebhookParams, type WebhookEvent, type WebhookEventType, type WebhookPayload, Webhooks, validateInput };