@waterfall-finance/sdk 0.3.0

package/README.md

@@ -0,0 +1,218 @@
+# Waterfall TypeScript SDK
+
+TypeScript SDK for x402 payments with OpenRouter. This is a 1:1 port of the Python waterfall SDK.
+
+## Installation
+
+```bash
+npm install @waterfall-finance/sdk
+```
+
+## Quick Start
+
+```typescript
+import { WaterfallClient, createClient } from "@waterfall-finance/sdk";
+
+// Option 1: Use the convenience function
+const client = await createClient("wf_your_api_key");
+
+// Option 2: Manual initialization
+const client = new WaterfallClient({
+  apiKey: "wf_your_api_key",
+});
+await client.configureWallet(); // Uses default wallet
+
+// Make a chat completion request
+const response = await client.chat.send({
+  model: "openai/gpt-3.5-turbo",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+console.log(response.choices[0].message.content);
+```
+
+## Features
+
+- **Automatic x402 Payment Handling**: The SDK automatically handles 402 Payment Required responses
+- **OpenRouter Integration**: Full access to OpenRouter's model catalog
+- **Wallet Management**: Create, list, and manage wallets
+- **Streaming Support**: Stream chat completions for real-time responses
+- **TypeScript First**: Full type definitions included
+
+## API Reference
+
+### WaterfallClient
+
+The main client class for interacting with Waterfall.
+
+```typescript
+const client = new WaterfallClient({
+  apiKey: "wf_...", // Your Waterfall API key
+  walletId: "...", // Optional: specific wallet ID
+  backendUrl: "...", // Optional: custom backend URL
+  proxyUrl: "...", // Optional: custom x402 proxy URL
+});
+```
+
+### Client Methods
+
+#### `configureWallet(options?)`
+
+Configure which wallet to use for payments.
+
+```typescript
+// Use default wallet
+await client.configureWallet();
+
+// Use wallet by name
+await client.configureWallet({ walletName: "My Wallet" });
+
+// Use wallet by ID
+await client.configureWallet({ walletId: "wallet_123" });
+```
+
+#### `listWallets()`
+
+List all wallets associated with your API key.
+
+```typescript
+const wallets = await client.listWallets();
+console.log(wallets);
+// [{ id: "...", name: "...", address: "0x...", network: "base-mainnet" }, ...]
+```
+
+#### `createWallet(options)`
+
+Create a new wallet.
+
+```typescript
+const wallet = await client.createWallet({
+  name: "My New Wallet",
+  useTestnet: false, // Optional: use Base Sepolia testnet
+  teamId: "...", // Optional: team ID
+});
+```
+
+### Chat API
+
+#### `chat.send(options)`
+
+Send a chat completion request.
+
+```typescript
+const response = await client.chat.send({
+  model: "openai/gpt-4",
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "What is the capital of France?" },
+  ],
+  temperature: 0.7,
+  maxTokens: 1000,
+});
+```
+
+#### `chat.stream(options)`
+
+Stream a chat completion response.
+
+```typescript
+const stream = await client.chat.stream({
+  model: "openai/gpt-3.5-turbo",
+  messages: [{ role: "user", content: "Tell me a story" }],
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}
+```
+
+### Supported Models
+
+Any model available on OpenRouter can be used:
+
+- `openai/gpt-4`
+- `openai/gpt-3.5-turbo`
+- `anthropic/claude-3-opus`
+- `anthropic/claude-3-sonnet`
+- `google/gemini-pro`
+- `meta-llama/llama-3-70b-instruct`
+- And many more...
+
+## How It Works
+
+1. **Initial Request**: Client sends request to the x402 proxy
+2. **402 Response**: Proxy returns `402 Payment Required` with payment details
+3. **Payment Signing**: SDK automatically signs the payment via Coinbase CDP wallet
+4. **Retry**: SDK retries the request with the payment signature
+5. **Success**: Proxy verifies signature and forwards to OpenRouter
+
+```
+Your Code
+    ↓
+WaterfallClient.chat.send()
+    ↓
+x402 Proxy
+    ↓
+[402 Payment Required]
+    ↓
+Waterfall Backend (signs payment)
+    ↓
+[Payment Signature]
+    ↓
+Retry with signature
+    ↓
+OpenRouter API
+    ↓
+AI Model Response
+```
+
+## Configuration
+
+### Environment Variables
+
+You can also set the API key via environment variable:
+
+```bash
+export WATERFALL_API_KEY=wf_your_api_key
+```
+
+```typescript
+const client = new WaterfallClient({
+  apiKey: process.env.WATERFALL_API_KEY,
+});
+```
+
+### Custom URLs
+
+Override default URLs if needed:
+
+```typescript
+const client = new WaterfallClient({
+  apiKey: "wf_...",
+  backendUrl: "https://your-custom-backend.convex.site",
+  proxyUrl: "https://your-custom-proxy.com",
+});
+```
+
+## Error Handling
+
+```typescript
+try {
+  const response = await client.chat.send({
+    model: "openai/gpt-4",
+    messages: [{ role: "user", content: "Hello!" }],
+  });
+} catch (error) {
+  if (error.message.includes("Invalid or missing Waterfall API key")) {
+    console.error("Check your API key");
+  } else if (error.message.includes("Payment failed")) {
+    console.error("Payment signing failed - check wallet balance");
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,395 @@
+/**
+ * Waterfall SDK Types
+ */
+/**
+ * Configuration for wallet selection and usage.
+ */
+interface WalletConfig {
+    /** Optional wallet ID to use. If undefined, uses default wallet. */
+    walletId?: string;
+}
+/**
+ * Wallet details returned from the API.
+ */
+interface Wallet {
+    /** Wallet ID (Convex ID) */
+    id: string;
+    /** Wallet name */
+    name: string;
+    /** Ethereum address */
+    address: string;
+    /** Network (e.g., "base-mainnet", "base-sepolia") */
+    network: string;
+    /** Chain identifier */
+    chain: string;
+    /** Whether this is the default wallet */
+    isDefault?: boolean;
+}
+/**
+ * Payment required response from x402 proxy.
+ */
+interface PaymentRequired {
+    [key: string]: unknown;
+}
+/**
+ * Payment signature response from backend.
+ */
+interface PaymentSignatureResponse {
+    success: boolean;
+    signature?: string;
+    payment_signature?: string;
+    error?: string;
+}
+/**
+ * Options for creating a WaterfallClient.
+ */
+interface WaterfallClientOptions {
+    /** Waterfall API key (wf_...) for authentication */
+    apiKey?: string;
+    /** Optional wallet ID to use for payments */
+    walletId?: string;
+    /** Waterfall backend URL (defaults to Convex deployment) */
+    backendUrl?: string;
+    /** x402 proxy URL (defaults to X402_PROXY_URL) */
+    proxyUrl?: string;
+    /** Legacy parameter name (use apiKey instead) */
+    x402ApiKey?: string;
+}
+/**
+ * Options for creating a wallet.
+ */
+interface CreateWalletOptions {
+    /** Name for the wallet */
+    name: string;
+    /** Optional team ID to create wallet under */
+    teamId?: string;
+    /** If true, creates on Base Sepolia testnet */
+    useTestnet?: boolean;
+}
+/**
+ * Chat message format (OpenAI compatible).
+ */
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | "function" | "tool";
+    content: string | null;
+    name?: string;
+    function_call?: {
+        name: string;
+        arguments: string;
+    };
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+/**
+ * Chat completion request options.
+ */
+interface ChatCompletionOptions {
+    /** Model to use (e.g., "openai/gpt-4", "anthropic/claude-3-opus") */
+    model: string;
+    /** Messages for the conversation */
+    messages: ChatMessage[];
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for sampling */
+    temperature?: number;
+    /** Top-p sampling */
+    topP?: number;
+    /** Stop sequences */
+    stop?: string | string[];
+    /** Whether to stream the response */
+    stream?: boolean;
+    /** Frequency penalty */
+    frequencyPenalty?: number;
+    /** Presence penalty */
+    presencePenalty?: number;
+    /** Number of completions to generate */
+    n?: number;
+    /** User identifier */
+    user?: string;
+}
+/**
+ * Chat completion response choice.
+ */
+interface ChatCompletionChoice {
+    index: number;
+    message: {
+        role: "assistant";
+        content: string | null;
+        function_call?: {
+            name: string;
+            arguments: string;
+        };
+        tool_calls?: Array<{
+            id: string;
+            type: "function";
+            function: {
+                name: string;
+                arguments: string;
+            };
+        }>;
+    };
+    finish_reason: string | null;
+}
+/**
+ * Chat completion response.
+ */
+interface ChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+
+/**
+ * Wallet configuration and management for Waterfall client.
+ */
+
+/**
+ * Manages wallet operations and communication with Waterfall/Convex backend.
+ */
+declare class WalletManager {
+    private backendUrl?;
+    private apiKey?;
+    /**
+     * Initialize wallet manager.
+     *
+     * @param backendUrl - URL of the Waterfall Convex backend (e.g., https://xxx.convex.site)
+     * @param apiKey - Waterfall API key (wf_...) for authentication
+     */
+    constructor(backendUrl?: string, apiKey?: string);
+    /**
+     * Get authorization headers for Waterfall API requests.
+     */
+    private getAuthHeaders;
+    /**
+     * Construct full API URL.
+     */
+    private apiUrl;
+    /**
+     * List all wallets for the authenticated user.
+     *
+     * @param chain - Optional chain/network filter (e.g., "base-sepolia", "base-mainnet")
+     * @returns List of wallet objects
+     */
+    listWallets(chain?: string): Promise<Wallet[]>;
+    /**
+     * Get the default wallet ID.
+     *
+     * @param chain - Optional chain/network filter to get default for specific chain
+     * @returns Default wallet ID or undefined if not available
+     */
+    getDefaultWallet(chain?: string): Promise<string | undefined>;
+    /**
+     * Get wallet ID by name.
+     *
+     * @param name - Name of the wallet
+     * @returns Wallet ID or undefined if not found
+     */
+    getWalletByName(name: string): Promise<string | undefined>;
+    /**
+     * Get wallet details by ID.
+     *
+     * @param walletId - Wallet ID (Convex ID, Coinbase ID, or address)
+     * @returns Wallet object or undefined if not found
+     */
+    getWallet(walletId: string): Promise<Wallet | undefined>;
+    /**
+     * Create a new wallet on the Base network.
+     *
+     * @param options - Wallet creation options
+     * @returns Created wallet details including id and address
+     * @throws Error if creation fails
+     */
+    createWallet(options: CreateWalletOptions): Promise<Wallet>;
+    /**
+     * Sign data using the specified wallet.
+     *
+     * @param _data - Data to sign
+     * @param _walletId - Optional wallet ID. If undefined, uses default wallet.
+     * @returns Signature string
+     *
+     * Note: For x402 payments, the SDK handles signing automatically via
+     * the wallet-pay endpoint. This method is for custom signing needs.
+     */
+    signData(_data: Uint8Array, _walletId?: string): Promise<string>;
+    /**
+     * Close the manager (no-op in TypeScript, included for API compatibility).
+     */
+    close(): void;
+}
+
+/**
+ * Waterfall client - OpenRouter with x402 payment integration.
+ */
+
+/** Default Waterfall Convex backend URL */
+declare const DEFAULT_BACKEND_URL = "https://marvelous-wolf-471.convex.site";
+/** Default x402 proxy URL for OpenRouter */
+declare const X402_PROXY_URL = "https://rishabhspro.x402instant.com";
+/**
+ * Chat interface with x402 payment handling.
+ * Uses native Node.js https module to preserve header casing.
+ */
+declare class X402Chat {
+    private client;
+    constructor(client: WaterfallClient);
+    /**
+     * Make a request to the x402 proxy with automatic payment handling.
+     */
+    private makeRequest;
+    /**
+     * Send a chat completion request.
+     *
+     * @param options - Chat completion options
+     * @returns Chat completion response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.chat.send({
+     *   model: "openai/gpt-3.5-turbo",
+     *   messages: [{ role: "user", content: "Hello!" }],
+     * });
+     * ```
+     */
+    send(options: ChatCompletionOptions): Promise<ChatCompletionResponse>;
+    /**
+     * Send a streaming chat completion request.
+     * Note: Streaming is not yet fully implemented with native https.
+     *
+     * @param options - Chat completion options
+     * @returns Chat completion response (non-streaming for now)
+     */
+    stream(options: Omit<ChatCompletionOptions, "stream">): Promise<ChatCompletionResponse>;
+}
+/**
+ * Waterfall client for x402 payments with OpenRouter.
+ *
+ * Provides direct access to OpenRouter's chat API with automatic
+ * payment signature handling via the x402 proxy.
+ *
+ * @example
+ * ```typescript
+ * // Initialize with your Waterfall API key
+ * const client = new WaterfallClient({ apiKey: "wf_xxxxxxxx_..." });
+ *
+ * // Configure wallet (optional - uses default if not specified)
+ * await client.configureWallet({ walletName: "My Wallet" });
+ *
+ * // Use OpenRouter with automatic payment handling
+ * const response = await client.chat.send({
+ *   model: "openai/gpt-3.5-turbo",
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * });
+ * ```
+ */
+declare class WaterfallClient {
+    /** Waterfall API key */
+    readonly apiKey?: string;
+    /** Legacy alias for apiKey */
+    readonly x402ApiKey?: string;
+    /** Waterfall backend URL */
+    readonly backendUrl: string;
+    /** x402 proxy URL */
+    readonly proxyUrl: string;
+    /** Wallet configuration */
+    walletConfig: WalletConfig;
+    /** Wallet manager instance */
+    readonly walletManager: WalletManager;
+    /** Lazy-initialized chat interface */
+    private _chat?;
+    /**
+     * Initialize Waterfall client.
+     *
+     * @param options - Client configuration options
+     */
+    constructor(options?: WaterfallClientOptions);
+    /**
+     * Configure the wallet to use for signing.
+     *
+     * @param options - Wallet configuration options
+     * @returns This client instance for method chaining
+     *
+     * If neither walletId nor walletName provided, fetches the default wallet.
+     */
+    configureWallet(options?: {
+        walletId?: string;
+        walletName?: string;
+    }): Promise<WaterfallClient>;
+    /**
+     * List all wallets associated with your API key.
+     *
+     * @returns List of wallet objects
+     */
+    listWallets(): Promise<Wallet[]>;
+    /**
+     * Create a new wallet on the Base network.
+     *
+     * @param options - Wallet creation options
+     * @returns Created wallet details including id and address
+     */
+    createWallet(options: CreateWalletOptions): Promise<Wallet>;
+    /**
+     * Sign a payment via Waterfall wallet-pay endpoint.
+     *
+     * @internal
+     * @param paymentRequired - Payment required data from 402 response
+     * @returns Payment signature
+     */
+    signPayment(paymentRequired: PaymentRequired): Promise<string>;
+    /**
+     * Access OpenRouter chat API with automatic x402 payment handling.
+     *
+     * @returns Chat interface with send() and stream() methods
+     *
+     * @example
+     * ```typescript
+     * const response = await client.chat.send({
+     *   model: "openai/gpt-3.5-turbo",
+     *   messages: [{ role: "user", content: "Hello!" }],
+     * });
+     * ```
+     */
+    get chat(): X402Chat;
+    /**
+     * Close the client and clean up resources.
+     */
+    close(): void;
+}
+/**
+ * Create a configured Waterfall client.
+ *
+ * @param apiKey - Your Waterfall API key (wf_...)
+ * @param walletName - Optional wallet name to use (uses default if not specified)
+ * @param backendUrl - Optional custom backend URL
+ * @returns Configured WaterfallClient ready for use
+ *
+ * @example
+ * ```typescript
+ * const client = await createClient("wf_abc123_xyz789");
+ * const response = await client.chat.send({
+ *   model: "openai/gpt-3.5-turbo",
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * });
+ * ```
+ */
+declare function createClient(apiKey: string, walletName?: string, backendUrl?: string): Promise<WaterfallClient>;
+
+/**
+ * Waterfall - TypeScript SDK for x402 payments with OpenRouter.
+ */
+
+declare const VERSION = "0.3.0";
+
+export { type ChatCompletionChoice, type ChatCompletionOptions, type ChatCompletionResponse, type ChatMessage, type CreateWalletOptions, DEFAULT_BACKEND_URL, type PaymentRequired, type PaymentSignatureResponse, VERSION, type Wallet, type WalletConfig, WalletManager, WaterfallClient, type WaterfallClientOptions, X402_PROXY_URL, createClient };