#!/usr/bin/env node
/**
 * @name X402PaidCallHelper
 * @description Local helper for paying and retrying hosted SAP MCP x402 tool calls with a user-controlled SAP profile signer.
 */
import type { PaymentPayload, PaymentRequired, PaymentRequirements, SettleResponse } from '@x402/core/types';
import { type SapMcpConfig } from '../../config-runtime/src/env.js';
import { type WalletGuardSummary } from '../../signer/src/wallet-guard.js';
export declare const DEFAULT_X402_PAID_CALL_ENDPOINT = "https://mcp.sap.oobeprotocol.ai/mcp";
/**
 * @name X402PaidCallInput
 * @description Request shape accepted by the local x402 paid-call helper.
 */
export interface X402PaidCallInput {
    endpoint?: string;
    toolName?: string;
    arguments?: unknown;
    body?: JsonRpcRequest;
    profileName?: string;
    maxPriceUsd: number;
    maxAttempts?: number;
    confirm: boolean;
    /** Prepaid session ID. When set, the bridge injects an X-SAP-Prepaid-Session
     * header into both the unpaid probe and paid retry. If the server grants
     * access via prepaid balance (HTTP 200), no x402 payment is charged. */
    prepaidSessionId?: string;
}
/**
 * @name X402ExternalCallInput
 * @description Request shape accepted by the local helper for generic HTTP x402 endpoints outside hosted SAP MCP.
 */
export interface X402ExternalCallInput {
    url: string;
    method?: string;
    headers?: Record<string, string>;
    body?: unknown;
    profileName?: string;
    maxPriceUsd: number;
    maxAttempts?: number;
    confirm: boolean;
}
/**
 * @name X402ChallengeProbeInput
 * @description Request shape for obtaining a hosted MCP x402 challenge without signing it.
 */
export interface X402ChallengeProbeInput {
    endpoint?: string;
    toolName?: string;
    arguments?: unknown;
    body?: JsonRpcRequest;
    maxPriceUsd?: number;
}
/**
 * @name X402ChallengeProbeResult
 * @description Parsed x402 challenge returned by the hosted MCP server before local signing.
 */
export interface X402ChallengeProbeResult {
    endpoint: string;
    sessionId: string;
    requestBody: JsonRpcRequest;
    paymentRequired: PaymentRequired;
    selectedRequirements: PaymentRequirements;
    amountUsd: number;
    instructions: {
        signer: 'local-sap-mcp-profile-or-external-signer';
        retryHeader: 'Payment-Signature';
        settlementHeader: 'Payment-Response';
        requestBinding: 'json-rpc-method-and-params';
        recommendedTool: 'sap_payments_call_paid_tool';
    };
}
/**
 * @name X402ChallengeSignInput
 * @description Request shape for signing a previously obtained x402 challenge without executing the paid call.
 */
export interface X402ChallengeSignInput {
    paymentRequired: PaymentRequired;
    selectedIndex?: number;
    profileName?: string;
    maxPriceUsd: number;
    confirm: boolean;
}
/**
 * @name X402ChallengeSignResult
 * @description One-time payment header generated from a challenge and a local SAP MCP profile signer.
 */
export interface X402ChallengeSignResult {
    signerAddress: string;
    amountUsd: number;
    payment: {
        network: string;
        asset: string;
        payTo: string;
    };
    headers: Record<string, string>;
    payload: PaymentPayload;
    warning: string;
}
/**
 * @name X402ReceiptInspectionResult
 * @description Parsed x402 settlement receipt header or structured settlement response.
 */
export interface X402ReceiptInspectionResult {
    validJson: boolean;
    decoded: unknown;
    txSignature?: string;
    network?: string;
    warning?: string;
}
/**
 * @name AgentCommercePolicySnapshot
 * @description Redacted local policy limits used by agents before paying or moving value.
 */
export interface AgentCommercePolicySnapshot {
    autoPayX402BelowUsd: number;
    dailyX402LimitUsd?: number;
    maxTradeUsd?: number;
    maxSlippageBps: number;
    requireConfirmationAboveUsd: number;
    allowedProtocols: readonly string[];
    maxAttempts: number;
}
/**
 * @name X402PaymentReadinessResult
 * @description Full local readiness snapshot for hosted paid/write SAP MCP workflows.
 */
export interface X402PaymentReadinessResult {
    hostedMcp: {
        endpoint: string;
        accountModel: 'hosted-remote-accountless';
        toolNamespace: 'sap';
    };
    localBridge: {
        status: 'connected';
        toolNamespace: 'sap_payments';
        preferredTool: 'sap_payments_call_paid_tool';
        readinessTool: 'sap_payments_readiness';
    };
    profile: {
        activeProfile: string;
        configPath: string;
        mode: SapMcpConfig['mode'];
        network: string;
        rpcUrl: string;
        programId: string;
        walletPathConfigured: boolean;
        walletFileExists: boolean;
        signerConfigured: boolean;
        signerPublicKey?: string;
        agentPubkey?: string;
        secretMaterial: 'keypair-bytes-never-returned';
    };
    walletGuard: WalletGuardSummary;
    balances: {
        checked: boolean;
        sol?: number;
        usdc?: number;
        usdcMint: string;
        payerBalanceEnoughForAutoPay?: boolean;
        error?: string;
    };
    policy: AgentCommercePolicySnapshot;
    readiness: {
        status: 'ready' | 'degraded' | 'not-ready';
        canPayX402: boolean;
        canExecuteWriteTools: boolean;
        issues: readonly string[];
        nextAction: string;
    };
    agentInstruction: string;
}
/**
 * @name X402PaidCallResult
 * @description Result returned after a hosted MCP paid request is completed.
 */
export interface X402PaidCallResult {
    success: boolean;
    endpoint: string;
    sessionId: string;
    signerAddress: string;
    payment: {
        amountUsd: number;
        network: string;
        asset: string;
        payTo: string;
    };
    settlement?: SettleResponse;
    response: unknown;
    attempts: number;
    transientRetries: readonly string[];
    /** HTTP status code from the upstream server after payment. Present when
     * payment was charged but the upstream returned a non-OK response (401,
     * 500, etc.). The agent can use this to request a credit or refund. */
    upstreamHttpStatus?: number;
    /** True when the payment was charged but the upstream failed. Agent should
     * not retry with the same parameters — the failure is upstream, not local. */
    paymentChargedButUpstreamFailed?: boolean;
    /** True when an x402 payment was actually charged (signed and settled).
     * False when the call was granted via prepaid session balance or when no
     * payment was needed. Agents can use this to distinguish prepaid vs paid. */
    paymentCharged?: boolean;
    /** True when a prepaid session was used to grant access without x402
     * payment. The prepaidSessionId field identifies which session was used. */
    prepaidUsed?: boolean;
    /** True when the hosted tool was free or otherwise did not require an x402
     * challenge. This lets agents safely route mixed free/paid tools through the
     * bridge without treating HTTP 200 as a malformed payment response. */
    freeToolBypass?: boolean;
    /** The prepaid session ID used for this call, if any. Present when
     * prepaidUsed is true. */
    prepaidSessionId?: string;
    audit: X402PaidCallAudit;
}
/**
 * @name X402PaidCallAudit
 * @description Agent-readable proof object for one hosted paid MCP execution.
 */
export interface X402PaidCallAudit {
    intentId: string;
    profileName: string;
    signerAddress: string;
    endpoint: string;
    toolName?: string;
    requestMethod: string;
    payment: {
        amountUsd: number;
        network: string;
        asset: string;
        payTo: string;
    };
    receipt: {
        present: boolean;
        transaction?: string;
        network?: string;
        amount?: string;
        payer?: string;
    };
    attempts: number;
    transientRetries: readonly string[];
    secretMaterial: 'keypair-bytes-never-returned';
}
/**
 * @name X402ExternalCallResult
 * @description Result returned after a generic HTTP x402 request is completed through the local signer.
 */
export interface X402ExternalCallResult {
    success: boolean;
    url: string;
    method: string;
    signerAddress: string;
    payment?: {
        amountUsd: number;
        network: string;
        asset: string;
        payTo: string;
    };
    settlement?: SettleResponse;
    response: {
        status: number;
        headers: Record<string, string>;
        body: unknown;
    };
    attempts: number;
    transientRetries: readonly string[];
    audit: X402ExternalCallAudit;
}
/**
 * @name X402ExternalCallAudit
 * @description Agent-readable proof object for one generic x402 HTTP request.
 */
export interface X402ExternalCallAudit {
    intentId: string;
    profileName: string;
    signerAddress: string;
    url: string;
    method: string;
    payment?: {
        amountUsd: number;
        network: string;
        asset: string;
        payTo: string;
    };
    receipt: {
        present: boolean;
        transaction?: string;
        network?: string;
        amount?: string;
        payer?: string;
    };
    attempts: number;
    transientRetries: readonly string[];
    secretMaterial: 'keypair-bytes-never-returned';
}
interface JsonRpcRequest {
    jsonrpc: '2.0';
    id?: string | number | null;
    method: string;
    params?: unknown;
}
/**
 * @name executeX402PaidCall
 * @description Initializes MCP, obtains x402 payment requirements, signs locally, retries the call, and returns the settlement receipt.
 */
export declare function executeX402PaidCall(input: X402PaidCallInput): Promise<X402PaidCallResult>;
/**
 * @name X402BatchPaidCallInput
 * @description Request shape for batch paid calls with concurrency control.
 */
export interface X402BatchPaidCallInput {
    endpoint?: string;
    profileName?: string;
    maxPriceUsd: number;
    maxTotalUsd?: number;
    confirm: boolean;
    maxAttempts?: number;
    concurrency?: number;
    calls: ReadonlyArray<{
        toolName: string;
        arguments?: Record<string, unknown>;
    }>;
}
/**
 * @name X402BatchPaidCallResult
 * @description Result of a batch paid call.
 */
export interface X402BatchPaidCallResult {
    success: boolean;
    endpoint: string;
    sessionId: string;
    totalCalls: number;
    succeeded: number;
    failed: number;
    totalAmountUsd: number;
    results: ReadonlyArray<X402PaidCallResult | {
        success: false;
        error: string;
        toolName: string;
    }>;
    audit: {
        profileName: string;
        signerAddress: string;
        totalAmountUsd: number;
        maxTotalUsd: number;
        callCount: number;
        concurrency: number;
    };
}
/**
 * @name executeX402BatchPaidCall
 * @description Executes multiple paid tool calls in parallel with a shared MCP session.
 *   Uses concurrency-limited parallelism (default 3) to avoid overwhelming the hosted server.
 *   Each call gets its own x402 challenge and payment — no shared payment across calls.
 */
export declare function executeX402BatchPaidCall(input: X402BatchPaidCallInput): Promise<X402BatchPaidCallResult>;
/**
 * @name executeExternalX402Call
 * @description Calls a generic HTTP x402 endpoint by fetching its challenge, signing locally, retrying with the payment header, and returning the receipt.
 */
export declare function executeExternalX402Call(input: X402ExternalCallInput): Promise<X402ExternalCallResult>;
/**
 * @name getX402PaymentReadiness
 * @description Checks local profile, signer, RPC, balances, and commerce policy for hosted paid/write workflows.
 */
export declare function getX402PaymentReadiness(profileName?: string, endpoint?: string): Promise<X402PaymentReadinessResult>;
/**
 * @name probeX402PaymentChallenge
 * @description Initializes hosted MCP and returns a parsed x402 challenge for one unpaid tool call without signing.
 */
export declare function probeX402PaymentChallenge(input: X402ChallengeProbeInput): Promise<X402ChallengeProbeResult>;
/**
 * @name signX402PaymentChallenge
 * @description Signs a parsed x402 challenge with the active SAP MCP profile signer and returns a one-time payment header.
 */
export declare function signX402PaymentChallenge(input: X402ChallengeSignInput): Promise<X402ChallengeSignResult>;
/**
 * @name inspectX402Receipt
 * @description Decodes a PAYMENT-RESPONSE or X-PAYMENT-RESPONSE header for agent-readable receipt inspection.
 */
export declare function inspectX402Receipt(receiptHeader: string): X402ReceiptInspectionResult;
export {};
//# sourceMappingURL=x402-paid-call.d.ts.map