@haven_ai/sdk 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -48,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;
@@ -113,6 +113,109 @@ interface X402Receipt {
     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;
@@ -122,7 +225,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);
@@ -141,6 +251,7 @@ declare class HavenClient {
     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);
@@ -179,6 +290,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).
      */
@@ -192,8 +310,10 @@ declare class HavenClient {
      *
      * Requires `delegateKey` to be set in the client config.
      */
-    authorizeX402(paymentRequired: X402PaymentRequired): Promise<X402Receipt>;
+    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.
      *
@@ -207,9 +327,23 @@ declare class HavenClient {
      *
      * Requires `delegateKey` to be set in the client config.
      */
-    fetch(url: string, init?: RequestInit): Promise<Response>;
+    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;
     /**
@@ -225,10 +359,14 @@ declare class HavenClient {
      * ```
      */
     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;
 }
 
 /**
@@ -353,4 +491,9 @@ declare function encodePaymentProof(receipt: {
     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, parsePaymentRequiredResponse, 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 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 };

package/dist/index.d.ts

@@ -48,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;
@@ -113,6 +113,109 @@ interface X402Receipt {
     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;
@@ -122,7 +225,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);
@@ -141,6 +251,7 @@ declare class HavenClient {
     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);
@@ -179,6 +290,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).
      */
@@ -192,8 +310,10 @@ declare class HavenClient {
      *
      * Requires `delegateKey` to be set in the client config.
      */
-    authorizeX402(paymentRequired: X402PaymentRequired): Promise<X402Receipt>;
+    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.
      *
@@ -207,9 +327,23 @@ declare class HavenClient {
      *
      * Requires `delegateKey` to be set in the client config.
      */
-    fetch(url: string, init?: RequestInit): Promise<Response>;
+    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;
     /**
@@ -225,10 +359,14 @@ declare class HavenClient {
      * ```
      */
     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;
 }
 
 /**
@@ -353,4 +491,9 @@ declare function encodePaymentProof(receipt: {
     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, parsePaymentRequiredResponse, 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 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 };