@anuragchvn-blip/mandatekit/dist/types/index.d.ts

Production-ready Web3 autopay SDK for crypto-based recurring payments using EIP-712 mandates

/**
 * Core type definitions for MandateKit SDK
 * @module types
 */
import type { Address, Hex, TypedDataDomain } from 'viem';
/**
 * Cadence interval types for recurring payments
 */
export type CadenceInterval = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'custom';
/**
 * Cadence configuration for recurring payments
 * Defines the frequency and interval of automated payments
 */
export interface Cadence {
    /** The type of interval (daily, weekly, monthly, yearly, custom) */
    interval: CadenceInterval;
    /** Number of intervals between payments (e.g., 2 for bi-weekly if interval is 'weekly') */
    count: number;
    /** For custom intervals: number of seconds between payments */
    customSeconds?: number;
}
/**
 * Core mandate structure representing a recurring payment authorization
 * Uses EIP-712 typed data for secure signing
 */
export interface Mandate {
    /** Address of the subscriber authorizing the payments */
    subscriber: Address;
    /** Token contract address for payments */
    token: Address;
    /** Amount per payment (in token's smallest unit, e.g., wei) */
    amount: bigint | string;
    /** Payment frequency configuration */
    cadence: Cadence;
    /** Address receiving the payments */
    recipient: Address;
    /** Unix timestamp - mandate valid after this time */
    validAfter: number;
    /** Unix timestamp - mandate expires after this time */
    validBefore: number;
    /** Nonce for replay protection (unique per subscriber) */
    nonce: bigint | string;
    /** Optional maximum number of payments allowed */
    maxPayments?: number;
    /** Optional metadata or reference string */
    metadata?: string;
}
/**
 * Signed mandate with cryptographic proof
 */
export interface SignedMandate extends Mandate {
    /** EIP-712 signature from subscriber */
    signature: Hex;
    /** Timestamp when mandate was signed */
    signedAt: number;
    /** Chain ID where mandate is valid */
    chainId: number;
}
/**
 * EIP-712 domain configuration for mandate signing
 */
export interface MandateDomain extends TypedDataDomain {
    name: string;
    version: string;
    chainId: number;
    verifyingContract: Address;
}
/**
 * Payment execution record for tracking and verification
 */
export interface PaymentRecord {
    /** Reference to the mandate ID or hash */
    mandateHash: Hex;
    /** Execution sequence number (1, 2, 3...) */
    executionCount: number;
    /** Unix timestamp when payment was executed */
    executedAt: number;
    /** Transaction hash of the execution */
    txHash: Hex;
    /** Actual amount paid (may differ slightly due to precision) */
    amountPaid: bigint;
    /** Address that executed the payment (relayer) */
    executor: Address;
    /** Gas used for the transaction */
    gasUsed: bigint;
}
/**
 * Execution plan for scheduled payments
 */
export interface ExecutionPlan {
    /** Mandate being executed */
    mandate: SignedMandate;
    /** Next scheduled execution timestamp */
    nextExecution: number;
    /** Number of payments executed so far */
    executionCount: number;
    /** Whether the mandate is still active */
    isActive: boolean;
    /** Reason if mandate is inactive */
    inactiveReason?: string;
    /** Estimated gas cost for next execution */
    estimatedGas?: bigint;
}
/**
 * Relayer configuration
 */
export interface RelayerConfig {
    /** RPC URL for blockchain connection */
    rpcUrl: string;
    /** Chain ID */
    chainId: number;
    /** Registry contract address */
    registryAddress: Address;
    /** Relayer's private key or account */
    account: Address | Hex;
    /** Optional gas price strategy */
    gasPriceStrategy?: 'fast' | 'standard' | 'slow';
    /** Optional maximum gas price in gwei */
    maxGasPrice?: bigint;
    /** Optional webhook URL for notifications */
    webhookUrl?: string;
}
/**
 * Mandate verification result
 */
export interface VerificationResult {
    /** Whether the signature is valid */
    isValid: boolean;
    /** Whether the mandate is still active */
    isActive: boolean;
    /** Whether the mandate is within valid time range */
    isWithinTimeRange: boolean;
    /** Whether the next execution is due */
    isExecutionDue: boolean;
    /** Recovered signer address */
    recoveredSigner?: Address;
    /** Any validation errors */
    errors: string[];
}
/**
 * Nonce management for replay protection
 */
export interface NonceManager {
    /** Get current nonce for an address */
    getCurrentNonce: (address: Address) => Promise<bigint>;
    /** Increment and return next nonce */
    getNextNonce: (address: Address) => Promise<bigint>;
    /** Check if nonce has been used */
    isNonceUsed: (address: Address, nonce: bigint) => Promise<boolean>;
    /** Invalidate/mark nonce as used */
    invalidateNonce: (address: Address, nonce: bigint) => Promise<void>;
}
/**
 * EIP-712 typed data structure for mandate signing
 */
export interface MandateTypedData {
    domain: MandateDomain;
    types: {
        Mandate: Array<{
            name: string;
            type: string;
        }>;
    };
    primaryType: 'Mandate';
    message: Omit<Mandate, 'metadata' | 'maxPayments'> & {
        metadata?: string;
        maxPayments?: string | number;
    };
}
/**
 * Gas estimation result
 */
export interface GasEstimate {
    /** Estimated gas limit */
    gasLimit: bigint;
    /** Estimated gas price */
    gasPrice: bigint;
    /** Estimated total cost in native token */
    totalCost: bigint;
    /** Estimated cost in USD (if available) */
    totalCostUsd?: number;
}
/**
 * Generic success response
 */
export interface SuccessResponse<T = unknown> {
    success: true;
    data: T;
}
/**
 * Generic error response
 */
export interface ErrorResponse {
    success: false;
    error: {
        code: string;
        message: string;
        details?: unknown;
    };
}
/**
 * API response type
 */
export type ApiResponse<T = unknown> = SuccessResponse<T> | ErrorResponse;
//# sourceMappingURL=index.d.ts.map