@haven_ai/sdk 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,499 +0,0 @@
-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;
-    /** Optional wallet identity to send as the x402-wallet header. */
-    x402Wallet?: 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' | 'pending_approval' | 'approved' | 'proposed' | 'executed' | 'rejected' | '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;
-    maxAmountRequired?: string;
-    resource?: string;
-    description?: string;
-    mimeType?: 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;
-    accepted?: X402PaymentOption;
-    paymentHeader?: string;
-    merchantTo?: string | null;
-    payer?: string;
-    chainId?: number;
-    haven?: {
-        paymentId: string;
-        fundingTxHash: string;
-        fundingExplorerUrl: string;
-    };
-    merchant?: {
-        payTo: string | null;
-        settlementTxHash?: string | null;
-        settlementExplorerUrl?: string | null;
-    };
-    x402?: {
-        amount: string;
-        token: string;
-        network: string;
-        asset: string;
-        resource: string;
-    };
-}
-interface X402AuthorizationOptions {
-    /** Stable caller-supplied key for this user intent. Prevents duplicate approvals across fresh 402 quotes. */
-    idempotencyKey?: string;
-}
-interface ResumeAuthorizedX402Input extends X402AuthorizationOptions {
-    /** Payment or approval request ID returned by authorizeX402 / haven.fetch. */
-    paymentId: string;
-    /** Original or freshly parsed x402 requirements for the merchant retry. */
-    paymentRequired: X402PaymentRequired;
-}
-interface ResumeX402PaymentInput extends X402AuthorizationOptions {
-    /** Payment or approval request ID returned by authorizeX402 / haven.fetch. */
-    paymentId: string;
-    /** Original paid URL. If paymentRequired is omitted, Haven will call it once to re-read the 402 challenge. */
-    url: string;
-    /** Original fetch options. Reused for the 402 probe and final merchant retry. */
-    init?: RequestInit;
-    /** Original or freshly parsed x402 requirements. Supplying this avoids an extra merchant 402 probe. */
-    paymentRequired?: X402PaymentRequired;
-}
-type MachinePaymentRail = 'x402' | 'mpp_demo' | 'mpp_crypto' | 'stripe_deposit' | 'spt';
-interface MachinePaymentChallenge {
-    rail: MachinePaymentRail;
-    version: string;
-    challengeId: string;
-    resource: string;
-    description: string;
-    network: {
-        chainId: number;
-        name: 'base';
-    };
-    asset: {
-        symbol: 'USDC';
-        address: string;
-        decimals: 6;
-    };
-    amount: {
-        display: string;
-        atomic: string;
-    };
-    recipient: string;
-    expiresAt: string;
-    metadata?: Record<string, unknown>;
-}
-interface MachinePaymentReceipt {
-    success: boolean;
-    rail: MachinePaymentRail;
-    paymentId: string;
-    challengeId: string;
-    txHash: string;
-    token: string;
-    amount: string;
-    to: string;
-    resourceUrl: string;
-    explorerUrl: string;
-    payer?: string;
-    chainId?: number;
-    proofHeader: string;
-}
-type PaymentStateKind = 'payment_intent' | 'approval_request';
-type PaymentPhase = 'agent_signature_required' | 'payment_submitted' | 'payment_confirmed' | 'user_approval_required' | 'user_execution_required' | 'waiting_for_additional_approvals' | 'funding_sent' | 'rejected' | 'expired' | 'failed';
-type PaymentNextAction = 'sign_and_submit_payment' | 'check_status_later' | 'none' | 'wait_for_user_approval' | 'wait_for_user_to_complete_payment' | 'retry_original_x402_request' | 'stop_and_tell_user' | 'request_again_if_user_still_wants_it';
-interface PaymentStatusResult {
-    paymentId: string;
-    kind: PaymentStateKind;
-    rail: string;
-    status: PaymentStatus | string;
-    phase: PaymentPhase;
-    nextAction: PaymentNextAction;
-    amount: string;
-    token: string;
-    resourceUrl: string | null;
-    merchantAddress: string | null;
-    txHash: string | null;
-    expiresAt: string;
-    chainId: number;
-    message: string;
-}
-interface PendingApproval extends PaymentStatusResult {
-    kind: 'approval_request';
-    status: 'pending_approval' | 'pending' | string;
-    phase: 'user_approval_required';
-    nextAction: 'wait_for_user_approval';
-    requested?: string;
-    remaining?: string | null;
-}
-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, paymentId?: string);
-}
-declare class HavenPaymentStateError extends HavenApiError {
-    readonly state: PaymentStatusResult;
-    constructor(message: string, statusCode: number, state: PaymentStatusResult, body?: unknown);
-    get status(): string;
-    get phase(): PaymentPhase;
-    get nextAction(): PaymentNextAction;
-}
-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 x402Wallet;
-    private readonly requestTimeout;
-    private readonly confirmationTimeout;
-    private readonly pollingInterval;
-    private readonly inFlightX402;
-    private readonly x402ReceiptCache;
-    private readonly inFlightMachinePayments;
-    /** 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>;
-    /**
-     * Get agent-actionable status for a payment intent or approval request.
-     *
-     * Use this for IDs returned by agent tools and machine-payment/x402 flows.
-     * `getPayment()` remains available for payment-intent-only integrations.
-     */
-    getPaymentStatus(paymentId: string): Promise<PaymentStatusResult>;
-    /**
-     * 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
-     * option, funds the delegate wallet through Haven, and returns the standard
-     * x402 header that the merchant can verify and settle.
-     *
-     * Requires `delegateKey` to be set in the client config.
-     */
-    authorizeX402(paymentRequired: X402PaymentRequired, options?: X402AuthorizationOptions): Promise<X402Receipt>;
-    private authorizeStandardX402;
-    resumeAuthorizedX402(input: ResumeAuthorizedX402Input): Promise<X402Receipt>;
-    resumeX402Payment(input: ResumeX402PaymentInput): Promise<Response>;
-    /**
-     * 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, options?: X402AuthorizationOptions): Promise<Response>;
-    private retryX402Request;
-    authorizeMachinePayment(challenge: MachinePaymentChallenge): Promise<MachinePaymentReceipt>;
-    private authorizeMppDemoPayment;
-    private fetchWithMachinePayment;
-    private assertCanResumeX402;
-    private mapX402ReceiptFromAuthorization;
-    private mapX402ReceiptFromStatus;
-    private buildX402Receipt;
-    private createStandardX402Header;
-    private cacheX402Receipt;
-    private mapMachinePaymentReceipt;
-    private recordMerchantRetryRejected;
-    private reportMachinePaymentEvidence;
-    private throwIfNonSignableAuthorizationState;
-    private throwPaymentStateError;
-    private paymentStateFromRaw;
-    private x402PayerAddress;
-    private withX402Wallet;
-    /**
-     * 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 toolX402PaymentRequired;
-    private x402ToolReceipt;
-    private toolError;
-    private post;
-    private get;
-    private request;
-    private mapPaymentResult;
-    private mapPaymentStatusResult;
-}
-
-/**
- * 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
- * - parsePaymentRequiredResponse() — async parser with JSON body fallback
- * - 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;
-/**
- * Parse an HTTP 402 response into x402 PaymentRequired data.
- *
- * Soundside and other Bazaar-style MCP endpoints return the PaymentRequired
- * object in the JSON body, while older Haven demos and many x402 examples use
- * base64 headers. This keeps the synchronous header parser intact and adds the
- * body fallback needed for those endpoints.
- */
-declare function parsePaymentRequiredResponse(response: Response): Promise<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;
-    resourceUrl?: string;
-    accepted?: X402PaymentOption;
-    payer?: string;
-    chainId?: number;
-}): string;
-
-declare function parseMachinePaymentChallenge(response: Response): MachinePaymentChallenge;
-declare function parseMachinePaymentChallengeResponse(response: Response): Promise<MachinePaymentChallenge>;
-declare function buildMachinePaymentIdempotencyKey(challenge: MachinePaymentChallenge): string;
-declare function encodeMachinePaymentProof(receipt: Omit<MachinePaymentReceipt, 'proofHeader'>): string;
-
-export { type ClaudeTool, HavenApiError, HavenClient, type HavenClientConfig, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedX402Input, type ResumeX402PaymentInput, type SignData, type X402AuthorizationOptions, type X402PaymentOption, type X402PaymentRequired, type X402Receipt, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };