@drip-sdk/node 1.0.10 → 1.1.1

package/README.md

@@ -1,702 +1,264 @@
-# @drip-sdk/node
+# Drip SDK (Node.js)
 
-The official Node.js SDK for **Drip** - Usage-based billing for AI agents.
+Drip is a lightweight SDK for **usage tracking and execution logging** in systems where cost is tied to computation — AI agents, APIs, background jobs, and infra workloads.
 
-Drip enables real-time, per-request billing using USDC on blockchain. Perfect for AI APIs, compute platforms, and any service with variable usage patterns.
+This **Core SDK** is designed for pilots: it records *what ran* and *how much it used*, without handling billing or balances.
 
-[![npm version](https://badge.fury.io/js/@drip-sdk/node.svg)](https://www.npmjs.com/package/@drip-sdk/node)
+**One line to start tracking:** `await drip.trackUsage({ customerId, meter, quantity })`
+
+[![npm version](https://img.shields.io/npm/v/%40drip-sdk%2Fnode.svg)](https://www.npmjs.com/package/@drip-sdk/node)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Installation
+---
 
-```bash
-npm install @drip-sdk/node
-```
+## 60-Second Quickstart (Core SDK)
 
-```bash
-yarn add @drip-sdk/node
-```
+### 1. Install
 
 ```bash
-pnpm add @drip-sdk/node
+npm install @drip-sdk/node
 ```
 
-## Quick Start
-
-### One-Liner Integration (Recommended)
-
-The fastest way to add billing to your API:
+### 2. Set your API key
 
-#### Next.js App Router
-
-```typescript
-// app/api/generate/route.ts
-import { withDrip } from '@drip-sdk/node/next';
+```bash
+# Secret key — full API access (server-side only, never expose publicly)
+export DRIP_API_KEY=sk_test_...
 
-export const POST = withDrip({
-  meter: 'api_calls',
-  quantity: 1,
-}, async (req, { charge, customerId }) => {
-  // Your handler - payment already verified!
-  console.log(`Charged ${charge.charge.amountUsdc} USDC to ${customerId}`);
-  return Response.json({ result: 'success' });
-});
+# Or public key — read/write access for usage, customers, billing (safe for client-side)
+export DRIP_API_KEY=pk_test_...
 ```
 
-#### Express
+### 3. Track usage (one line)
 
 ```typescript
-import express from 'express';
-import { dripMiddleware } from '@drip-sdk/node/express';
-
-const app = express();
+import { drip } from '@drip-sdk/node';
 
-app.use('/api/paid', dripMiddleware({
-  meter: 'api_calls',
-  quantity: 1,
-}));
-
-app.post('/api/paid/generate', (req, res) => {
-  console.log(`Charged: ${req.drip.charge.charge.amountUsdc} USDC`);
-  res.json({ success: true });
-});
+// Track usage - that's it
+await drip.trackUsage({ customerId: 'cust_123', meter: 'api_calls', quantity: 1 });
 ```
 
-### Manual Integration
+The `drip` singleton reads `DRIP_API_KEY` from your environment automatically.
 
-For more control, use the SDK directly:
+### Alternative: Explicit Configuration
 
 ```typescript
 import { Drip } from '@drip-sdk/node';
 
-// Initialize the client
-const drip = new Drip({
-  apiKey: process.env.DRIP_API_KEY!,
-});
-
-// Create a customer
-const customer = await drip.createCustomer({
-  onchainAddress: '0x1234567890abcdef...',
-  externalCustomerId: 'user_123',
-});
+// Auto-reads DRIP_API_KEY from environment
+const drip = new Drip();
 
-// Record usage and charge
-const result = await drip.charge({
-  customerId: customer.id,
-  meter: 'api_calls',
-  quantity: 100,
-});
+// Or pass config explicitly with a secret key (full access)
+const drip = new Drip({ apiKey: 'sk_test_...' });
 
-console.log(`Charged ${result.charge.amountUsdc} USDC`);
-console.log(`TX: ${result.charge.txHash}`);
+// Or with a public key (safe for client-side, limited scope)
+const drip = new Drip({ apiKey: 'pk_test_...' });
 ```
 
-## Configuration
+### Full Example
 
 ```typescript
-const drip = new Drip({
-  // Required: Your Drip API key
-  apiKey: 'drip_live_abc123...',
-
-  // Optional: API base URL (for staging/development)
-  baseUrl: 'https://api.drip.dev/v1',
-
-  // Optional: Request timeout in milliseconds (default: 30000)
-  timeout: 30000,
-});
-```
-
-## API Reference
+import { drip } from '@drip-sdk/node';
+
+async function main() {
+  // Verify connectivity
+  await drip.ping();
+
+  // Record usage
+  await drip.trackUsage({
+    customerId: 'customer_123',
+    meter: 'llm_tokens',
+    quantity: 842,
+    metadata: { model: 'gpt-4o-mini' },
+  });
 
-### Customer Management
+  // Record an execution lifecycle
+  await drip.recordRun({
+    customerId: 'customer_123',
+    workflow: 'research-agent',
+    events: [
+      { eventType: 'llm.call', model: 'gpt-4', inputTokens: 500, outputTokens: 1200 },
+      { eventType: 'tool.call', name: 'web-search', duration: 1500 },
+    ],
+    status: 'COMPLETED',
+  });
 
-#### Create a Customer
+  console.log('Usage + run recorded');
+}
 
-```typescript
-const customer = await drip.createCustomer({
-  onchainAddress: '0x1234567890abcdef...',
-  externalCustomerId: 'user_123', // Your internal user ID
-  metadata: { plan: 'pro' },
-});
+main();
 ```
 
-#### Get a Customer
+**Expected result:**
+- No errors
+- Events appear in your Drip dashboard within seconds
 
-```typescript
-const customer = await drip.getCustomer('cust_abc123');
-```
+---
 
-#### List Customers
+## Core Concepts (2-minute mental model)
 
-```typescript
-// List all customers
-const { data: customers } = await drip.listCustomers();
+| Concept | Description |
+|---------|-------------|
+| `customerId` | The end user, API key, or account you're attributing usage to |
+| `meter` | What you're measuring (tokens, requests, seconds, rows, etc.) |
+| `quantity` | Numeric usage for that meter |
+| `run` | A single execution or request lifecycle (success / failure / duration) |
 
-// With filters
-const { data: activeCustomers } = await drip.listCustomers({
-  status: 'ACTIVE',
-  limit: 50,
-});
-```
+**Status values:** `PENDING` | `RUNNING` | `COMPLETED` | `FAILED`
 
-#### Get Customer Balance
+**Event schema:** Payloads are schema-flexible. Drip stores events as structured JSON and does not enforce a fixed event taxonomy.
 
-```typescript
-const balance = await drip.getBalance('cust_abc123');
-console.log(`Balance: ${balance.balanceUSDC} USDC`);
-```
+Drip is append-only and idempotent-friendly. You can safely retry events.
 
-### Meters (Usage Types)
+---
 
-#### List Available Meters
+## Idempotency Keys
 
-Discover what meter names are valid for charging. Meters are defined by your pricing plans.
-
-```typescript
-const { data: meters } = await drip.listMeters();
+Every mutating SDK method (`charge`, `trackUsage`, `emitEvent`) accepts an optional `idempotencyKey` parameter. The server uses this key to deduplicate requests — if two requests share the same key, only the first is processed.
 
-console.log('Available meters:');
-for (const meter of meters) {
-  console.log(`  ${meter.meter}: $${meter.unitPriceUsd}/unit`);
-}
-// Output:
-//   api_calls: $0.001/unit
-//   tokens: $0.00001/unit
-//   compute_seconds: $0.01/unit
-```
+`recordRun` generates idempotency keys internally for its batch events (using `externalRunId` when provided, otherwise deterministic keys).
 
-### Charging & Usage
+### Auto-generated keys (default)
 
-#### Record Usage and Charge
+When you omit `idempotencyKey`, the SDK generates one automatically. The auto key is:
 
-```typescript
-const result = await drip.charge({
-  customerId: 'cust_abc123',
-  meter: 'api_calls',
-  quantity: 100,
-  idempotencyKey: 'req_unique_123', // Prevents duplicate charges
-  metadata: { endpoint: '/v1/chat' },
-});
+- **Unique per call** — two separate calls with identical parameters produce different keys (a monotonic counter ensures this).
+- **Stable across retries** — the key is generated once and reused for all retry attempts of that call, so network retries are safely deduplicated.
+- **Deterministic** — no randomness; keys are reproducible for debugging.
 
-if (result.success) {
-  console.log(`Charge ID: ${result.charge.id}`);
-  console.log(`Amount: ${result.charge.amountUsdc} USDC`);
-  console.log(`TX Hash: ${result.charge.txHash}`);
-}
-```
+This means you get **free retry safety** with zero configuration.
 
-#### Get Charge Details
+> **Note:** `wrapApiCall` generates a time-based key when no explicit `idempotencyKey` is provided. Pass your own key if you need deterministic deduplication with `wrapApiCall`.
 
-```typescript
-const charge = await drip.getCharge('chg_abc123');
-console.log(`Status: ${charge.status}`);
-```
+### When to pass explicit keys
 
-#### List Charges
+Pass your own `idempotencyKey` when you need **application-level deduplication** — e.g., to guarantee that a specific business operation is billed exactly once, even across process restarts:
 
 ```typescript
-// List all charges
-const { data: charges } = await drip.listCharges();
-
-// Filter by customer and status
-const { data: customerCharges } = await drip.listCharges({
-  customerId: 'cust_abc123',
-  status: 'CONFIRMED',
-  limit: 50,
+await drip.charge({
+  customerId: 'cust_123',
+  meter: 'api_calls',
+  quantity: 1,
+  idempotencyKey: `order_${orderId}_charge`, // your business-level key
 });
 ```
 
-#### Check Charge Status
+Common patterns:
+- `order_${orderId}` — one charge per order
+- `run_${runId}_step_${stepIndex}` — one charge per pipeline step
+- `invoice_${invoiceId}` — one charge per invoice
 
-```typescript
-const status = await drip.getChargeStatus('chg_abc123');
-if (status.status === 'CONFIRMED') {
-  console.log('Charge confirmed on-chain!');
-}
-```
+### StreamMeter
 
-### Streaming Meter
+`StreamMeter` also auto-generates idempotency keys per flush. If you provide an `idempotencyKey` in the options, each flush appends a counter (`_flush_0`, `_flush_1`, etc.) to keep multi-flush scenarios safe.
 
-For LLM token streaming and other high-frequency metering scenarios, use the streaming meter to accumulate usage locally and charge once at the end:
+---
 
-```typescript
-import { Drip } from '@drip-sdk/node';
+## API Key Types
 
-const drip = new Drip({ apiKey: process.env.DRIP_API_KEY! });
+Drip issues two key types per API key pair. Each has different access scopes:
 
-// Create a stream meter for a customer
-const meter = drip.createStreamMeter({
-  customerId: 'cust_abc123',
-  meter: 'tokens',
-});
+| Key Type | Prefix | Access | Use In |
+|----------|--------|--------|--------|
+| **Secret Key** | `sk_live_` / `sk_test_` | Full API access (all endpoints) | Server-side only |
+| **Public Key** | `pk_live_` / `pk_test_` | Usage tracking, customers, billing, analytics, sessions | Client-side safe |
 
-// Stream from your LLM provider
-const stream = await openai.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Hello!' }],
-  stream: true,
-});
+### What public keys **can** access
+- Usage tracking (`trackUsage`, `recordRun`, `startRun`, `emitEvent`, etc.)
+- Customer management (`createCustomer`, `getCustomer`, `listCustomers`)
+- Billing & charges (`charge`, `getBalance`, `listCharges`, etc.)
+- Pricing plans, sessions, analytics, usage caps, refunds
 
-// Accumulate tokens as they stream
-for await (const chunk of stream) {
-  const tokens = chunk.usage?.completion_tokens ?? 1;
-  meter.add(tokens); // Accumulates locally, no API call
-  yield chunk;
-}
-
-// Single charge at end of stream
-const result = await meter.flush();
-console.log(`Charged ${result.charge.amountUsdc} USDC for ${result.quantity} tokens`);
-```
+### What public keys **cannot** access (secret key required)
+- Webhook management (`createWebhook`, `listWebhooks`, `deleteWebhook`, etc.)
+- API key management (create, rotate, revoke keys)
+- Feature flag management
 
-#### Stream Meter Options
+The SDK detects your key type automatically and will throw a `DripError` with code `PUBLIC_KEY_NOT_ALLOWED` (HTTP 403) if you attempt a secret-key-only operation with a public key.
 
 ```typescript
-const meter = drip.createStreamMeter({
-  customerId: 'cust_abc123',
-  meter: 'tokens',
+const drip = new Drip({ apiKey: 'pk_test_...' });
+console.log(drip.keyType); // 'public'
 
-  // Optional: Custom idempotency key
-  idempotencyKey: 'stream_req_123',
+// This works fine
+await drip.trackUsage({ customerId: 'cust_123', meter: 'api_calls', quantity: 1 });
 
-  // Optional: Metadata attached to the charge
-  metadata: { model: 'gpt-4', endpoint: '/v1/chat' },
-
-  // Optional: Auto-flush when threshold reached
-  flushThreshold: 10000, // Flush every 10k tokens
-
-  // Optional: Callback on each add
-  onAdd: (quantity, total) => console.log(`Added ${quantity}, total: ${total}`),
-});
+// This throws DripError(403, 'PUBLIC_KEY_NOT_ALLOWED')
+await drip.createWebhook({ url: '...', events: ['charge.succeeded'] });
 ```
 
-#### Handling Partial Failures
+---
 
-If the stream fails mid-way, you can still charge for what was delivered:
-
-```typescript
-const meter = drip.createStreamMeter({
-  customerId: 'cust_abc123',
-  meter: 'tokens',
-});
-
-try {
-  for await (const chunk of stream) {
-    meter.add(chunk.tokens);
-    yield chunk;
-  }
-  await meter.flush();
-} catch (error) {
-  // Charge for tokens delivered before failure
-  if (meter.total > 0) {
-    await meter.flush();
-  }
-  throw error;
-}
-```
+## SDK Variants
 
-#### Multiple Meters in One Request
+| Variant | Description |
+|---------|-------------|
+| **Core SDK** (recommended for pilots) | Usage tracking + execution logging only |
+| **Full SDK** | Includes billing, balances, and workflows (for later stages) |
 
-```typescript
-const tokenMeter = drip.createStreamMeter({ customerId, meter: 'tokens' });
-const toolMeter = drip.createStreamMeter({ customerId, meter: 'tool_calls' });
-
-for await (const chunk of agentStream) {
-  if (chunk.type === 'token') {
-    tokenMeter.add(1);
-  } else if (chunk.type === 'tool_call') {
-    toolMeter.add(1);
-  }
-  yield chunk;
-}
+---
 
-// Flush all meters
-await Promise.all([tokenMeter.flush(), toolMeter.flush()]);
-```
+## Core SDK Methods
 
-### Run Tracking (Simplified API)
+| Method | Description |
+|--------|-------------|
+| `ping()` | Verify API connection |
+| `createCustomer(params)` | Create a customer |
+| `getCustomer(customerId)` | Get customer details |
+| `listCustomers(options)` | List all customers |
+| `trackUsage(params)` | Record metered usage |
+| `recordRun(params)` | Log complete agent run (simplified) |
+| `startRun(params)` | Start execution trace |
+| `emitEvent(params)` | Log event within run |
+| `emitEventsBatch(params)` | Batch log events |
+| `endRun(runId, params)` | Complete execution trace |
+| `getRunTimeline(runId)` | Get execution timeline |
 
-Track agent executions with a single API call instead of multiple separate calls.
+---
 
-#### Record a Complete Run
+## Who This Is For
 
-The `recordRun()` method combines workflow creation, run tracking, event emission, and completion into one call:
+- AI agents (token metering, tool calls, execution traces)
+- API companies (per-request billing, endpoint attribution)
+- RPC providers (multi-chain call tracking)
+- Cloud/infra (compute seconds, storage, bandwidth)
 
-```typescript
-// Before: 4+ separate API calls
-const workflow = await drip.createWorkflow({ name: 'My Agent', slug: 'my_agent' });
-const run = await drip.startRun({ customerId, workflowId: workflow.id });
-await drip.emitEvent({ runId: run.id, eventType: 'step1', ... });
-await drip.emitEvent({ runId: run.id, eventType: 'step2', ... });
-await drip.endRun(run.id, { status: 'COMPLETED' });
-
-// After: 1 call with recordRun()
-const result = await drip.recordRun({
-  customerId: 'cust_123',
-  workflow: 'my_agent',  // Auto-creates workflow if it doesn't exist
-  events: [
-    { eventType: 'agent.start', description: 'Started processing' },
-    { eventType: 'tool.ocr', quantity: 3, units: 'pages', costUnits: 0.15 },
-    { eventType: 'tool.validate', quantity: 1, costUnits: 0.05 },
-    { eventType: 'agent.complete', description: 'Finished successfully' },
-  ],
-  status: 'COMPLETED',
-});
+---
 
-console.log(result.summary);
-// Output: "✓ My Agent: 4 events recorded (250ms)"
-```
+## Full SDK (Billing, Webhooks, Integrations)
 
-#### Record a Failed Run
+For billing, webhooks, middleware, and advanced features:
 
 ```typescript
-const result = await drip.recordRun({
-  customerId: 'cust_123',
-  workflow: 'prescription_intake',
-  events: [
-    { eventType: 'agent.start', description: 'Started processing' },
-    { eventType: 'error', description: 'OCR failed: image too blurry' },
-  ],
-  status: 'FAILED',
-  errorMessage: 'OCR processing failed',
-  errorCode: 'OCR_QUALITY_ERROR',
-});
-
-console.log(result.summary);
-// Output: "✗ Prescription Intake: 2 events recorded (150ms)"
-```
-
-### Webhooks
-
-#### Create a Webhook
-
-```typescript
-const webhook = await drip.createWebhook({
-  url: 'https://api.yourapp.com/webhooks/drip',
-  events: ['charge.succeeded', 'charge.failed', 'customer.balance.low'],
-  description: 'Main webhook endpoint',
-});
-
-// IMPORTANT: Save the secret securely!
-console.log(`Webhook secret: ${webhook.secret}`);
-```
-
-#### List Webhooks
-
-```typescript
-const { data: webhooks } = await drip.listWebhooks();
-webhooks.forEach((wh) => {
-  console.log(`${wh.url}: ${wh.stats?.successfulDeliveries} successful`);
-});
-```
-
-#### Delete a Webhook
-
-```typescript
-await drip.deleteWebhook('wh_abc123');
-```
-
-#### Verify Webhook Signatures
-
-```typescript
-import express from 'express';
 import { Drip } from '@drip-sdk/node';
-
-const app = express();
-
-app.post(
-  '/webhooks/drip',
-  express.raw({ type: 'application/json' }),
-  (req, res) => {
-    const isValid = Drip.verifyWebhookSignature(
-      req.body.toString(),
-      req.headers['x-drip-signature'] as string,
-      process.env.DRIP_WEBHOOK_SECRET!,
-    );
-
-    if (!isValid) {
-      return res.status(401).send('Invalid signature');
-    }
-
-    const event = JSON.parse(req.body.toString());
-
-    switch (event.type) {
-      case 'charge.succeeded':
-        console.log('Charge succeeded:', event.data.charge_id);
-        break;
-      case 'charge.failed':
-        console.log('Charge failed:', event.data.failure_reason);
-        break;
-      case 'customer.balance.low':
-        console.log('Low balance alert for:', event.data.customer_id);
-        break;
-    }
-
-    res.status(200).send('OK');
-  },
-);
 ```
 
-### Available Webhook Events
-
-| Event                        | Description                          |
-| ---------------------------- | ------------------------------------ |
-| `charge.succeeded`           | Charge confirmed on-chain            |
-| `charge.failed`              | Charge failed                        |
-| `customer.balance.low`       | Customer balance below threshold     |
-| `customer.deposit.confirmed` | Deposit confirmed on-chain           |
-| `customer.withdraw.confirmed`| Withdrawal confirmed                 |
-| `customer.usage_cap.reached` | Usage cap hit                        |
-| `customer.created`           | New customer created                 |
-| `usage.recorded`             | Usage event recorded                 |
-| `transaction.created`        | Transaction initiated                |
-| `transaction.confirmed`      | Transaction confirmed on-chain       |
-| `transaction.failed`         | Transaction failed                   |
-
-## TypeScript Usage
+See **[FULL_SDK.md](./FULL_SDK.md)** for complete documentation.
 
-The SDK is written in TypeScript and includes full type definitions.
-
-```typescript
-import {
-  Drip,
-  DripConfig,
-  DripError,
-  Customer,
-  Charge,
-  ChargeResult,
-  ChargeStatus,
-  Webhook,
-  WebhookEventType,
-  StreamMeter,
-  StreamMeterOptions,
-} from '@drip-sdk/node';
-
-// All types are available for use
-const config: DripConfig = {
-  apiKey: process.env.DRIP_API_KEY!,
-};
-
-const drip = new Drip(config);
-
-// Type-safe responses
-const customer: Customer = await drip.getCustomer('cust_abc123');
-const result: ChargeResult = await drip.charge({
-  customerId: customer.id,
-  meter: 'api_calls',
-  quantity: 100,
-});
-```
+---
 
 ## Error Handling
 
-The SDK throws `DripError` for API errors:
-
 ```typescript
 import { Drip, DripError } from '@drip-sdk/node';
 
 try {
-  const result = await drip.charge({
-    customerId: 'cust_abc123',
-    meter: 'api_calls',
-    quantity: 100,
-  });
+  await drip.trackUsage({ ... });
 } catch (error) {
   if (error instanceof DripError) {
-    console.error(`API Error: ${error.message}`);
-    console.error(`Status Code: ${error.statusCode}`);
-    console.error(`Error Code: ${error.code}`);
-
-    switch (error.code) {
-      case 'INSUFFICIENT_BALANCE':
-        // Handle low balance
-        break;
-      case 'CUSTOMER_NOT_FOUND':
-        // Handle missing customer
-        break;
-      case 'RATE_LIMITED':
-        // Handle rate limiting
-        break;
-    }
+    console.error(`Error: ${error.message} (${error.code})`);
   }
 }
 ```
 
-### Common Error Codes
-
-| Code                   | Description                              |
-| ---------------------- | ---------------------------------------- |
-| `INSUFFICIENT_BALANCE` | Customer doesn't have enough balance     |
-| `CUSTOMER_NOT_FOUND`   | Customer ID doesn't exist                |
-| `DUPLICATE_CUSTOMER`   | Customer already exists                  |
-| `INVALID_API_KEY`      | API key is invalid or revoked            |
-| `RATE_LIMITED`         | Too many requests                        |
-| `TIMEOUT`              | Request timed out                        |
-
-## Idempotency
-
-Use idempotency keys to safely retry requests:
-
-```typescript
-const result = await drip.charge({
-  customerId: 'cust_abc123',
-  meter: 'api_calls',
-  quantity: 100,
-  idempotencyKey: `req_${requestId}`, // Unique per request
-});
-
-// Retrying with the same key returns the original result
-const retry = await drip.charge({
-  customerId: 'cust_abc123',
-  meter: 'api_calls',
-  quantity: 100,
-  idempotencyKey: `req_${requestId}`, // Same key = same result
-});
-```
-
-## CommonJS Usage
-
-The SDK supports both ESM and CommonJS:
-
-```javascript
-// ESM
-import { Drip } from '@drip-sdk/node';
-
-// CommonJS
-const { Drip } = require('@drip-sdk/node');
-```
+---
 
 ## Requirements
 
 - Node.js 18.0.0 or higher
-- Native `fetch` support (included in Node.js 18+)
-
-## Middleware Reference (withDrip)
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `meter` | `string` | **required** | Usage meter to charge (must match pricing plan) |
-| `quantity` | `number \| (req) => number` | **required** | Quantity to charge (static or dynamic) |
-| `apiKey` | `string` | `DRIP_API_KEY` | Drip API key |
-| `baseUrl` | `string` | `DRIP_API_URL` | Drip API base URL |
-| `customerResolver` | `'header' \| 'query' \| function` | `'header'` | How to identify customers |
-| `skipInDevelopment` | `boolean` | `false` | Skip charging in dev mode |
-| `metadata` | `object \| function` | `undefined` | Custom metadata for charges |
-| `onCharge` | `function` | `undefined` | Callback after successful charge |
-| `onError` | `function` | `undefined` | Custom error handler |
-
-### How It Works
-
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   Your API      │    │   withDrip       │    │   Drip Backend  │
-│   (Next/Express)│───▶│   Middleware     │───▶│   API           │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
-         │                      │                       │
-         ▼                      ▼                       ▼
-    1. Request            2. Resolve             3. Check balance
-       arrives               customer               & charge
-         │                      │                       │
-         ▼                      ▼                       ▼
-    6. Response           5. Pass to             4. Return result
-       returned              handler                or 402
-```
-
-### x402 Payment Flow
-
-When a customer has insufficient balance, the middleware returns `402 Payment Required`:
-
-```
-HTTP/1.1 402 Payment Required
-X-Payment-Required: true
-X-Payment-Amount: 0.01
-X-Payment-Recipient: 0x...
-X-Payment-Usage-Id: 0x...
-X-Payment-Expires: 1704110400
-X-Payment-Nonce: abc123
-
-{
-  "error": "Payment required",
-  "code": "PAYMENT_REQUIRED",
-  "paymentRequest": { ... },
-  "instructions": {
-    "step1": "Sign the payment request with your session key using EIP-712",
-    "step2": "Retry the request with X-Payment-* headers"
-  }
-}
-```
-
-### Advanced Usage
-
-#### Dynamic Quantity
-
-```typescript
-export const POST = withDrip({
-  meter: 'tokens',
-  quantity: async (req) => {
-    const body = await req.json();
-    return body.maxTokens ?? 100;
-  },
-}, handler);
-```
-
-#### Custom Customer Resolution
-
-```typescript
-export const POST = withDrip({
-  meter: 'api_calls',
-  quantity: 1,
-  customerResolver: (req) => {
-    const token = req.headers.get('authorization')?.split(' ')[1];
-    return decodeJWT(token).customerId;
-  },
-}, handler);
-```
-
-#### Factory Pattern
-
-```typescript
-// lib/drip.ts
-import { createWithDrip } from '@drip-sdk/node/next';
-
-export const withDrip = createWithDrip({
-  apiKey: process.env.DRIP_API_KEY,
-  baseUrl: process.env.DRIP_API_URL,
-});
-
-// app/api/generate/route.ts
-import { withDrip } from '@/lib/drip';
-export const POST = withDrip({ meter: 'api_calls', quantity: 1 }, handler);
-```
-
-### What's Included vs. Missing
-
-| Feature | Status | Description |
-|---------|--------|-------------|
-| Next.js App Router | ✅ | `withDrip` wrapper |
-| Express Middleware | ✅ | `dripMiddleware` |
-| x402 Payment Flow | ✅ | Automatic 402 handling |
-| Dynamic Quantity | ✅ | Function-based pricing |
-| Customer Resolution | ✅ | Header, query, or custom |
-| Idempotency | ✅ | Built-in or custom keys |
-| Dev Mode Skip | ✅ | Skip in development |
-| Metadata | ✅ | Attach to charges |
-| TypeScript | ✅ | Full type definitions |
-| Streaming Meter | ✅ | For LLM token streams |
-
-## Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-## License
-
-MIT - see [LICENSE](./LICENSE)
 
 ## Links
 
-- [GitHub Repository](https://github.com/MichaelLevin5908/drip-sdk)
-- [Issue Tracker](https://github.com/MichaelLevin5908/drip-sdk/issues)
-- [npm Package](https://www.npmjs.com/package/@drip-sdk/node)
-- [Documentation](https://docs.drip.dev)
+- [Full SDK Documentation](./FULL_SDK.md)
+- [API Documentation](https://drippay.dev/api-reference)
+- [npm](https://www.npmjs.com/package/@drip-sdk/node)