/**
 * The FacilitatorAPI class provides methods to verify and settle AI agent permissions using X402 access tokens.
 * This allows AI agents to act as facilitators, verifying and settling credits on behalf of subscribers.
 *
 * @example
 * ```typescript
 * import { Payments, X402PaymentRequired } from '@nevermined-io/payments'
 *
 * // Initialize the Payments instance
 * const payments = Payments.getInstance({
 *   nvmApiKey: 'your-nvm-api-key',
 *   environment: 'sandbox'
 * })
 *
 * // The server's 402 PaymentRequired response
 * const paymentRequired: X402PaymentRequired = buildPaymentRequired('123456789', {
 *   endpoint: '/api/v1/agents/task',
 *   agentId: '987654321',
 *   httpVerb: 'POST'
 * })
 *
 * // Get X402 access token from subscriber (x402 v2: payment-signature header)
 * const x402Token = req.headers['payment-signature'] as string
 *
 * // Verify if subscriber has sufficient permissions/credits
 * const verification = await payments.facilitator.verifyPermissions({
 *   paymentRequired,
 *   x402AccessToken: x402Token,
 *   maxAmount: 2n
 * })
 *
 * if (verification.isValid) {
 *   // Settle (burn) the credits
 *   const settlement = await payments.facilitator.settlePermissions({
 *     paymentRequired,
 *     x402AccessToken: x402Token,
 *     maxAmount: 2n
 *   })
 *   console.log(`Credits redeemed: ${settlement.creditsRedeemed}`)
 * }
 * ```
 */
import { BasePaymentsAPI } from '../api/base-payments.js';
import { PaymentOptions, StartAgentRequest, X402SchemeType } from '../common/types.js';
import type { EnvironmentName } from '../environments.js';
import type { Payments } from '../payments.js';
/**
 * x402 Resource information
 */
export interface X402Resource {
    /** The protected resource URL */
    url: string;
    /** Human-readable description */
    description?: string;
    /** Expected response MIME type (e.g., "application/json") */
    mimeType?: string;
}
/**
 * x402 Scheme extra fields for nvm:erc4337
 */
export interface X402SchemeExtra {
    /** Scheme version (e.g., "1") */
    version?: string;
    /** Agent identifier */
    agentId?: string;
    /** HTTP method for the endpoint */
    httpVerb?: string;
}
/**
 * x402 Scheme definition (nvm:erc4337)
 */
export interface X402Scheme {
    /** Payment scheme identifier (e.g., "nvm:erc4337") */
    scheme: string;
    /** Blockchain network in CAIP-2 format (e.g., "eip155:84532") */
    network: string;
    /** 256-bit plan identifier */
    planId: string;
    /** Scheme-specific extra fields */
    extra?: X402SchemeExtra;
}
/**
 * x402 PaymentRequired response (402 response from server)
 */
export interface X402PaymentRequired {
    /** x402 protocol version (always 2) */
    x402Version: number;
    /** Human-readable error message */
    error?: string;
    /** Protected resource information */
    resource: X402Resource;
    /** Array of accepted payment schemes */
    accepts: X402Scheme[];
    /** Extensions object (empty object for nvm:erc4337) */
    extensions: Record<string, unknown>;
}
/**
 * x402 PaymentAccepted response (accepted payment scheme)
 */
export interface X402PaymentAccepted {
    /** The x402 version */
    x402Version: number;
    /** The accepted payment scheme (nvm:erc4337) */
    accepted: X402Scheme;
    /** The payload of the payment accepted */
    payload: {
        signature: string;
        authorization: {
            from: string;
            sessionKeysProvider: string;
            sessionKeys: string[];
        };
    };
    extensions: Record<string, unknown>;
}
/**
 * Parameters for verifying permissions
 */
export interface VerifyPermissionsParams {
    /** The server's 402 PaymentRequired response */
    paymentRequired: X402PaymentRequired;
    /** The X402 access token (base64-encoded) */
    x402AccessToken: string;
    /** Maximum credits to verify (optional) */
    maxAmount?: bigint;
}
/**
 * x402 Verify Response - per x402 facilitator spec
 * @see https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md
 */
export interface VerifyPermissionsResult {
    /** Whether the payment authorization is valid */
    isValid: boolean;
    /** Reason for invalidity (only present if isValid is false) */
    invalidReason?: string;
    /** Address of the payer's wallet */
    payer?: string;
    /** Network identifier (e.g., 'stripe', 'braintree', 'visa', 'eip155:84532') */
    network?: string;
    /** Agent request ID for observability tracking (Nevermined extension) */
    agentRequestId?: string;
    /** URL pattern that matched the endpoint (Nevermined extension) */
    urlMatching?: string;
    /** Agent request context for observability (Nevermined extension) */
    agentRequest?: StartAgentRequest;
}
/**
 * Parameters for settling permissions
 */
export interface SettlePermissionsParams {
    /** The server's 402 PaymentRequired response */
    paymentRequired: X402PaymentRequired;
    /** The X402 access token (base64-encoded) */
    x402AccessToken: string;
    /** Number of credits to burn (optional) */
    maxAmount?: bigint;
    /** Agent request ID for observability tracking. Returned by verifyPermissions. */
    agentRequestId?: string;
    /** Whether this is a batch request (multiple LLM calls under one agentRequestId) */
    batch?: boolean;
    /** Margin percentage (0-10) for credit calculation. Mutually exclusive with maxAmount when agentRequestId provided. */
    marginPercent?: number;
}
/**
 * x402 Settle Response - per x402 facilitator spec
 * @see https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md
 */
export interface SettlePermissionsResult {
    /** Whether settlement was successful */
    success: boolean;
    /** Reason for settlement failure (only present if success is false) */
    errorReason?: string;
    /** Address of the payer's wallet */
    payer?: string;
    /** Blockchain transaction hash (empty string if settlement failed) */
    transaction: string;
    /** Blockchain network identifier in CAIP-2 format */
    network: string;
    /** Number of credits redeemed (Nevermined extension) */
    creditsRedeemed?: string;
    /** Subscriber's remaining balance (Nevermined extension) */
    remainingBalance?: string;
    /** Transaction hash of the order operation if auto top-up occurred (Nevermined extension) */
    orderTx?: string;
}
/**
 * Build an X402PaymentRequired object for verify/settle operations.
 *
 * This helper simplifies the creation of payment requirement objects
 * that are needed for the facilitator API.
 *
 * @param planId - The Nevermined plan identifier (required)
 * @param options - Optional configuration with endpoint, agentId, httpVerb, network, description
 * @returns X402PaymentRequired object ready to use with verifyPermissions/settlePermissions
 *
 * @example
 * ```typescript
 * import { buildPaymentRequired } from '@nevermined-io/payments'
 *
 * const paymentRequired = buildPaymentRequired('123456789', {
 *   endpoint: '/api/v1/agents/task',
 *   agentId: '987654321',
 *   httpVerb: 'POST'
 * })
 *
 * const result = await payments.facilitator.verifyPermissions({
 *   paymentRequired,
 *   x402AccessToken: token,
 *   maxAmount: 2n
 * })
 * ```
 */
export declare function buildPaymentRequired(planId: string, options?: {
    endpoint?: string;
    agentId?: string;
    httpVerb?: string;
    network?: string;
    description?: string;
    mimeType?: string;
    scheme?: X402SchemeType;
    environment?: EnvironmentName;
}): X402PaymentRequired;
/**
 * Build an X402PaymentRequired object advertising one or more plans.
 *
 * Like {@link buildPaymentRequired} but produces one `accepts[]` entry per plan
 * id, so a payment-required response can advertise every plan that unlocks the
 * resource. For a single plan this is equivalent to {@link buildPaymentRequired}.
 *
 * @param planIds - The Nevermined plan identifiers (falls back to `['']` if empty)
 * @param options - Same options as {@link buildPaymentRequired}
 * @returns X402PaymentRequired object with one accepts entry per plan
 */
export declare function buildPaymentRequiredForPlans(planIds: string[], options?: {
    endpoint?: string;
    agentId?: string;
    httpVerb?: string;
    network?: string;
    description?: string;
    mimeType?: string;
    scheme?: X402SchemeType;
    environment?: EnvironmentName;
}): X402PaymentRequired;
/**
 * Resolve the network for a plan from its fiatPaymentProvider metadata.
 * For card-delegation plans, returns the provider ('stripe' or 'braintree').
 * Returns undefined for crypto plans.
 */
export declare function resolveNetwork(payments: Payments, planId: string, explicitNetwork?: string): Promise<string | undefined>;
/**
 * Resolve the x402 scheme for a plan by fetching plan metadata (cached).
 * Used in callsites that don't have a token to extract scheme from
 * (402 responses and token generation).
 *
 * @param payments - The Payments instance for API access
 * @param planId - The plan identifier
 * @param explicitScheme - Optional explicit override; returned immediately if provided
 * @returns The resolved scheme type
 */
export declare function resolveScheme(payments: Payments, planId: string, explicitScheme?: X402SchemeType): Promise<X402SchemeType>;
/**
 * The FacilitatorAPI class provides methods to verify and settle AI agent permissions.
 * It enables AI agents to act as facilitators, managing credit verification and settlement
 * for subscribers using X402 access tokens.
 */
export declare class FacilitatorAPI extends BasePaymentsAPI {
    /**
     * Get a singleton instance of the FacilitatorAPI class.
     *
     * @param options - The options to initialize the payments class
     * @returns The instance of the FacilitatorAPI class
     */
    static getInstance(options: PaymentOptions): FacilitatorAPI;
    /**
     * Verify if a subscriber has permission to use credits from a payment plan.
     * This method simulates the credit usage without actually burning credits,
     * checking if the subscriber has sufficient balance and permissions.
     *
     * The planId and subscriberAddress are extracted from the x402AccessToken.
     *
     * @param params - Verification parameters (see {@link VerifyPermissionsParams}).
     *   - paymentRequired: x402 PaymentRequired from 402 response (required, for validation)
     *   - x402AccessToken: X402 access token (contains planId, subscriberAddress, agentId)
     *   - maxAmount: maximum credits to verify (optional, bigint)
     * @returns A promise that resolves to a verification result with 'isValid' boolean
     *
     * @throws PaymentsError if verification fails
     */
    verifyPermissions(params: VerifyPermissionsParams): Promise<VerifyPermissionsResult>;
    /**
     * Settle (burn) credits from a subscriber's payment plan.
     * This method executes the actual credit consumption, burning the specified
     * number of credits from the subscriber's balance. If the subscriber doesn't
     * have enough credits, it will attempt to order more before settling.
     *
     * The planId and subscriberAddress are extracted from the x402AccessToken.
     *
     * @param params - Settlement parameters (see {@link SettlePermissionsParams}).
     *   - paymentRequired: x402 PaymentRequired from 402 response (required, for validation)
     *   - x402AccessToken: X402 access token (contains planId, subscriberAddress, agentId)
     *   - maxAmount: number of credits to burn (optional, bigint)
     *   - agentRequestId: Agent request ID for observability tracking (optional)
     *   - batch: Whether this is a batch request (optional)
     *   - marginPercent: Margin percentage for credit calculation (optional)
     * @returns A promise that resolves to a settlement result with transaction details
     *
     * @throws PaymentsError if settlement fails
     */
    settlePermissions(params: SettlePermissionsParams): Promise<SettlePermissionsResult>;
}
//# sourceMappingURL=facilitator-api.d.ts.map