@haven_ai/sdk 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -0,0 +1,1081 @@
+import { PaymentRequirements } from 'x402/types';
+
+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;
+    /**
+     * 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" */
+    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;
+}
+/**
+ * Keyless x402 construct result.
+ *
+ * Returned by `createX402Intent` — the non-custodial half of an x402 payment.
+ * It carries the unsigned funding hash (`signData.hash`, Safe → delegate EOA)
+ * plus everything the *edge* needs to build and sign the EIP-3009 merchant
+ * header itself. The construct path never signs; both delegate signatures
+ * (funding hash + merchant header) happen on the machine that holds the key.
+ */
+interface X402Intent {
+    /** Haven payment id for the funding transfer. */
+    paymentId: string;
+    status: 'pending_signature';
+    /** ISO 8601 expiry of the funding intent, if returned. */
+    expiresAt?: string;
+    /** The unsigned funding hash to sign with the delegate key (Safe → delegate EOA). */
+    signData: SignData;
+    /** The selected x402 option — the edge needs this to build the EIP-3009 header. */
+    accepted: X402PaymentOption;
+    /** Resource URL the 402 came from. */
+    resourceUrl: string;
+    /** Merchant payTo address (the final recipient of the EIP-3009 transfer). */
+    merchantTo: string;
+    /** Atomic amount the edge signer must authorize in the merchant header. */
+    amountAtomic: string;
+    /** Token contract the merchant header must pay. */
+    asset: string;
+    /** x402 network the merchant header must use. */
+    network: string;
+    /** Haven-authenticated binding over the x402 expected context. */
+    expectedAuth: X402ExpectedAuth;
+    /** Delegate EOA the funding transfer tops up (the x402 payer). */
+    fundingTo: string;
+}
+interface X402ExpectedContext {
+    paymentId: string;
+    payloadHash: string;
+    resourceUrl: string;
+    merchantTo: string;
+    amount: string;
+    asset: string;
+    network: string;
+}
+interface X402ExpectedAuth {
+    version: 1;
+    message: string;
+    signature: string;
+    signer: 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;
+    /** 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;
+    /** 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;
+    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;
+}
+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;
+    paymentIntentId?: string | null;
+    approvalRequestId?: string | null;
+    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';
+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";
+    /**
+     * Pre-flight check determined the delegate's existing balance plus the
+     * remaining on-chain allowance cannot cover the requested amount, so no
+     * payment intent was created. Distinct from `UserApprovalRequired`: there
+     * is no approval that would fix this — the originating Safe needs more
+     * funds or the agent's per-token allowance needs to be raised first.
+     */
+    readonly InsufficientFunds: "insufficient_funds";
+};
+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";
+    /**
+     * Stop and tell the user that the originating Safe needs to be funded or
+     * the agent's per-token allowance needs to be raised before the payment
+     * can succeed. A user approval will not fix this state on its own.
+     */
+    readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
+};
+type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
+/**
+ * Stable rail identifier carried on Haven agent payment responses and resume
+ * state.
+ *
+ * Two layers of vocabulary share this enum because both reach the wire:
+ *
+ *   - **Categorical rails** identify the rail family and are used as
+ *     discriminators on `PaymentResumeState`: `direct`, `x402`, `mpp`.
+ *   - **Granular rails** identify the specific protocol the backend persists
+ *     and returns on response bodies: `mpp_demo`, `mpp_crypto`,
+ *     `stripe_deposit`, `spt`. `x402` doubles as both categorical and
+ *     granular.
+ *
+ * Consumers reading the top-level `rail` field on a payment status response
+ * should treat any `mpp*` value as the MPP family; consumers reading the
+ * `rail` field on a `MppResumeState` will always see the categorical `mpp`,
+ * with the granular value on `paymentRail`.
+ */
+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 family — categorical value used as a resume-state discriminator. */
+    readonly Mpp: "mpp";
+    /** Haven internal MPP demo rail. Not for production traffic. */
+    readonly MppDemo: "mpp_demo";
+    /** Crypto-settled MPP rail. */
+    readonly MppCrypto: "mpp_crypto";
+    /** Stripe-deposit-backed MPP rail. */
+    readonly StripeDeposit: "stripe_deposit";
+    /** Stripe Payment Token MPP rail. */
+    readonly Spt: "spt";
+};
+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" | "insufficient_funds")[];
+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" | "fund_safe_or_raise_allowance")[];
+declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "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;
+    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;
+    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: typeof AgentPaymentPhase.UserApprovalRequired;
+    nextAction: typeof AgentPaymentNextAction.WaitForUserApproval;
+    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;
+    resumeState?: X402ResumeState | MppResumeState;
+    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;
+    /**
+     * 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.
+     *
+     * 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>;
+    /**
+     * Keyless x402 construct.
+     *
+     * The non-custodial half of an x402 payment: posts the funding request to
+     * `/x402` and returns the unsigned funding hash plus the data the caller
+     * needs to build and sign the EIP-3009 merchant header itself. Crucially it
+     * does **not** sign — neither the funding hash nor the merchant header — so
+     * it works without a `delegateKey`. Both delegate signatures happen on the
+     * machine that holds the key (the edge); the hosted MCP server relays only.
+     *
+     * Use this from the hosted, keyless server. The all-in-one `authorizeX402`
+     * remains for local clients that hold the key.
+     *
+     * Throws (via the shared payment-state path) when the amount exceeds the
+     * on-chain allowance — there is nothing to sign until the user approves.
+     */
+    createX402Intent(paymentRequired: X402PaymentRequired, options?: X402AuthorizationOptions): Promise<X402Intent>;
+    /**
+     * 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>;
+    /**
+     * 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).
+     */
+    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>;
+    /**
+     * 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 | X402ResumeState): 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>;
+    /**
+     * 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, 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.
+     *
+     * 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;
+    private mapPaymentReceipt;
+}
+
+/**
+ * Pre-built tool definitions for AI agent frameworks.
+ *
+ * These definitions describe Haven's direct SDK tool-calling surface in the
+ * formats expected by Claude (Anthropic) and OpenAI.
+ *
+ * The agent payment surface used by these tools is shared with the
+ * `@haven_ai/mcp` server — both consume `toolDescriptions` from
+ * `./tool-descriptions.ts`. Each consumer composes its own user-visible string
+ * from the same semantic fragments, so guidance lands in both surfaces at
+ * once and a downstream test asserts the shared summary appears in every
+ * consumer description.
+ *
+ * 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;
+
+/**
+ * Shared semantic descriptions for Haven agent payment tools.
+ *
+ * Two surfaces in this repo expose Haven as a tool: the Claude / OpenAI
+ * function-calling tool definitions in `tools.ts` (used for direct SDK
+ * integrations) and the MCP server in `packages/mcp` (used by any MCP-speaking
+ * agent runtime). The two surfaces use different tool *names* — the SDK's
+ * tools are tuned for tool-calling conventions (`make_payment`,
+ * `authorize_x402_payment`); the MCP tools follow the MCP `haven_*` naming
+ * (`haven_pay_x402_quote`).
+ *
+ * The underlying *operations* are the same, so the descriptive prose should
+ * live in one place. Both surfaces import from this module and compose their
+ * own tool descriptions from these semantic fragments. Drift is caught by
+ * tests asserting each consumer's description string contains the shared
+ * `summary` from this module.
+ */
+interface ToolDescription {
+    /** One-line summary of the operation. Used as the first sentence of every
+     * downstream description and as a stable substring for drift tests. */
+    summary: string;
+    /** Natural-language user intents that should make an agent prefer this
+     * tool over adjacent tools. Empty or omitted when the summary is enough. */
+    selectionGuidance?: string;
+    /** Concrete behaviour the tool performs end-to-end, including which
+     * non-custodial guarantee applies. */
+    behavior: string;
+    /** What the agent should do next on error / pending-approval states.
+     * Empty string if not applicable. */
+    nextActionGuidance: string;
+}
+/**
+ * Build a single description string from the three fragments. Joined with
+ * spaces so consumers can split on the summary substring if they need to.
+ */
+declare function composeDescription(d: ToolDescription): string;
+declare const toolDescriptions: {
+    readonly quoteX402: {
+        readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
+        readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
+        readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again — Haven re-uses the captured request when paying.";
+    };
+    readonly payX402: {
+        readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
+        readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
+        readonly nextActionGuidance: string;
+    };
+    readonly payX402OneShot: {
+        readonly summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.";
+        readonly selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.";
+        readonly nextActionGuidance: string;
+    };
+    readonly resumeX402: {
+        readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
+        readonly behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.";
+        readonly nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session.";
+    };
+    readonly quoteMpp: {
+        readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
+        readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
+        readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again — Haven re-uses the captured request when paying.";
+    };
+    readonly payMpp: {
+        readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
+        readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
+        readonly behavior: "Authorizes the payment through Haven within the on-chain allowance, signs the challenge proof, and returns the proof header for retrying the original paid resource.";
+        readonly nextActionGuidance: "If approval is needed, preserve resume_state or payment_id and wait for nextAction=retry_original_x402_request before resuming.";
+    };
+    readonly resumeMpp: {
+        readonly summary: "Resume an MPP payment after the Haven wallet owner approved the funding step.";
+        readonly behavior: "Accepts either resume_state or payment_id and retries the original paid resource with the MPP proof header. No new Haven approval is created.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getPaymentStatus: {
+        readonly summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.";
+        readonly behavior: "Accepts a payment intent or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).";
+        readonly nextActionGuidance: "";
+    };
+    readonly getResumeState: {
+        readonly summary: "Rehydrate stored x402 or MPP resume_state by payment_id.";
+        readonly behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getAgent: {
+        readonly summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.";
+        readonly behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.";
+        readonly nextActionGuidance: "";
+    };
+    readonly getAllowances: {
+        readonly summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.";
+        readonly selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.";
+        readonly behavior: "Reads the Safe AllowanceModule snapshot per token (allowance, spent, remaining, reset window). Configured amounts from Haven are returned alongside the on-chain truth.";
+        readonly nextActionGuidance: "";
+    };
+    readonly listReceipts: {
+        readonly summary: "List recent machine-payment receipts and evidence for bookkeeping.";
+        readonly selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.";
+        readonly behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.";
+        readonly nextActionGuidance: "";
+    };
+};
+type SharedToolKey = keyof typeof toolDescriptions;
+
+/**
+ * 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;
+/**
+ * Select an option that can be paid with the official x402 EIP-3009 exact
+ * scheme. Haven's older tx-hash proof path can describe more networks; the
+ * merchant-verified path currently needs Base USDC.
+ */
+declare function selectStandardPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+declare function x402AuthorizationAmount(option: X402PaymentOption): string;
+declare function buildX402ExpectedMessage(context: X402ExpectedContext): string;
+declare function toStandardPaymentRequirements(paymentRequired: X402PaymentRequired, option: X402PaymentOption): PaymentRequirements;
+/**
+ * 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 { 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 SharedToolKey, type SignData, type ToolDescription, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildX402ExpectedMessage, composeDescription, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };