@haven_ai/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+interface HavenClientConfig {
+    /** Haven API key (sk_agent_xxx) */
+    apiKey: string;
+    /** Agent's delegate EOA private key. If provided, the SDK handles signing automatically. */
+    delegateKey?: string;
+    /** Haven API base URL (default: http://localhost:3001) */
+    baseUrl?: string;
+    /** Timeout in ms for individual HTTP requests (default: 30000) */
+    requestTimeout?: number;
+    /** Timeout in ms when polling for tx confirmation (default: 90000) */
+    confirmationTimeout?: number;
+    /** Polling interval in ms when waiting for confirmation (default: 3000) */
+    pollingInterval?: number;
+}
+interface PaymentRequest {
+    /** Token symbol: "EURe", "USDC.e", or "xDAI" */
+    token: string;
+    /** Amount as a decimal string, e.g. "5.00" */
+    amount: string;
+    /** Recipient Ethereum address (0x...) */
+    to: string;
+}
+interface SignData {
+    /** The hash to sign (keccak256, 0x-prefixed) */
+    hash: string;
+    /** Breakdown of values that were hashed — useful for debugging */
+    components: {
+        safe: string;
+        token: string;
+        to: string;
+        amount: string;
+        payment_token: string;
+        payment: string;
+        nonce: number;
+    };
+    /** Human-readable signing instructions */
+    instructions: string;
+}
+interface PaymentIntent {
+    /** Unique payment ID */
+    paymentId: string;
+    /** Current status */
+    status: 'pending_signature';
+    /** ISO 8601 expiry timestamp */
+    expiresAt: string;
+    /** Data needed to sign the payment */
+    signData: SignData;
+}
+type PaymentStatus = 'pending_signature' | 'submitted' | 'confirmed' | 'expired' | 'failed';
+interface PaymentResult {
+    /** Unique payment ID */
+    paymentId: string;
+    /** Final status */
+    status: PaymentStatus;
+    /** Token that was sent */
+    token: string;
+    /** Amount that was sent (human-readable) */
+    amount: string;
+    /** Recipient address */
+    to: string;
+    /** On-chain transaction hash (present when confirmed) */
+    txHash: string | null;
+    /** Error message (present when failed) */
+    errorMessage: string | null;
+    /** Block explorer URL for the transaction (chain-dependent) */
+    explorerUrl: string | null;
+    /** ISO 8601 timestamps */
+    createdAt: string;
+    signedAt: string | null;
+    submittedAt: string | null;
+    confirmedAt: string | null;
+    expiresAt: string;
+}
+/** Payment requirements from an HTTP 402 response (x402 protocol). */
+interface X402PaymentRequired {
+    x402Version: number;
+    resource: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: X402PaymentOption[];
+    error?: string;
+}
+/** A single payment option from x402 PaymentRequired. */
+interface X402PaymentOption {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+/** Receipt returned after a successful x402 payment. */
+interface X402Receipt {
+    success: boolean;
+    paymentId: string;
+    txHash: string;
+    token: string;
+    amount: string;
+    to: string;
+    resourceUrl: string;
+    explorerUrl: string;
+}
+declare class HavenError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    readonly paymentId?: string | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, paymentId?: string | undefined);
+}
+declare class HavenApiError extends HavenError {
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, body?: unknown | undefined);
+}
+declare class HavenSigningError extends HavenError {
+    constructor(message: string);
+}
+declare class HavenTimeoutError extends HavenError {
+    constructor(paymentId: string);
+}
+
+declare class HavenClient {
+    private readonly apiKey;
+    private readonly delegateKey;
+    private readonly baseUrl;
+    private readonly requestTimeout;
+    private readonly confirmationTimeout;
+    private readonly pollingInterval;
+    /** Delegate address derived from the private key (if provided) */
+    readonly delegateAddress: string | undefined;
+    constructor(config: HavenClientConfig);
+    /**
+     * Send a payment in one call.
+     *
+     * Creates the intent, signs the hash, submits the signature,
+     * and polls until confirmed (or throws on failure/timeout).
+     *
+     * Requires `delegateKey` to be set in the client config.
+     */
+    pay(request: PaymentRequest): Promise<PaymentResult>;
+    /**
+     * Step 1: Create a payment intent.
+     *
+     * Returns the intent with the hash to sign.
+     */
+    createIntent(request: PaymentRequest): Promise<PaymentIntent>;
+    /**
+     * Step 2: Sign a hash with the delegate key.
+     *
+     * Returns the 65-byte signature (0x-prefixed).
+     * Requires `delegateKey` to be set in the client config.
+     */
+    sign(hash: string): string;
+    /**
+     * Step 3: Submit a signature to execute the payment.
+     *
+     * The signature can come from `client.sign()` or from external signing.
+     */
+    submitSignature(paymentId: string, signature: string): Promise<{
+        status: string;
+        txHash?: string;
+    }>;
+    /**
+     * Get the current status of a payment.
+     */
+    getPayment(paymentId: string): Promise<PaymentResult>;
+    /**
+     * Poll until a payment reaches a terminal status (confirmed, failed, expired).
+     */
+    waitForConfirmation(paymentId: string): Promise<PaymentResult>;
+    /**
+     * Authorize an x402 payment.
+     *
+     * Takes the parsed PaymentRequired from a 402 response, selects a
+     * compatible payment option, signs and executes the payment through Haven.
+     *
+     * Requires `delegateKey` to be set in the client config.
+     */
+    authorizeX402(paymentRequired: X402PaymentRequired): Promise<X402Receipt>;
+    /**
+     * Fetch wrapper that automatically handles HTTP 402 responses.
+     *
+     * Works like the standard `fetch()` but intercepts 402 responses,
+     * pays via x402 through Haven, and retries the request.
+     *
+     * ```ts
+     * const response = await haven.fetch('https://paid-api.com/data')
+     * const data = await response.json()
+     * ```
+     *
+     * Requires `delegateKey` to be set in the client config.
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Execute a tool call by name and input.
+     *
+     * Designed to plug directly into agent tool-call handlers:
+     *
+     * ```ts
+     * if (block.type === 'tool_use') {
+     *   const result = await haven.executeTool(block.name, block.input)
+     *   // send result back to the model
+     * }
+     * ```
+     */
+    executeTool(toolName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private post;
+    private get;
+    private request;
+    private mapPaymentResult;
+}
+
+/**
+ * Pre-built tool definitions for AI agent frameworks.
+ *
+ * These definitions describe the `make_payment` and `get_payment_status` tools
+ * in the formats expected by Claude (Anthropic) and OpenAI.
+ *
+ * Usage with Claude:
+ *   const response = await anthropic.messages.create({
+ *     tools: havenTools.claude(),
+ *     ...
+ *   })
+ *
+ * Usage with OpenAI:
+ *   const response = await openai.chat.completions.create({
+ *     tools: havenTools.openai(),
+ *     ...
+ *   })
+ */
+interface ClaudeTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required: readonly string[];
+    };
+}
+declare function claudeTools(): ClaudeTool[];
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required: readonly string[];
+        };
+    };
+}
+declare function openaiTools(): OpenAITool[];
+declare const havenTools: {
+    /** Tool definitions in Anthropic/Claude format */
+    claude: typeof claudeTools;
+    /** Tool definitions in OpenAI function-calling format */
+    openai: typeof openaiTools;
+};
+
+/**
+ * Sign a hash using raw ECDSA (no Ethereum message prefix).
+ *
+ * This matches what Safe's AllowanceModule `checkSignature` expects —
+ * a direct ecrecover over the hash, NOT the "\x19Ethereum Signed Message" variant.
+ *
+ * Uses ethers.SigningKey.sign() instead of wallet.signMessage() to avoid the prefix.
+ */
+declare function signHash(privateKey: string, hash: string): string;
+/**
+ * Derive the Ethereum address from a private key.
+ */
+declare function addressFromKey(privateKey: string): string;
+/**
+ * Verify that a signature over a hash recovers to the expected address.
+ */
+declare function verifySignature(hash: string, signature: string, expectedAddress: string): boolean;
+
+/**
+ * x402 protocol support for the Haven SDK.
+ *
+ * Provides:
+ * - parsePaymentRequired() — extract payment requirements from a 402 response
+ * - encodePaymentProof()   — encode a receipt as a PAYMENT-SIGNATURE header
+ *
+ * The main authorizeX402() and fetchWithPayment() are methods on HavenClient
+ * (see client.ts) since they need API access and signing.
+ */
+
+/**
+ * Parse an HTTP 402 response into x402 PaymentRequired data.
+ *
+ * Supports:
+ * - v2: PAYMENT-REQUIRED header (base64 JSON)
+ * - v1 fallback: X-PAYMENT header or response body
+ */
+declare function parsePaymentRequired(response: Response): X402PaymentRequired;
+/**
+ * Select the best payment option from the x402 accepts array.
+ *
+ * Preference order:
+ * 1. Option on a Haven-supported network with a known token
+ * 2. Any option on a Haven-supported network
+ * 3. null — no compatible option
+ */
+declare function selectPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/**
+ * Encode a payment receipt as a base64 PAYMENT-SIGNATURE header value.
+ *
+ * This follows the x402 v2 protocol — the server's facilitator will
+ * verify the on-chain transaction referenced by tx_hash.
+ */
+declare function encodePaymentProof(receipt: {
+    txHash: string;
+    paymentId: string;
+    token: string;
+    amount: string;
+    to: string;
+}): string;
+
+export { type ClaudeTool, HavenApiError, HavenClient, type HavenClientConfig, HavenError, HavenSigningError, HavenTimeoutError, type OpenAITool, type PaymentIntent, type PaymentRequest, type PaymentResult, type PaymentStatus, type SignData, type X402PaymentOption, type X402PaymentRequired, type X402Receipt, addressFromKey, encodePaymentProof, havenTools, parsePaymentRequired, selectPaymentOption, signHash, verifySignature };