@haven_ai/sdk 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -13,6 +13,15 @@ interface HavenClientConfig {
     confirmationTimeout?: number;
     /** Polling interval in ms when waiting for confirmation (default: 3000) */
     pollingInterval?: number;
+    /**
+     * Extra headers to attach to every request to the Haven API.
+     *
+     * Used by the MCP server to tag requests with `X-Haven-MCP-Tool: <name>`
+     * so the backend can record an audit-log entry per tool invocation. Has
+     * no effect on outbound merchant requests (x402 / MPP) — those are
+     * standard HTTP and never carry Haven-internal headers.
+     */
+    defaultHeaders?: Record<string, string>;
 }
 interface PaymentRequest {
     /** Token symbol: "EURe", "USDC.e", or "xDAI" */
@@ -135,6 +144,94 @@ interface X402AuthorizationOptions {
     /** Stable caller-supplied key for this user intent. Prevents duplicate approvals across fresh 402 quotes. */
     idempotencyKey?: string;
 }
+/** Serializable HTTP request state for retrying the same x402 merchant request. */
+interface X402RequestSnapshot {
+    url: string;
+    method: string;
+    headers: [string, string][];
+    body?: string;
+}
+/** Quote parsed from an HTTP 402 response without creating a Haven payment. */
+interface X402Quote {
+    rail: 'x402';
+    idempotencyKey: string;
+    paymentRequired: X402PaymentRequired;
+    accepted: X402PaymentOption;
+    request: X402RequestSnapshot;
+    resourceUrl: string;
+    description: string | null;
+    mimeType: string | null;
+    amountAtomic: string;
+    amount: string;
+    token: string;
+    asset: string;
+    network: string;
+    chainId: number | null;
+    merchantAddress: string;
+    maxTimeoutSeconds: number;
+}
+/** State bundle an agent can persist while waiting for manual x402 approval. */
+interface X402ResumeState {
+    rail: 'x402';
+    paymentId: string;
+    idempotencyKey: string;
+    paymentRequired: X402PaymentRequired;
+    accepted: X402PaymentOption;
+    url: string;
+    request?: X402RequestSnapshot;
+    resourceUrl: string;
+    description: string | null;
+    amountAtomic: string;
+    amount: string;
+    token: string;
+    asset: string;
+    network: string;
+    chainId: number | null;
+    merchantAddress: string;
+}
+interface MppAuthorizationOptions {
+    /** Stable caller-supplied key for this user intent. Prevents duplicate approvals across retries. */
+    idempotencyKey?: string;
+}
+/** Quote parsed from an MPP challenge without creating a Haven payment. */
+interface MppQuote {
+    rail: 'mpp';
+    paymentRail: MachinePaymentRail;
+    idempotencyKey: string;
+    challenge: MachinePaymentChallenge;
+    request: X402RequestSnapshot;
+    resourceUrl: string;
+    description: string | null;
+    amountAtomic: string;
+    amount: string;
+    token: string;
+    asset: string;
+    network: string;
+    chainId: number;
+    merchantAddress: string;
+    expiresAt: string;
+}
+/** State bundle an agent can persist while waiting for manual MPP approval. */
+interface MppResumeState {
+    rail: 'mpp';
+    paymentRail: MachinePaymentRail;
+    paymentId: string;
+    idempotencyKey: string;
+    challenge: MachinePaymentChallenge;
+    url: string;
+    request?: X402RequestSnapshot;
+    resourceUrl: string;
+    description: string | null;
+    amountAtomic: string;
+    amount: string;
+    token: string;
+    asset: string;
+    network: string;
+    chainId: number;
+    merchantAddress: string;
+    expiresAt: string;
+}
+type PaymentResumeState = X402ResumeState | MppResumeState;
 interface ResumeAuthorizedX402Input extends X402AuthorizationOptions {
     /** Payment or approval request ID returned by authorizeX402 / haven.fetch. */
     paymentId: string;
@@ -148,9 +245,29 @@ interface ResumeX402PaymentInput extends X402AuthorizationOptions {
     url: string;
     /** Original fetch options. Reused for the 402 probe and final merchant retry. */
     init?: RequestInit;
+    /** Serializable original request captured by quoteX402() / pending approval errors. */
+    request?: X402RequestSnapshot;
     /** Original or freshly parsed x402 requirements. Supplying this avoids an extra merchant 402 probe. */
     paymentRequired?: X402PaymentRequired;
 }
+interface ResumeAuthorizedMppInput extends MppAuthorizationOptions {
+    /** Payment or approval request ID returned by authorizeMachinePayment / haven.fetch. */
+    paymentId: string;
+    /** Original MPP challenge returned by the paid resource. */
+    challenge: MachinePaymentChallenge;
+}
+interface ResumeMppPaymentInput extends MppAuthorizationOptions {
+    /** Payment or approval request ID returned by authorizeMachinePayment / haven.fetch. */
+    paymentId: string;
+    /** Original paid URL. If challenge is omitted, Haven will call it once to re-read the MPP challenge. */
+    url: string;
+    /** Original fetch options. Reused for the 402 probe and final merchant retry. */
+    init?: RequestInit;
+    /** Serializable original request captured by quoteMpp() / pending approval errors. */
+    request?: X402RequestSnapshot;
+    /** Original MPP challenge. Supplying this avoids an extra paid-resource 402 probe. */
+    challenge?: MachinePaymentChallenge;
+}
 type MachinePaymentRail = 'x402' | 'mpp_demo' | 'mpp_crypto' | 'stripe_deposit' | 'spt';
 interface MachinePaymentChallenge {
     rail: MachinePaymentRail;
@@ -190,9 +307,134 @@ interface MachinePaymentReceipt {
     chainId?: number;
     proofHeader: string;
 }
+interface HavenAgent {
+    id: string;
+    name: string;
+    status: string;
+    safeAddress: string;
+    delegateAddress: string;
+    chainId: number;
+}
+interface HavenAllowance {
+    id: string;
+    tokenAddress: string;
+    tokenSymbol: string;
+    configuredAmount: string;
+    resetPeriodMin: number;
+    onchain: {
+        amount: string;
+        spent: string;
+        remaining: string;
+        effectiveSpent: string;
+        resetTimeMin: number;
+        lastResetMin: number;
+        nonce: number;
+        isResetPending: boolean;
+    };
+}
+interface HavenAllowanceSummary {
+    agentId: string;
+    safeAddress: string;
+    delegateAddress: string;
+    chainId: number;
+    allowances: HavenAllowance[];
+}
+interface HavenPaymentReceipt {
+    id: string;
+    paymentId: string;
+    rail: string;
+    proofStatus: string;
+    txHash: string;
+    chainId: number;
+    resourceUrl: string;
+    merchantAddress: string | null;
+    payerAddress: string;
+    settlementAddress: string;
+    tokenSymbol: string;
+    tokenAddress: string;
+    amountRaw: string;
+    amount: string;
+    challengeId: string | null;
+    idempotencyKey: string | null;
+    challengePayload?: Record<string, unknown> | null;
+    selectedPayment?: Record<string, unknown> | null;
+    paymentProofHeaderName: string | null;
+    protocolReceiptHeaderName: string | null;
+    protocolReceiptPayload?: Record<string, unknown> | null;
+    merchantStatus: number | null;
+    confirmedAt: string | null;
+    createdAt: string;
+    updatedAt: 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 AgentPaymentEnumSchema {
+    type: 'string';
+    enum: readonly string[];
+    description: string;
+    'x-enumDescriptions': Record<string, string>;
+}
+declare const AgentPaymentPhase: {
+    /** The agent must sign and submit the prepared payment before Haven can relay it. */
+    readonly AgentSignatureRequired: "agent_signature_required";
+    /** Haven has received the signed payment and the agent should poll for confirmation. */
+    readonly PaymentSubmitted: "payment_submitted";
+    /** The direct payment is confirmed; the agent does not need to do more for this payment id. */
+    readonly PaymentConfirmed: "payment_confirmed";
+    /** The payment needs wallet owner approval in Haven before it can continue. */
+    readonly UserApprovalRequired: "user_approval_required";
+    /** The wallet owner approved the request and still needs to complete the funding payment. */
+    readonly UserExecutionRequired: "user_execution_required";
+    /** The funding payment was proposed and is waiting for the remaining account approvals. */
+    readonly WaitingForAdditionalApprovals: "waiting_for_additional_approvals";
+    /** The Haven funding leg was sent; the agent can continue the merchant/protocol leg. */
+    readonly FundingSent: "funding_sent";
+    /** The wallet owner rejected the request; the agent should stop and tell the user. */
+    readonly Rejected: "rejected";
+    /** The payment or approval request expired before completion. */
+    readonly Expired: "expired";
+    /** Haven could not complete the payment; the agent should stop and surface the failure. */
+    readonly Failed: "failed";
+};
+type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
+declare const AgentPaymentNextAction: {
+    /** Sign with the delegate key and submit the payment to Haven. */
+    readonly SignAndSubmitPayment: "sign_and_submit_payment";
+    /** Poll getPaymentStatus later using this payment id. */
+    readonly CheckStatusLater: "check_status_later";
+    /** No further agent action is required for this payment id. */
+    readonly None: "none";
+    /** Wait for the wallet owner to approve or reject the request in Haven. */
+    readonly WaitForUserApproval: "wait_for_user_approval";
+    /** Wait for the wallet owner to finish sending the approved funding payment. */
+    readonly WaitForUserToCompletePayment: "wait_for_user_to_complete_payment";
+    /** Resume this payment id and retry the original x402 request with the merchant payment header. */
+    readonly RetryOriginalX402Request: "retry_original_x402_request";
+    /** Stop retrying this payment and tell the user what happened. */
+    readonly StopAndTellUser: "stop_and_tell_user";
+    /** Ask again only if the user still wants the payment after expiry. */
+    readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
+};
+type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+declare const AgentPaymentRail: {
+    /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
+    readonly Direct: "direct";
+    /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
+    readonly X402: "x402";
+    /** Machine Payment Protocol flow. */
+    readonly Mpp: "mpp";
+};
+type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail];
+type PaymentPhase = AgentPaymentPhase;
+type PaymentNextAction = AgentPaymentNextAction;
+declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent")[];
+declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("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")[];
+declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "direct")[];
+declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
+declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
+declare const AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
+declare const AgentPaymentPhaseSchema: AgentPaymentEnumSchema;
+declare const AgentPaymentNextActionSchema: AgentPaymentEnumSchema;
+declare const AgentPaymentRailSchema: AgentPaymentEnumSchema;
 interface PaymentStatusResult {
     paymentId: string;
     kind: PaymentStateKind;
@@ -208,12 +450,36 @@ interface PaymentStatusResult {
     expiresAt: string;
     chainId: number;
     message: string;
+    amountAtomic?: string | null;
+    asset?: string | null;
+    network?: string | null;
+    description?: string | null;
+    idempotencyKey?: string | null;
+    x402?: {
+        amountAtomic: string | null;
+        asset: string | null;
+        network: string | null;
+        resourceUrl: string | null;
+        merchantAddress: string | null;
+        description: string | null;
+        idempotencyKey: string | null;
+    };
+    mpp?: {
+        amountAtomic: string | null;
+        asset: string | null;
+        network: string | null;
+        resourceUrl: string | null;
+        merchantAddress: string | null;
+        description: string | null;
+        idempotencyKey: string | null;
+        challengeId: string | null;
+    };
 }
 interface PendingApproval extends PaymentStatusResult {
     kind: 'approval_request';
     status: 'pending_approval' | 'pending' | string;
-    phase: 'user_approval_required';
-    nextAction: 'wait_for_user_approval';
+    phase: typeof AgentPaymentPhase.UserApprovalRequired;
+    nextAction: typeof AgentPaymentNextAction.WaitForUserApproval;
     requested?: string;
     remaining?: string | null;
 }
@@ -229,6 +495,7 @@ declare class HavenApiError extends HavenError {
 }
 declare class HavenPaymentStateError extends HavenApiError {
     readonly state: PaymentStatusResult;
+    resumeState?: X402ResumeState | MppResumeState;
     constructor(message: string, statusCode: number, state: PaymentStatusResult, body?: unknown);
     get status(): string;
     get phase(): PaymentPhase;
@@ -252,9 +519,38 @@ declare class HavenClient {
     private readonly inFlightX402;
     private readonly x402ReceiptCache;
     private readonly inFlightMachinePayments;
+    /**
+     * Setup-time headers configured via `HavenClientConfig.defaultHeaders`.
+     * Read-only after construction — use `withRequestContext` for per-call
+     * scoping so concurrent requests don't race on shared mutable state.
+     */
+    private readonly defaultHeaders;
+    /**
+     * Async-local store for per-request context (currently: extra headers).
+     * Each `withRequestContext` invocation produces an isolated store, so
+     * overlapping async work — like two MCP tool dispatches in flight at
+     * the same time — see their own headers without stepping on each other.
+     */
+    private readonly requestContext;
     /** Delegate address derived from the private key (if provided) */
     readonly delegateAddress: string | undefined;
     constructor(config: HavenClientConfig);
+    /**
+     * Run `fn` with extra Haven-API headers scoped to the async work it
+     * performs. Used by the MCP server to tag every Haven API request that
+     * a single tool dispatch makes with `X-Haven-MCP-Tool: <name>` so the
+     * backend can write an audit-log row attributing the call.
+     *
+     * The headers are held in an `AsyncLocalStorage` so overlapping
+     * dispatches do not leak headers into each other's requests. The store
+     * inherits across `await` boundaries, so any Haven API call made while
+     * `fn` is awaiting will pick up the right headers.
+     *
+     * Has no effect on outbound merchant requests (x402 / MPP) — those
+     * never go through the internal `request<T>` path that reads the
+     * context.
+     */
+    withRequestContext<T>(headers: Record<string, string>, fn: () => Promise<T>): Promise<T>;
     /**
      * Send a payment in one call.
      *
@@ -297,6 +593,27 @@ declare class HavenClient {
      * `getPayment()` remains available for payment-intent-only integrations.
      */
     getPaymentStatus(paymentId: string): Promise<PaymentStatusResult>;
+    /**
+     * Get the agent identity tied to this API key.
+     */
+    getAgent(): Promise<HavenAgent>;
+    /**
+     * Get configured and on-chain allowances for the authenticated agent.
+     */
+    getAllowances(): Promise<HavenAllowanceSummary>;
+    /**
+     * List recent machine-payment receipts/evidence for bookkeeping.
+     */
+    listReceipts(options?: {
+        limit?: number;
+    }): Promise<HavenPaymentReceipt[]>;
+    /**
+     * Rehydrate the x402/MPP resume-state bundle for a payment id.
+     *
+     * The server returns stored protocol context only. The client still signs the
+     * merchant proof locally when resumeX402Payment() or resumeMppPayment() runs.
+     */
+    getResumeState(paymentId: string): Promise<PaymentResumeState>;
     /**
      * Poll until a payment reaches a terminal status (confirmed, failed, expired).
      */
@@ -311,9 +628,18 @@ declare class HavenClient {
      * Requires `delegateKey` to be set in the client config.
      */
     authorizeX402(paymentRequired: X402PaymentRequired, options?: X402AuthorizationOptions): Promise<X402Receipt>;
+    /**
+     * Probe a paid endpoint and return its x402 quote without creating a Haven
+     * payment or approval request.
+     */
+    quoteX402(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<X402Quote>;
+    /**
+     * Pay a previously inspected x402 quote and retry the exact captured request.
+     */
+    payX402Quote(quote: X402Quote, options?: X402AuthorizationOptions): Promise<Response>;
     private authorizeStandardX402;
     resumeAuthorizedX402(input: ResumeAuthorizedX402Input): Promise<X402Receipt>;
-    resumeX402Payment(input: ResumeX402PaymentInput): Promise<Response>;
+    resumeX402Payment(input: ResumeX402PaymentInput | X402ResumeState): Promise<Response>;
     /**
      * Fetch wrapper that automatically handles HTTP 402 responses.
      *
@@ -328,24 +654,48 @@ declare class HavenClient {
      * Requires `delegateKey` to be set in the client config.
      */
     fetch(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<Response>;
+    /**
+     * Probe a paid MPP endpoint or inspect an existing challenge without creating
+     * a Haven payment or approval request.
+     */
+    quoteMpp(challengeOrUrl: MachinePaymentChallenge | string, init?: RequestInit, options?: MppAuthorizationOptions): Promise<MppQuote>;
+    /**
+     * Pay a previously inspected MPP quote and retry the exact captured request.
+     */
+    payMppChallenge(quote: MppQuote, options?: MppAuthorizationOptions): Promise<Response>;
     private retryX402Request;
-    authorizeMachinePayment(challenge: MachinePaymentChallenge): Promise<MachinePaymentReceipt>;
+    authorizeMachinePayment(challenge: MachinePaymentChallenge, options?: MppAuthorizationOptions): Promise<MachinePaymentReceipt>;
     private authorizeMppDemoPayment;
+    resumeAuthorizedMpp(input: ResumeAuthorizedMppInput): Promise<MachinePaymentReceipt>;
+    resumeMppPayment(input: ResumeMppPaymentInput | MppResumeState): Promise<Response>;
     private fetchWithMachinePayment;
+    private retryMppRequest;
     private assertCanResumeX402;
+    private assertCanResumeMpp;
     private mapX402ReceiptFromAuthorization;
     private mapX402ReceiptFromStatus;
     private buildX402Receipt;
     private createStandardX402Header;
     private cacheX402Receipt;
     private mapMachinePaymentReceipt;
+    private mapMachinePaymentReceiptFromStatus;
     private recordMerchantRetryRejected;
     private reportMachinePaymentEvidence;
     private throwIfNonSignableAuthorizationState;
     private throwPaymentStateError;
     private paymentStateFromRaw;
     private x402PayerAddress;
+    private snapshotX402Request;
+    private snapshotRequestBody;
+    private requestInitFromSnapshot;
     private withX402Wallet;
+    private buildX402Quote;
+    private buildX402ResumeState;
+    private buildMppQuote;
+    private buildMppResumeState;
+    private attachResumeState;
+    private attachX402ResumeState;
+    private attachMppResumeState;
     /**
      * Execute a tool call by name and input.
      *
@@ -367,6 +717,7 @@ declare class HavenClient {
     private request;
     private mapPaymentResult;
     private mapPaymentStatusResult;
+    private mapPaymentReceipt;
 }
 
 /**
@@ -496,4 +847,4 @@ declare function parseMachinePaymentChallengeResponse(response: Response): Promi
 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 };
+export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, type HavenAgent, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, type SignData, type X402AuthorizationOptions, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };