/**
 * Payment ID Extension Type Definitions
 *
 * Allows servers to attach unique identifiers to payments for
 * correlation, idempotency, and audit trails.
 */
/**
 * Extension key for payment ID in requirements/payload extensions.
 */
declare const PAYMENT_ID_EXTENSION_KEY = "paymentId";
/**
 * Information provided by server about the payment identifier.
 */
interface PaymentIdExtensionInfo {
    /** Unique payment identifier (UUID v4) */
    id: string;
    /** Optional idempotency key for replay protection */
    idempotencyKey?: string;
    /** Optional payment group for batching */
    groupId?: string;
    /** Optional metadata */
    metadata?: Record<string, string>;
}
/**
 * Payment ID extension declaration for server responses.
 */
interface PaymentIdExtension {
    /** Extension information */
    info: PaymentIdExtensionInfo;
    /** JSON Schema for validation */
    schema: object;
}
/**
 * Payment ID payload echoed back by the client.
 */
interface PaymentIdPayload {
    /** Payment ID echoed back from requirements */
    id: string;
    /** Optional client-generated correlation ID */
    clientId?: string;
}
/**
 * Options for declaring a payment ID extension.
 */
interface DeclarePaymentIdOptions {
    /** Custom payment ID (defaults to crypto.randomUUID()) */
    id?: string;
    /** Optional idempotency key for replay protection */
    idempotencyKey?: string;
    /** Optional payment group for batching */
    groupId?: string;
    /** Optional metadata */
    metadata?: Record<string, string>;
}

/**
 * Payment ID Extension Server-Side Implementation
 *
 * Provides functions for servers to declare payment ID requirements,
 * parse client payloads, and validate payment IDs.
 */

/**
 * Declares a payment ID extension for server responses.
 *
 * @param options - Optional configuration for the payment ID
 * @returns Payment ID extension object ready for response
 *
 * @example
 * ```typescript
 * const extension = declarePaymentIdExtension();
 * // Include in PaymentRequired response extensions:
 * // extensions: { [PAYMENT_ID_EXTENSION_KEY]: extension }
 * ```
 */
declare function declarePaymentIdExtension(options?: DeclarePaymentIdOptions): PaymentIdExtension;
/**
 * Parses a payment ID payload from client request extensions.
 *
 * @param extensions - Extensions object from the payment payload
 * @returns Parsed payment ID payload, or null if not present
 * @throws Error if payload is present but invalid
 *
 * @example
 * ```typescript
 * const payload = parsePaymentIdPayload(paymentPayload.extensions);
 * if (payload) {
 *   console.log("Payment ID:", payload.id);
 * }
 * ```
 */
declare function parsePaymentIdPayload(extensions?: Record<string, unknown>): PaymentIdPayload | null;
/**
 * Validates that a client's payment ID payload matches the expected extension.
 *
 * @param payload - The client's payment ID payload
 * @param expected - The expected payment ID from the server extension
 * @returns True if the payment ID matches
 *
 * @example
 * ```typescript
 * const isValid = validatePaymentId(clientPayload, serverExtension.info);
 * if (!isValid) {
 *   throw new Error("Payment ID mismatch");
 * }
 * ```
 */
declare function validatePaymentId(payload: PaymentIdPayload, expected: PaymentIdExtensionInfo): boolean;

/**
 * Payment ID Extension Client-Side Implementation
 *
 * Provides functions for clients to echo payment IDs back to servers.
 */

/**
 * Creates a payment ID payload from a server extension.
 *
 * Reads the payment ID from requirements and echoes it back.
 *
 * @param extension - Payment ID extension from server's 402 response
 * @param clientId - Optional client-generated correlation ID
 * @returns Payment ID payload for inclusion in payment extensions
 *
 * @example
 * ```typescript
 * const extension = paymentRequirements.extensions?.paymentId;
 * const payload = createPaymentIdPayload(extension, "my-correlation-id");
 * // Include in payment payload extensions:
 * // extensions: { [PAYMENT_ID_EXTENSION_KEY]: payload }
 * ```
 */
declare function createPaymentIdPayload(extension: PaymentIdExtension, clientId?: string): PaymentIdPayload;
/**
 * Encodes a payment ID payload for header-based transport.
 *
 * @param payload - The payment ID payload to encode
 * @returns Base64-encoded JSON string
 */
declare function encodePaymentIdHeader(payload: PaymentIdPayload): string;

export { type DeclarePaymentIdOptions, PAYMENT_ID_EXTENSION_KEY, type PaymentIdExtension, type PaymentIdExtensionInfo, type PaymentIdPayload, createPaymentIdPayload, declarePaymentIdExtension, encodePaymentIdHeader, parsePaymentIdPayload, validatePaymentId };