@closeloop/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CloseLoop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,478 @@
+# @closeloop/sdk
+
+Official Node.js SDK for the [CloseLoop](https://closeloop.app) credit billing system.
+
+[![npm version](https://img.shields.io/npm/v/@closeloop/sdk.svg)](https://www.npmjs.com/package/@closeloop/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install @closeloop/sdk
+# or
+pnpm add @closeloop/sdk
+# or
+yarn add @closeloop/sdk
+```
+
+## Quick Start
+
+```typescript
+import { CloseLoop } from "@closeloop/sdk"
+
+const client = new CloseLoop({
+  apiKey: process.env.CLOSELOOP_API_KEY!
+})
+
+// Verify credits before processing
+const verification = await client.credits.verify({
+  walletAddress: "0x1234...",
+  planId: "plan_abc123",
+  amount: 1
+})
+
+if (verification.hasEnoughCredits) {
+  // Process the request...
+
+  // Consume the credit
+  await client.credits.consume({
+    walletAddress: "0x1234...",
+    planId: "plan_abc123",
+    amount: 1,
+    consumedBy: "my-service"
+  })
+}
+```
+
+## Features
+
+- 🔒 **Secure** - Input validation, HMAC webhook verification, timing-safe comparisons
+- ⚡ **Fast** - Lightweight with minimal dependencies
+- 🔄 **Atomic operations** - Verify and consume in one call
+- 🪝 **Webhook support** - Secure signature verification with schema validation
+- 📦 **Framework helpers** - Next.js middleware with rate limiting docs
+- ✅ **Validated** - All inputs validated with Zod schemas
+
+## API Reference
+
+### Credit Operations
+
+#### Verify Credits
+
+Check if a user has enough credits without consuming them:
+
+```typescript
+const result = await client.credits.verify({
+  walletAddress: "0x...",
+  planId: "plan_id",
+  amount: 10
+})
+
+console.log(result.hasEnoughCredits) // true
+console.log(result.remainingCredits) // 100
+console.log(result.expiresAt) // "2024-12-31T23:59:59Z" or null
+```
+
+#### Consume Credits
+
+Deduct credits from a user's balance:
+
+```typescript
+const result = await client.credits.consume({
+  walletAddress: "0x...",
+  planId: "plan_id",
+  amount: 1,
+  consumedBy: "ai-generation", // Optional: track what used the credits
+  metadata: { requestId: "req_123" }, // Optional: attach metadata
+  idempotencyKey: "unique-key-123" // Optional: prevent duplicates
+})
+
+console.log(result.success) // true
+console.log(result.remainingCredits) // 99
+console.log(result.transactionId) // "tx_abc123"
+```
+
+#### Verify and Consume (Atomic)
+
+Verify and consume in a single operation to prevent race conditions:
+
+```typescript
+import { InsufficientCreditsError, CreditsExpiredError } from "@closeloop/sdk"
+
+try {
+  const result = await client.credits.verifyAndConsume({
+    walletAddress: "0x...",
+    planId: "plan_id",
+    amount: 5,
+    consumedBy: "batch-processing"
+  })
+  // Credits were verified and consumed
+} catch (error) {
+  if (error instanceof InsufficientCreditsError) {
+    console.log(`Need ${error.requiredCredits}, have ${error.remainingCredits}`)
+  } else if (error instanceof CreditsExpiredError) {
+    console.log(`Credits expired at ${error.expiresAt}`)
+  }
+}
+```
+
+#### Batch Consume
+
+Consume credits for multiple users in one request:
+
+```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}`)
+```
+
+### Balance Queries
+
+#### Get Specific Balance
+
+```typescript
+const balance = await client.balances.get({
+  walletAddress: "0x...",
+  planId: "plan_id"
+})
+
+if (balance) {
+  console.log(`${balance.remainingCredits} / ${balance.totalCredits} credits`)
+  console.log(`Active: ${balance.isActive}`)
+  console.log(`Expires: ${balance.expiresAt}`)
+}
+```
+
+#### List All Balances
+
+```typescript
+const { balances, nextCursor, totalCount } = await client.balances.list({
+  walletAddress: "0x...",
+  activeOnly: true,
+  limit: 10
+})
+
+for (const balance of balances) {
+  console.log(`${balance.planName}: ${balance.remainingCredits} credits`)
+}
+
+// Paginate
+if (nextCursor) {
+  const nextPage = await client.balances.list({
+    walletAddress: "0x...",
+    cursor: nextCursor
+  })
+}
+```
+
+#### Get Transaction History
+
+```typescript
+const { transactions } = await client.balances.transactions({
+  balanceId: "bal_id",
+  type: "CONSUMPTION", // Optional filter
+  limit: 50
+})
+
+for (const tx of transactions) {
+  console.log(`${tx.type}: ${tx.amount} - ${tx.description}`)
+}
+```
+
+#### Get Aggregated Stats
+
+```typescript
+const stats = await client.balances.stats("0x...")
+
+console.log(`Total: ${stats.totalCredits}`)
+console.log(`Used: ${stats.totalUsed}`)
+console.log(`Remaining: ${stats.totalRemaining}`)
+console.log(`Active Balances: ${stats.activeBalances}`)
+```
+
+### Webhook Verification
+
+Securely verify webhook signatures:
+
+```typescript
+// Express
+app.post("/webhook", (req, res) => {
+  try {
+    const event = client.webhooks.verify({
+      payload: req.body, // raw body string
+      signature: req.headers["x-closeloop-signature"],
+      secret: process.env.WEBHOOK_SECRET!
+    })
+
+    // Type-safe event handling
+    if (client.webhooks.isPaymentSuccess(event)) {
+      const { creditAmount, payerAddress, planId } = event.data
+      console.log(`${payerAddress} purchased ${creditAmount} credits`)
+    }
+
+    if (client.webhooks.isCreditsLow(event)) {
+      const { walletAddress, remainingCredits, threshold } = event.data
+      console.log(`Low balance alert: ${remainingCredits} < ${threshold}`)
+    }
+
+    if (client.webhooks.isCreditsExpired(event)) {
+      const { walletAddress, expiredCredits } = event.data
+      console.log(`${expiredCredits} credits expired`)
+    }
+
+    res.json({ received: true })
+  } catch (error) {
+    res.status(400).json({ error: "Invalid signature" })
+  }
+})
+```
+
+```typescript
+// Next.js App Router
+export async function POST(request: Request) {
+  const payload = await request.text()
+  const signature = request.headers.get("x-closeloop-signature")!
+
+  try {
+    const event = client.webhooks.verify({
+      payload,
+      signature,
+      secret: process.env.WEBHOOK_SECRET!
+    })
+
+    // Handle event...
+    return Response.json({ received: true })
+  } catch {
+    return Response.json({ error: "Invalid signature" }, { status: 400 })
+  }
+}
+```
+
+## Next.js Integration
+
+### Middleware
+
+Protect routes by requiring credits:
+
+```typescript
+// middleware.ts
+import { CloseLoop, creditGate } from "@closeloop/sdk/nextjs"
+
+const client = new CloseLoop({ apiKey: process.env.CLOSELOOP_API_KEY! })
+
+export default creditGate({
+  client,
+  planId: "plan_abc123",
+  creditsPerRequest: 1,
+  getWalletAddress: (req) => req.headers.get("x-wallet-address")
+})
+
+export const config = {
+  matcher: ["/api/protected/:path*"]
+}
+```
+
+### API Route Helper
+
+Consume credits after processing:
+
+```typescript
+// app/api/ai/route.ts
+import { NextRequest, NextResponse } from "next/server"
+import { CloseLoop, consumeCreditsAfterRequest } from "@closeloop/sdk/nextjs"
+
+const client = new CloseLoop({ apiKey: process.env.CLOSELOOP_API_KEY! })
+
+export async function POST(request: NextRequest) {
+  const wallet = request.headers.get("x-wallet-address")!
+  
+  // Process request...
+  const result = await processAIRequest()
+  
+  // Consume credit after successful processing
+  await consumeCreditsAfterRequest(client, {
+    walletAddress: wallet,
+    planId: "plan_abc123",
+    amount: 1,
+    consumedBy: "ai-text-generation",
+    metadata: { requestId: result.id }
+  })
+  
+  return NextResponse.json(result)
+}
+```
+
+## Error Handling
+
+All errors extend `CloseLoopError`:
+
+```typescript
+import {
+  CloseLoopError,
+  InsufficientCreditsError,
+  CreditsExpiredError,
+  AuthenticationError,
+  RateLimitError,
+  NetworkError,
+  NotFoundError,
+  ValidationError
+} from "@closeloop/sdk"
+
+try {
+  await client.credits.consume({ ... })
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // 400 - Invalid input (bad wallet address, negative amount, etc.)
+    console.log(`Validation error: ${error.message}`)
+  } else if (error instanceof InsufficientCreditsError) {
+    // 402 - Not enough credits
+    console.log(`Need ${error.requiredCredits}, have ${error.remainingCredits}`)
+  } else if (error instanceof CreditsExpiredError) {
+    // 410 - Credits expired
+    console.log(`Expired at ${error.expiresAt}`)
+  } else if (error instanceof AuthenticationError) {
+    // 401 - Invalid API key
+    console.log("Check your API key")
+  } else if (error instanceof RateLimitError) {
+    // 429 - Too many requests
+    console.log(`Retry after ${error.retryAfter} seconds`)
+  } else if (error instanceof NotFoundError) {
+    // 404 - Resource not found
+    console.log("Balance or plan not found")
+  } else if (error instanceof NetworkError) {
+    // Network issues
+    console.log(`Network error: ${error.message}`)
+  } else if (error instanceof CloseLoopError) {
+    // Other API errors
+    console.log(`API error: ${error.code} - ${error.message}`)
+  }
+}
+```
+
+## Security
+
+### Input Validation
+
+All inputs are validated using Zod schemas before being sent to the API:
+
+- **Wallet addresses**: Must be valid Ethereum addresses (`0x` + 40 hex chars)
+- **Plan IDs**: Non-empty strings with max 100 characters
+- **Credit amounts**: Positive integers up to 1 billion
+- **Metadata**: Sanitized to prevent prototype pollution attacks
+
+### Rate Limiting
+
+The `creditGate` middleware does **not** include rate limiting. We strongly recommend combining it with a rate limiter:
+
+```typescript
+// middleware.ts - With rate limiting (RECOMMENDED)
+import { CloseLoop, creditGate } from "@closeloop/sdk/nextjs"
+import { Ratelimit } from "@upstash/ratelimit"
+import { Redis } from "@upstash/redis"
+
+const client = new CloseLoop({ apiKey: process.env.CLOSELOOP_API_KEY! })
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"), // 10 requests per 10 seconds
+})
+
+const creditGateMiddleware = creditGate({
+  client,
+  planId: "plan_abc123",
+  creditsPerRequest: 1,
+  getWalletAddress: (req) => req.headers.get("x-wallet-address")
+})
+
+export default async function middleware(request: NextRequest) {
+  // Rate limit by IP first
+  const ip = request.ip ?? "127.0.0.1"
+  const { success } = await ratelimit.limit(ip)
+
+  if (!success) {
+    return NextResponse.json({ error: "Rate limit exceeded" }, { status: 429 })
+  }
+
+  // Then check credits
+  return creditGateMiddleware(request)
+}
+
+export const config = {
+  matcher: ["/api/protected/:path*"]
+}
+```
+
+### Webhook Security
+
+- HMAC-SHA256 signatures with timing-safe comparison
+- Schema validation for all webhook payloads
+- Type guards validate payload structure before use
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  // Client
+  CloseLoopOptions,
+  
+  // Credits
+  VerifyCreditsParams,
+  VerifyCreditsResponse,
+  ConsumeCreditsParams,
+  ConsumeCreditsResponse,
+  BatchConsumeParams,
+  BatchConsumeResponse,
+  
+  // Balances
+  CreditBalance,
+  CreditTransaction,
+  CreditStats,
+  GetBalanceParams,
+  ListBalancesParams,
+  ListBalancesResponse,
+  ListTransactionsParams,
+  ListTransactionsResponse,
+  
+  // Webhooks
+  WebhookEvent,
+  WebhookEventType,
+  WebhookPayload,
+  PaymentSuccessPayload,
+  CreditsLowPayload,
+  CreditsExpiredPayload,
+  VerifyWebhookParams
+} from "@closeloop/sdk"
+```
+
+## Configuration
+
+```typescript
+const client = new CloseLoop({
+  // Required: Your API key from CloseLoop dashboard
+  apiKey: process.env.CLOSELOOP_API_KEY!,
+  
+  // Optional: Custom API URL (for self-hosted instances)
+  baseUrl: "https://closeloop.app",
+  
+  // Optional: Request timeout in milliseconds (default: 30000)
+  timeout: 30000
+})
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Next.js 14.0.0 or higher (for Next.js helpers)
+
+## License
+
+MIT