/**
 * Escrow-backed payment authorization for the Direct Data Controller.
 *
 * @remarks
 * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal
 * Server read returns `402 Payment Required`, the controller settles the
 * challenged operation through the escrow gateway:
 *
 *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.
 *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.
 *  3. Map the gateway's {@link EscrowPayResult} into a typed
 *     {@link DirectPaymentReceipt} for the caller to inspect.
 *
 * This module supports legacy `"grant"` operations and receipt-bound
 * `"data_access"` operations. It adapts the escrow `payForOp` flow to the
 * direct-read use case; it does not define its own payment scheme.
 *
 * @category Direct
 * @module direct/escrow-payment
 */
import { GENERIC_PAYMENT_TYPES, genericPaymentDomain, type EscrowPaymentClient, type EscrowPayResult, type PaymentBreakdown } from "../protocol/escrow.js";
import type { DirectFeeBreakdown, DirectPaymentReceipt, DirectPaymentResponseMetadata, PersonalServerPaymentOperation, PersonalServerPaymentRequired } from "./types.js";
/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */
export declare const GRANT_OP_TYPE: "grant";
/** The escrow `GenericPayment.opType` used for receipt-bound data access. */
export declare const DATA_ACCESS_OP_TYPE: "data_access";
/**
 * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).
 *
 * @remarks
 * Kept structurally minimal so any viem account/wallet client satisfies it
 * without the SDK depending on viem's exact `signTypedData` overload set.
 */
export type SignTypedDataFn = (args: {
    domain: ReturnType<typeof genericPaymentDomain>;
    types: typeof GENERIC_PAYMENT_TYPES;
    primaryType: "GenericPayment";
    message: {
        payerAddress: `0x${string}`;
        opType: string;
        opId: `0x${string}`;
        asset: `0x${string}`;
        amount: bigint;
        paymentNonce: bigint;
    };
}) => Promise<`0x${string}`>;
/** Supplies a monotonically-increasing payment nonce per payer. */
export type PaymentNonceSource = (payerAddress: string) => Promise<bigint> | bigint;
/** Configuration required to sign an escrow X-PAYMENT header. */
export interface EscrowPaymentHeaderConfig {
    /** Deployed `DataPortabilityEscrow` contract address. */
    escrowContract: `0x${string}`;
    /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */
    chainId: number;
    /** App EIP-712 signer. */
    signTypedData: SignTypedDataFn;
    /**
     * Supplies the next payment nonce for a payer. Defaults to a process-local
     * monotonic counter seeded at 1. Provide a durable source in production so
     * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).
     */
    nonceSource?: PaymentNonceSource;
}
/**
 * Escrow settlement configuration for gateway authorization.
 *
 * @remarks
 * Extends the header-signing boundary with the gateway client used by
 * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper
 * callers can continue to provide this full configuration.
 */
export interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {
    /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */
    client: EscrowPaymentClient;
}
/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */
export declare function toDirectFeeBreakdown(breakdown: PaymentBreakdown): DirectFeeBreakdown;
/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */
export declare function toDirectPaymentReceipt(result: EscrowPayResult): DirectPaymentReceipt;
/** Default in-process monotonic nonce counter (seeded at 1 per payer). */
export declare function createDefaultNonceSource(): PaymentNonceSource;
/**
 * Build the canonical X-PAYMENT header for a validated escrow operation.
 *
 * @remarks
 * Supports both legacy grant payments and receipt-bound data-access payments.
 * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.
 */
export declare function buildEscrowPaymentHeader(params: {
    /** Address whose escrow balance pays for the operation. */
    payerAddress: `0x${string}`;
    /** Validated operation parsed from the Personal Server challenge. */
    required: PersonalServerPaymentOperation;
    /** Escrow contract, chain, signer, and nonce configuration. */
    config: EscrowPaymentHeaderConfig;
}): Promise<string>;
/** Build a legacy grant X-PAYMENT header. */
export declare function buildGrantPaymentHeader(params: {
    payerAddress: `0x${string}`;
    required: PersonalServerPaymentRequired;
    config: EscrowPaymentConfig;
}): Promise<string>;
/**
 * Parse shape-validated payment response metadata echoed by a Personal Server.
 *
 * @remarks
 * This metadata is not authenticated by the gateway. It is suitable for
 * display and debugging, not as proof that a payment occurred.
 */
export declare function paymentResponseMetadataFromHeader(header: string | null | undefined): DirectPaymentResponseMetadata | undefined;
/**
 * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal
 * Server response header is untrusted metadata, not a gateway-authenticated
 * receipt.
 */
export declare function paymentReceiptFromHeader(header: string | null | undefined): DirectPaymentResponseMetadata | undefined;
/**
 * Authorize an escrow payment for a grant data-access fee.
 *
 * @param params - The payment requirement, the payer address, and escrow config.
 * @returns The gateway's {@link EscrowPayResult} as a typed
 * {@link DirectPaymentReceipt}.
 */
export declare function authorizeGrantPayment(params: {
    payerAddress: `0x${string}`;
    required: PersonalServerPaymentRequired;
    config: EscrowPaymentConfig;
}): Promise<DirectPaymentReceipt>;
/**
 * Authorize a validated grant or data-access operation through the escrow
 * gateway.
 */
export declare function authorizeEscrowPayment(params: {
    /** Address whose escrow balance pays for the operation. */
    payerAddress: `0x${string}`;
    /** Validated operation to authorize. */
    required: PersonalServerPaymentOperation;
    /** Escrow gateway and signing configuration. */
    config: EscrowPaymentConfig;
}): Promise<DirectPaymentReceipt>;