@t402/core 2.3.0 → 2.4.0

package/dist/esm/mechanisms-B-vz5yOj.d.mts

@@ -1,443 +0,0 @@
-type PaymentRequirementsV1 = {
-    scheme: string;
-    network: Network;
-    maxAmountRequired: string;
-    resource: string;
-    description: string;
-    mimeType: string;
-    outputSchema: Record<string, unknown>;
-    payTo: string;
-    maxTimeoutSeconds: number;
-    asset: string;
-    extra: Record<string, unknown>;
-};
-type PaymentRequiredV1 = {
-    t402Version: 1;
-    error?: string;
-    accepts: PaymentRequirementsV1[];
-};
-type PaymentPayloadV1 = {
-    t402Version: 1;
-    scheme: string;
-    network: Network;
-    payload: Record<string, unknown>;
-};
-type VerifyRequestV1 = {
-    paymentPayload: PaymentPayloadV1;
-    paymentRequirements: PaymentRequirementsV1;
-};
-type SettleRequestV1 = {
-    paymentPayload: PaymentPayloadV1;
-    paymentRequirements: PaymentRequirementsV1;
-};
-type SettleResponseV1 = {
-    success: boolean;
-    errorReason?: string;
-    payer?: string;
-    transaction: string;
-    network: Network;
-};
-type SupportedResponseV1 = {
-    kinds: {
-        t402Version: number;
-        scheme: string;
-        network: Network;
-        extra?: Record<string, unknown>;
-    }[];
-};
-
-interface ResourceServerExtension {
-    key: string;
-    enrichDeclaration?: (declaration: unknown, transportContext: unknown) => unknown;
-}
-
-/**
- * Up-To Scheme Types
- *
- * The `upto` scheme authorizes transfer of up to a maximum amount,
- * enabling usage-based billing where the final settlement amount
- * is determined by actual usage.
- *
- * @example
- * ```typescript
- * // Client authorizes up to $1.00
- * const requirements: UptoPaymentRequirements = {
- *   scheme: 'upto',
- *   network: 'eip155:8453',
- *   maxAmount: '1000000',  // $1.00 in USDC
- *   minAmount: '10000',    // $0.01 minimum
- *   asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
- *   payTo: '0x...',
- *   maxTimeoutSeconds: 300,
- *   extra: {
- *     unit: 'token',
- *     unitPrice: '100',
- *   },
- * };
- *
- * // Server settles for actual usage ($0.15)
- * const settlement: UptoSettlement = {
- *   settleAmount: '150000',
- *   usageDetails: {
- *     tokensGenerated: 1500,
- *     unitPrice: '100',
- *   },
- * };
- * ```
- */
-
-/**
- * Extended payment requirements for the upto scheme.
- */
-interface UptoPaymentRequirements extends Omit<PaymentRequirements, "scheme" | "amount"> {
-    /** Scheme identifier - always 'upto' */
-    scheme: "upto";
-    /** Network identifier (CAIP-2 format) */
-    network: Network;
-    /** Maximum amount the client authorizes (in smallest denomination) */
-    maxAmount: string;
-    /** Minimum settlement amount (prevents dust payments) */
-    minAmount?: string;
-    /** Asset contract address or identifier */
-    asset: string;
-    /** Recipient address */
-    payTo: string;
-    /** Maximum time in seconds before payment expires */
-    maxTimeoutSeconds: number;
-    /** Additional scheme-specific data */
-    extra: UptoExtra;
-}
-/**
- * Extra fields specific to the upto scheme.
- */
-interface UptoExtra extends Record<string, unknown> {
-    /** Billing unit (e.g., 'token', 'request', 'second', 'byte') */
-    unit?: string;
-    /** Price per unit in smallest denomination */
-    unitPrice?: string;
-    /** EIP-712 domain name (for EVM) */
-    name?: string;
-    /** EIP-712 domain version (for EVM) */
-    version?: string;
-    /** Router contract address (for EVM) */
-    routerAddress?: string;
-}
-/**
- * Base payload structure for upto scheme.
- */
-interface UptoPayloadBase {
-    /** Unique nonce to prevent replay attacks */
-    nonce: string;
-}
-/**
- * EVM-specific upto payload using EIP-2612 Permit.
- */
-interface UptoEvmPayload extends UptoPayloadBase {
-    /** EIP-2612 permit signature components */
-    signature: {
-        v: number;
-        r: `0x${string}`;
-        s: `0x${string}`;
-    };
-    /** Permit authorization parameters */
-    authorization: {
-        /** Token owner address */
-        owner: `0x${string}`;
-        /** Spender address (router contract) */
-        spender: `0x${string}`;
-        /** Maximum authorized value */
-        value: string;
-        /** Permit deadline (unix timestamp) */
-        deadline: string;
-        /** Permit nonce (from token contract) */
-        nonce: number;
-    };
-}
-/**
- * Alternative EVM payload with combined signature.
- */
-interface UptoEvmPayloadCompact extends UptoPayloadBase {
-    /** Combined EIP-2612 permit signature */
-    signature: `0x${string}`;
-    /** Permit authorization parameters */
-    authorization: {
-        owner: `0x${string}`;
-        spender: `0x${string}`;
-        value: string;
-        deadline: string;
-        nonce: number;
-    };
-}
-/**
- * Settlement request for upto scheme.
- */
-interface UptoSettlement {
-    /** Actual amount to settle (must be <= maxAmount) */
-    settleAmount: string;
-    /** Optional usage details for auditing */
-    usageDetails?: UptoUsageDetails;
-}
-/**
- * Usage details for settlement auditing.
- */
-interface UptoUsageDetails {
-    /** Number of units consumed */
-    unitsConsumed?: number;
-    /** Price per unit used */
-    unitPrice?: string;
-    /** Type of unit */
-    unitType?: string;
-    /** Start timestamp of usage period */
-    startTime?: number;
-    /** End timestamp of usage period */
-    endTime?: number;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Settlement response for upto scheme.
- */
-interface UptoSettlementResponse {
-    /** Whether settlement was successful */
-    success: boolean;
-    /** Transaction hash (if on-chain) */
-    transactionHash?: string;
-    /** Actual amount settled */
-    settledAmount: string;
-    /** Maximum amount that was authorized */
-    maxAmount: string;
-    /** Block number (if on-chain) */
-    blockNumber?: number;
-    /** Gas used (if on-chain) */
-    gasUsed?: string;
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Validation result for upto payment.
- */
-interface UptoValidationResult {
-    /** Whether the payment is valid */
-    isValid: boolean;
-    /** Reason if invalid */
-    invalidReason?: string;
-    /** Validated maximum amount */
-    validatedMaxAmount?: string;
-    /** Payer address */
-    payer?: string;
-    /** Expiration timestamp */
-    expiresAt?: number;
-}
-/**
- * Type guard for UptoPaymentRequirements.
- *
- * @param requirements - The value to check
- * @returns True if the value is UptoPaymentRequirements
- */
-declare function isUptoPaymentRequirements(requirements: unknown): requirements is UptoPaymentRequirements;
-/**
- * Type guard for UptoEvmPayload.
- *
- * @param payload - The value to check
- * @returns True if the value is UptoEvmPayload
- */
-declare function isUptoEvmPayload(payload: unknown): payload is UptoEvmPayload;
-/**
- * Constants for upto scheme.
- */
-declare const UPTO_SCHEME: "upto";
-declare const UPTO_DEFAULTS: {
-    /** Default minimum settlement amount (prevents dust) */
-    readonly MIN_AMOUNT: "1000";
-    /** Default maximum timeout in seconds (5 minutes) */
-    readonly MAX_TIMEOUT_SECONDS: 300;
-    /** Supported billing units */
-    readonly UNITS: readonly ["token", "request", "second", "minute", "byte", "kb", "mb"];
-};
-type UptoUnit = (typeof UPTO_DEFAULTS.UNITS)[number];
-
-type Network = `${string}:${string}`;
-type Money = string | number;
-type AssetAmount = {
-    asset: string;
-    amount: string;
-    extra?: Record<string, unknown>;
-};
-type Price = Money | AssetAmount;
-
-interface ResourceInfo {
-    url: string;
-    description?: string;
-    mimeType?: string;
-}
-type PaymentRequirements = {
-    scheme: string;
-    network: Network;
-    asset: string;
-    amount: string;
-    payTo: string;
-    maxTimeoutSeconds: number;
-    extra: Record<string, unknown>;
-};
-type PaymentRequired = {
-    t402Version: number;
-    error?: string;
-    resource: ResourceInfo;
-    accepts: PaymentRequirements[];
-    extensions?: Record<string, unknown>;
-};
-type PaymentPayload = {
-    t402Version: number;
-    resource?: ResourceInfo;
-    accepted: PaymentRequirements;
-    payload: Record<string, unknown>;
-    extensions?: Record<string, unknown>;
-};
-
-type VerifyRequest = {
-    paymentPayload: PaymentPayload;
-    paymentRequirements: PaymentRequirements;
-};
-type VerifyResponse = {
-    isValid: boolean;
-    invalidReason?: string;
-    payer?: string;
-};
-type SettleRequest = {
-    paymentPayload: PaymentPayload;
-    paymentRequirements: PaymentRequirements;
-};
-type SettleResponse = {
-    success: boolean;
-    errorReason?: string;
-    payer?: string;
-    transaction: string;
-    network: Network;
-};
-type SupportedKind = {
-    t402Version: number;
-    scheme: string;
-    network: Network;
-    extra?: Record<string, unknown>;
-};
-type SupportedResponse = {
-    kinds: SupportedKind[];
-    extensions: string[];
-    signers: Record<string, string[]>;
-};
-
-/**
- * Money parser function that converts a numeric amount to an AssetAmount
- * Receives the amount as a decimal number (e.g., 1.50 for $1.50)
- * Returns null to indicate "cannot handle this amount", causing fallback to next parser
- * Always returns a Promise for consistency - use async/await
- *
- * @param amount - The decimal amount (e.g., 1.50)
- * @param network - The network identifier for context
- * @returns AssetAmount or null to try next parser
- */
-type MoneyParser = (amount: number, network: Network) => Promise<AssetAmount | null>;
-interface SchemeNetworkClient {
-    readonly scheme: string;
-    createPaymentPayload(t402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "t402Version" | "payload">>;
-}
-interface SchemeNetworkFacilitator {
-    readonly scheme: string;
-    /**
-     * CAIP family pattern that this facilitator supports.
-     * Used to group signers by blockchain family in the supported response.
-     *
-     * @example
-     * // EVM facilitators
-     * readonly caipFamily = "eip155:*";
-     *
-     * @example
-     * // SVM facilitators
-     * readonly caipFamily = "solana:*";
-     */
-    readonly caipFamily: string;
-    /**
-     * Get mechanism-specific extra data needed for the supported kinds endpoint.
-     * This method is called when building the facilitator's supported response.
-     *
-     * @param network - The network identifier for context
-     * @returns Extra data object or undefined if no extra data is needed
-     *
-     * @example
-     * // EVM schemes return undefined (no extra data needed)
-     * getExtra(network: Network): undefined {
-     *   return undefined;
-     * }
-     *
-     * @example
-     * // SVM schemes return feePayer address
-     * getExtra(network: Network): Record<string, unknown> | undefined {
-     *   return { feePayer: this.signer.address };
-     * }
-     */
-    getExtra(network: Network): Record<string, unknown> | undefined;
-    /**
-     * Get signer addresses used by this facilitator for a given network.
-     * These are included in the supported response to help clients understand
-     * which addresses might sign/pay for transactions.
-     *
-     * Supports multiple addresses for load balancing, key rotation, and high availability.
-     *
-     * @param network - The network identifier
-     * @returns Array of signer addresses (wallet addresses, fee payer addresses, etc.)
-     *
-     * @example
-     * // EVM facilitator
-     * getSigners(network: string): string[] {
-     *   return [...this.signer.getAddresses()];
-     * }
-     *
-     * @example
-     * // SVM facilitator
-     * getSigners(network: string): string[] {
-     *   return [...this.signer.getAddresses()];
-     * }
-     */
-    getSigners(network: string): string[];
-    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
-    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
-}
-interface SchemeNetworkServer {
-    readonly scheme: string;
-    /**
-     * Convert a user-friendly price to the scheme's specific amount and asset format
-     * Always returns a Promise for consistency
-     *
-     * @param price - User-friendly price (e.g., "$0.10", "0.10", { amount: "100000", asset: "USDC" })
-     * @param network - The network identifier for context
-     * @returns Promise that resolves to the converted amount, asset identifier, and any extra metadata
-     *
-     * @example
-     * // For EVM networks with USDC:
-     * await parsePrice("$0.10", "eip155:8453") => { amount: "100000", asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }
-     *
-     * // For custom schemes:
-     * await parsePrice("10 points", "custom:network") => { amount: "10", asset: "points" }
-     */
-    parsePrice(price: Price, network: Network): Promise<AssetAmount>;
-    /**
-     * Build payment requirements for this scheme/network combination
-     *
-     * @param paymentRequirements - Base payment requirements with amount/asset already set
-     * @param supportedKind - The supported kind from facilitator's /supported endpoint
-     * @param supportedKind.t402Version - The t402 version
-     * @param supportedKind.scheme - The payment scheme
-     * @param supportedKind.network - The network identifier
-     * @param supportedKind.extra - Optional extra metadata
-     * @param facilitatorExtensions - Extensions supported by the facilitator
-     * @returns Enhanced payment requirements ready to be sent to clients
-     */
-    enhancePaymentRequirements(paymentRequirements: PaymentRequirements, supportedKind: {
-        t402Version: number;
-        scheme: string;
-        network: Network;
-        extra?: Record<string, unknown>;
-    }, facilitatorExtensions: string[]): Promise<PaymentRequirements>;
-}
-
-export { type AssetAmount as A, type UptoUnit as B, isUptoPaymentRequirements as C, isUptoEvmPayload as D, UPTO_SCHEME as E, UPTO_DEFAULTS as F, type Money as M, type Network as N, type PaymentRequirements as P, type ResourceServerExtension as R, type SettleResponse as S, type UptoPaymentRequirements as U, type VerifyResponse as V, type PaymentPayload as a, type SchemeNetworkFacilitator as b, type PaymentRequired as c, type SchemeNetworkClient as d, type SupportedResponse as e, type SchemeNetworkServer as f, type SupportedKind as g, type Price as h, type PaymentRequirementsV1 as i, type PaymentRequiredV1 as j, type PaymentPayloadV1 as k, type VerifyRequestV1 as l, type SettleRequestV1 as m, type SettleResponseV1 as n, type SupportedResponseV1 as o, type VerifyRequest as p, type SettleRequest as q, type MoneyParser as r, type UptoExtra as s, type UptoPayloadBase as t, type UptoEvmPayload as u, type UptoEvmPayloadCompact as v, type UptoSettlement as w, type UptoUsageDetails as x, type UptoSettlementResponse as y, type UptoValidationResult as z };