@haven_ai/sdk 0.1.1 → 0.1.2

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;
@@ -114,6 +114,72 @@ interface X402Receipt {
     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;
     readonly statusCode?: number | undefined;
@@ -122,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);
@@ -141,6 +214,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 +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).
      */
@@ -208,8 +289,17 @@ 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;
     /**
@@ -225,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;
 }
 
 /**
@@ -353,4 +445,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 SignData, 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;
@@ -114,6 +114,72 @@ interface X402Receipt {
     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;
     readonly statusCode?: number | undefined;
@@ -122,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);
@@ -141,6 +214,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 +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).
      */
@@ -208,8 +289,17 @@ 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;
     /**
@@ -225,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;
 }
 
 /**
@@ -353,4 +445,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 SignData, type X402PaymentOption, type X402PaymentRequired, type X402Receipt, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };