@haven_ai/sdk 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -5,6 +5,8 @@ interface HavenClientConfig {
     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) */
@@ -46,7 +48,7 @@ interface PaymentIntent {
     /** Data needed to sign the payment */
     signData: SignData;
 }
-type PaymentStatus = 'pending_signature' | 'submitted' | 'confirmed' | 'expired' | 'failed';
+type PaymentStatus = 'pending_signature' | 'submitted' | 'confirmed' | 'pending_approval' | 'approved' | 'proposed' | 'executed' | 'rejected' | 'expired' | 'failed';
 interface PaymentResult {
     /** Unique payment ID */
     paymentId: string;
@@ -87,6 +89,10 @@ interface X402PaymentOption {
     scheme: string;
     network: string;
     amount: string;
+    maxAmountRequired?: string;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
     asset: string;
     payTo: string;
     maxTimeoutSeconds: number;
@@ -102,6 +108,77 @@ interface X402Receipt {
     to: string;
     resourceUrl: string;
     explorerUrl: string;
+    accepted?: X402PaymentOption;
+    paymentHeader?: string;
+    merchantTo?: string | null;
+    payer?: string;
+    chainId?: number;
+}
+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;
@@ -111,7 +188,14 @@ declare class HavenError extends Error {
 }
 declare class HavenApiError extends HavenError {
     readonly body?: unknown | undefined;
-    constructor(message: string, statusCode: number, 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);
@@ -124,9 +208,13 @@ 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);
@@ -165,6 +253,13 @@ declare class HavenClient {
      * 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).
      */
@@ -172,12 +267,14 @@ declare class HavenClient {
     /**
      * Authorize an x402 payment.
      *
-     * Takes the parsed PaymentRequired from a 402 response, selects a
-     * compatible payment option, signs and executes the payment through Haven.
+     * 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): Promise<X402Receipt>;
+    private authorizeStandardX402;
     /**
      * Fetch wrapper that automatically handles HTTP 402 responses.
      *
@@ -192,6 +289,19 @@ declare class HavenClient {
      * Requires `delegateKey` to be set in the client config.
      */
     fetch(url: string, init?: RequestInit): Promise<Response>;
+    authorizeMachinePayment(challenge: MachinePaymentChallenge): Promise<MachinePaymentReceipt>;
+    private authorizeMppDemoPayment;
+    private fetchWithMachinePayment;
+    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.
      *
@@ -205,10 +315,12 @@ declare class HavenClient {
      * ```
      */
     executeTool(toolName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private toolError;
     private post;
     private get;
     private request;
     private mapPaymentResult;
+    private mapPaymentStatusResult;
 }
 
 /**
@@ -282,6 +394,7 @@ declare function verifySignature(hash: string, signature: string, expectedAddres
  *
  * 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
@@ -296,6 +409,15 @@ declare function verifySignature(hash: string, signature: string, expectedAddres
  * - 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.
  *
@@ -317,6 +439,15 @@ declare function encodePaymentProof(receipt: {
     token: string;
     amount: string;
     to: string;
+    resourceUrl?: string;
+    accepted?: X402PaymentOption;
+    payer?: string;
+    chainId?: number;
 }): 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 };
+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 SignData, type X402PaymentOption, type X402PaymentRequired, type X402Receipt, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };

package/dist/index.d.ts

@@ -5,6 +5,8 @@ interface HavenClientConfig {
     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) */
@@ -46,7 +48,7 @@ interface PaymentIntent {
     /** Data needed to sign the payment */
     signData: SignData;
 }
-type PaymentStatus = 'pending_signature' | 'submitted' | 'confirmed' | 'expired' | 'failed';
+type PaymentStatus = 'pending_signature' | 'submitted' | 'confirmed' | 'pending_approval' | 'approved' | 'proposed' | 'executed' | 'rejected' | 'expired' | 'failed';
 interface PaymentResult {
     /** Unique payment ID */
     paymentId: string;
@@ -87,6 +89,10 @@ interface X402PaymentOption {
     scheme: string;
     network: string;
     amount: string;
+    maxAmountRequired?: string;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
     asset: string;
     payTo: string;
     maxTimeoutSeconds: number;
@@ -102,6 +108,77 @@ interface X402Receipt {
     to: string;
     resourceUrl: string;
     explorerUrl: string;
+    accepted?: X402PaymentOption;
+    paymentHeader?: string;
+    merchantTo?: string | null;
+    payer?: string;
+    chainId?: number;
+}
+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;
@@ -111,7 +188,14 @@ declare class HavenError extends Error {
 }
 declare class HavenApiError extends HavenError {
     readonly body?: unknown | undefined;
-    constructor(message: string, statusCode: number, 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);
@@ -124,9 +208,13 @@ 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);
@@ -165,6 +253,13 @@ declare class HavenClient {
      * 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).
      */
@@ -172,12 +267,14 @@ declare class HavenClient {
     /**
      * Authorize an x402 payment.
      *
-     * Takes the parsed PaymentRequired from a 402 response, selects a
-     * compatible payment option, signs and executes the payment through Haven.
+     * 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): Promise<X402Receipt>;
+    private authorizeStandardX402;
     /**
      * Fetch wrapper that automatically handles HTTP 402 responses.
      *
@@ -192,6 +289,19 @@ declare class HavenClient {
      * Requires `delegateKey` to be set in the client config.
      */
     fetch(url: string, init?: RequestInit): Promise<Response>;
+    authorizeMachinePayment(challenge: MachinePaymentChallenge): Promise<MachinePaymentReceipt>;
+    private authorizeMppDemoPayment;
+    private fetchWithMachinePayment;
+    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.
      *
@@ -205,10 +315,12 @@ declare class HavenClient {
      * ```
      */
     executeTool(toolName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private toolError;
     private post;
     private get;
     private request;
     private mapPaymentResult;
+    private mapPaymentStatusResult;
 }
 
 /**
@@ -282,6 +394,7 @@ declare function verifySignature(hash: string, signature: string, expectedAddres
  *
  * 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
@@ -296,6 +409,15 @@ declare function verifySignature(hash: string, signature: string, expectedAddres
  * - 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.
  *
@@ -317,6 +439,15 @@ declare function encodePaymentProof(receipt: {
     token: string;
     amount: string;
     to: string;
+    resourceUrl?: string;
+    accepted?: X402PaymentOption;
+    payer?: string;
+    chainId?: number;
 }): 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 };
+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 SignData, type X402PaymentOption, type X402PaymentRequired, type X402Receipt, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };