moltspay 0.5.2 → 0.5.4

package/dist/index.d.mts

@@ -935,4 +935,550 @@ declare class CDPWallet {
     getViemAccount(): Promise<unknown>;
 }
 
-export { AgentWallet, AuditAction, AuditEntry, AuditLog, BuyerTemplates, type CDPInitResult, CDPWallet, type CDPWalletConfig, type CDPWalletData, ChainConfig, ChainName, CreateInvoiceParams, type EIP3009Authorization, Invoice, PAYMENT_HEADER, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAgent, PaymentAgentConfig, type Receipt, type ReceiptParams, SellerTemplates, StatusMarkers, VerifyOptions, VerifyResult, WalletBalance, type X402Client, type X402ClientConfig, type X402PaymentPayload, type X402PaymentRequirements, X402_VERSION, chainToNetwork, createExactEvmPayload, createPaymentRequiredResponse, createX402Client, encodePaymentPayload, formatReceiptJson, formatReceiptMessage, formatReceiptText, generateReceipt, generateReceiptFromInvoice, getAgentAddress, getCDPWalletAddress, getChain, initCDPWallet, isCDPAvailable, isX402Available, loadCDPWallet, networkToChain, parsePaymentRequired, parseStatusMarker, signEIP3009, verifyPaymentHeader, wrapFetchWith402, x402Fetch };
+/**
+ * Deferred Payment Types
+ *
+ * Supports credit-based, milestone, and subscription payment models
+ * for trusted Agent-to-Agent transactions.
+ */
+
+interface CreditAccount {
+    /** Unique account identifier */
+    accountId: string;
+    /** Buyer/debtor address or identifier */
+    buyerId: string;
+    /** Seller/creditor address */
+    sellerId: string;
+    /** Credit limit in USDC */
+    creditLimit: number;
+    /** Current balance owed (positive = buyer owes seller) */
+    balance: number;
+    /** Account status */
+    status: CreditAccountStatus;
+    /** Settlement chain */
+    chain: ChainName;
+    /** Payment terms */
+    terms: PaymentTerms;
+    /** Account creation time */
+    createdAt: string;
+    /** Last activity time */
+    updatedAt: string;
+    /** Transaction history */
+    transactions: CreditTransaction[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+type CreditAccountStatus = 'active' | 'suspended' | 'closed' | 'pending';
+interface PaymentTerms {
+    /** Net days for payment (e.g., 30 = Net-30) */
+    netDays: number;
+    /** Grace period after due date before suspension */
+    graceDays: number;
+    /** Settlement frequency: on-demand, daily, weekly, monthly */
+    settlementFrequency: SettlementFrequency;
+    /** Minimum balance to trigger auto-settlement */
+    autoSettleThreshold?: number;
+    /** Late fee percentage (optional) */
+    lateFeePercent?: number;
+}
+type SettlementFrequency = 'on-demand' | 'daily' | 'weekly' | 'monthly';
+interface CreditTransaction {
+    /** Transaction ID */
+    txId: string;
+    /** Transaction type */
+    type: CreditTransactionType;
+    /** Amount (positive for charges, negative for payments/credits) */
+    amount: number;
+    /** Running balance after this transaction */
+    balanceAfter: number;
+    /** Reference (order ID, service name, etc.) */
+    reference: string;
+    /** Optional on-chain tx hash for settlements */
+    onChainTxHash?: string;
+    /** Transaction time */
+    timestamp: string;
+    /** Notes */
+    notes?: string;
+}
+type CreditTransactionType = 'charge' | 'payment' | 'credit' | 'adjustment' | 'late_fee' | 'refund';
+interface DeferredPayment {
+    /** Payment ID */
+    paymentId: string;
+    /** Associated credit account (if using credit) */
+    accountId?: string;
+    /** Order/service ID */
+    orderId: string;
+    /** Service description */
+    service: string;
+    /** Total amount */
+    amount: number;
+    /** Amount paid so far */
+    paidAmount: number;
+    /** Payment status */
+    status: DeferredPaymentStatus;
+    /** Due date (ISO string) */
+    dueDate: string;
+    /** Settlement chain */
+    chain: ChainName;
+    /** Buyer identifier */
+    buyerId: string;
+    /** Seller address */
+    sellerAddress: string;
+    /** Payment plan (for installments) */
+    plan?: PaymentPlan;
+    /** Creation time */
+    createdAt: string;
+    /** Last update time */
+    updatedAt: string;
+    /** Settlement transactions */
+    settlements: Settlement[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+type DeferredPaymentStatus = 'pending' | 'partial' | 'paid' | 'overdue' | 'settled' | 'cancelled' | 'disputed';
+interface PaymentPlan {
+    /** Plan type */
+    type: 'fixed' | 'milestone' | 'subscription';
+    /** Total installments */
+    totalInstallments: number;
+    /** Completed installments */
+    completedInstallments: number;
+    /** Installment schedule */
+    schedule: Installment[];
+}
+interface Installment {
+    /** Installment number (1-based) */
+    number: number;
+    /** Amount for this installment */
+    amount: number;
+    /** Due date */
+    dueDate: string;
+    /** Status */
+    status: 'pending' | 'paid' | 'overdue';
+    /** Settlement tx hash (if paid) */
+    txHash?: string;
+    /** Milestone description (for milestone-based) */
+    milestone?: string;
+}
+interface Settlement {
+    /** Settlement ID */
+    settlementId: string;
+    /** Amount settled */
+    amount: number;
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Chain */
+    chain: ChainName;
+    /** Settlement time */
+    timestamp: string;
+    /** Verification status */
+    verified: boolean;
+}
+interface CreateCreditAccountParams {
+    buyerId: string;
+    sellerId: string;
+    creditLimit: number;
+    chain?: ChainName;
+    terms?: Partial<PaymentTerms>;
+    metadata?: Record<string, unknown>;
+}
+interface CreateDeferredPaymentParams {
+    accountId?: string;
+    orderId: string;
+    service: string;
+    amount: number;
+    buyerId: string;
+    sellerAddress: string;
+    chain?: ChainName;
+    dueInDays?: number;
+    plan?: Omit<PaymentPlan, 'completedInstallments'>;
+    metadata?: Record<string, unknown>;
+}
+interface RecordSettlementParams {
+    paymentId: string;
+    amount: number;
+    txHash: string;
+    chain?: ChainName;
+}
+interface DeferredPaymentStore {
+    createAccount(params: CreateCreditAccountParams): Promise<CreditAccount>;
+    getAccount(accountId: string): Promise<CreditAccount | null>;
+    getAccountByBuyer(buyerId: string, sellerId: string): Promise<CreditAccount | null>;
+    updateAccount(accountId: string, updates: Partial<CreditAccount>): Promise<CreditAccount>;
+    listAccounts(sellerId: string): Promise<CreditAccount[]>;
+    createPayment(params: CreateDeferredPaymentParams): Promise<DeferredPayment>;
+    getPayment(paymentId: string): Promise<DeferredPayment | null>;
+    updatePayment(paymentId: string, updates: Partial<DeferredPayment>): Promise<DeferredPayment>;
+    listPayments(filter: PaymentFilter): Promise<DeferredPayment[]>;
+    addTransaction(accountId: string, tx: Omit<CreditTransaction, 'txId' | 'timestamp'>): Promise<CreditTransaction>;
+}
+interface PaymentFilter {
+    accountId?: string;
+    buyerId?: string;
+    sellerId?: string;
+    status?: DeferredPaymentStatus | DeferredPaymentStatus[];
+    overdueOnly?: boolean;
+}
+
+/**
+ * Deferred Payment Manager
+ *
+ * Manages credit accounts and deferred payments for Agent-to-Agent transactions.
+ * Supports credit-based, milestone, and installment payment models.
+ */
+
+interface DeferredPaymentManagerConfig {
+    /** Seller's wallet address for receiving payments */
+    sellerAddress: string;
+    /** Seller's identifier */
+    sellerId: string;
+    /** Default chain for payments */
+    chain?: ChainName;
+    /** Custom store implementation (defaults to MemoryDeferredStore) */
+    store?: DeferredPaymentStore;
+    /** Auto-verify settlements on-chain */
+    autoVerify?: boolean;
+}
+interface ChargeResult {
+    success: boolean;
+    payment?: DeferredPayment;
+    transaction?: CreditTransaction;
+    error?: string;
+    /** True if credit limit would be exceeded */
+    creditExceeded?: boolean;
+}
+interface SettlementResult {
+    success: boolean;
+    settlement?: Settlement;
+    payment?: DeferredPayment;
+    transaction?: CreditTransaction;
+    error?: string;
+}
+interface AccountSummary {
+    account: CreditAccount;
+    pendingPayments: DeferredPayment[];
+    overduePayments: DeferredPayment[];
+    availableCredit: number;
+    totalOwed: number;
+}
+declare class DeferredPaymentManager {
+    private config;
+    constructor(config: DeferredPaymentManagerConfig);
+    /**
+     * Create a new credit account for a buyer
+     */
+    createCreditAccount(params: {
+        buyerId: string;
+        creditLimit: number;
+        netDays?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<CreditAccount>;
+    /**
+     * Get or create a credit account for a buyer
+     */
+    getOrCreateAccount(params: {
+        buyerId: string;
+        creditLimit?: number;
+    }): Promise<CreditAccount>;
+    /**
+     * Get credit account by ID
+     */
+    getAccount(accountId: string): Promise<CreditAccount | null>;
+    /**
+     * Get credit account by buyer ID
+     */
+    getAccountByBuyer(buyerId: string): Promise<CreditAccount | null>;
+    /**
+     * Update credit limit
+     */
+    updateCreditLimit(accountId: string, newLimit: number): Promise<CreditAccount>;
+    /**
+     * Suspend an account
+     */
+    suspendAccount(accountId: string, reason?: string): Promise<CreditAccount>;
+    /**
+     * Reactivate a suspended account
+     */
+    reactivateAccount(accountId: string): Promise<CreditAccount>;
+    /**
+     * Get account summary with pending/overdue payments
+     */
+    getAccountSummary(accountId: string): Promise<AccountSummary | null>;
+    /**
+     * List all credit accounts for this seller
+     */
+    listAccounts(): Promise<CreditAccount[]>;
+    /**
+     * Charge a service to a credit account (deferred payment)
+     */
+    charge(params: {
+        buyerId: string;
+        orderId: string;
+        service: string;
+        amount: number;
+        dueInDays?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<ChargeResult>;
+    /**
+     * Create a deferred payment without a credit account (standalone)
+     */
+    createDeferredPayment(params: CreateDeferredPaymentParams): Promise<DeferredPayment>;
+    /**
+     * Get deferred payment by ID
+     */
+    getPayment(paymentId: string): Promise<DeferredPayment | null>;
+    /**
+     * List deferred payments with filters
+     */
+    listPayments(filter?: PaymentFilter): Promise<DeferredPayment[]>;
+    /**
+     * Get overdue payments
+     */
+    getOverduePayments(): Promise<DeferredPayment[]>;
+    /**
+     * Record a settlement (payment received)
+     */
+    recordSettlement(params: RecordSettlementParams): Promise<SettlementResult>;
+    /**
+     * Settle all pending charges for an account
+     */
+    settleAccount(accountId: string, txHash: string): Promise<SettlementResult>;
+    /**
+     * Issue a credit (reduce balance owed)
+     */
+    issueCredit(params: {
+        accountId: string;
+        amount: number;
+        reason: string;
+    }): Promise<CreditTransaction>;
+    /**
+     * Issue a refund
+     */
+    issueRefund(params: {
+        paymentId: string;
+        amount: number;
+        reason: string;
+    }): Promise<SettlementResult>;
+    /**
+     * Mark overdue payments
+     */
+    markOverduePayments(): Promise<DeferredPayment[]>;
+    /**
+     * Apply late fees to overdue accounts
+     */
+    applyLateFees(): Promise<CreditTransaction[]>;
+}
+
+/**
+ * In-Memory Store for Deferred Payments
+ *
+ * Suitable for testing and single-process deployments.
+ * For production, implement DeferredPaymentStore with persistent storage.
+ */
+
+declare class MemoryDeferredStore implements DeferredPaymentStore {
+    private accounts;
+    private payments;
+    private buyerSellerIndex;
+    private makeKey;
+    createAccount(params: CreateCreditAccountParams): Promise<CreditAccount>;
+    getAccount(accountId: string): Promise<CreditAccount | null>;
+    getAccountByBuyer(buyerId: string, sellerId: string): Promise<CreditAccount | null>;
+    updateAccount(accountId: string, updates: Partial<CreditAccount>): Promise<CreditAccount>;
+    listAccounts(sellerId: string): Promise<CreditAccount[]>;
+    createPayment(params: CreateDeferredPaymentParams): Promise<DeferredPayment>;
+    getPayment(paymentId: string): Promise<DeferredPayment | null>;
+    updatePayment(paymentId: string, updates: Partial<DeferredPayment>): Promise<DeferredPayment>;
+    listPayments(filter: PaymentFilter): Promise<DeferredPayment[]>;
+    addTransaction(accountId: string, tx: Omit<CreditTransaction, 'txId' | 'timestamp'>): Promise<CreditTransaction>;
+    /**
+     * Get all data (for debugging/export)
+     */
+    export(): {
+        accounts: CreditAccount[];
+        payments: DeferredPayment[];
+    };
+    /**
+     * Import data (for restore)
+     */
+    import(data: {
+        accounts: CreditAccount[];
+        payments: DeferredPayment[];
+    }): void;
+    /**
+     * Clear all data
+     */
+    clear(): void;
+}
+
+/**
+ * JSON File-based Store for Deferred Payments
+ *
+ * Persists deferred payment data to a JSON file.
+ * Suitable for single-process production deployments.
+ *
+ * For multi-process or distributed systems, implement DeferredPaymentStore
+ * with a proper database (PostgreSQL, Redis, etc.).
+ */
+
+interface JsonDeferredStoreConfig {
+    /** Path to the JSON file */
+    filePath: string;
+    /** Auto-save after each write operation (default: true) */
+    autoSave?: boolean;
+    /** Pretty print JSON (default: true) */
+    prettyPrint?: boolean;
+}
+declare class JsonDeferredStore implements DeferredPaymentStore {
+    private memory;
+    private config;
+    private dirty;
+    constructor(config: JsonDeferredStoreConfig);
+    /**
+     * Load data from file
+     */
+    load(): void;
+    /**
+     * Save data to file
+     */
+    save(): void;
+    /**
+     * Mark as dirty and optionally auto-save
+     */
+    private markDirty;
+    /**
+     * Check if there are unsaved changes
+     */
+    isDirty(): boolean;
+    createAccount(params: CreateCreditAccountParams): Promise<CreditAccount>;
+    getAccount(accountId: string): Promise<CreditAccount | null>;
+    getAccountByBuyer(buyerId: string, sellerId: string): Promise<CreditAccount | null>;
+    updateAccount(accountId: string, updates: Partial<CreditAccount>): Promise<CreditAccount>;
+    listAccounts(sellerId: string): Promise<CreditAccount[]>;
+    createPayment(params: CreateDeferredPaymentParams): Promise<DeferredPayment>;
+    getPayment(paymentId: string): Promise<DeferredPayment | null>;
+    updatePayment(paymentId: string, updates: Partial<DeferredPayment>): Promise<DeferredPayment>;
+    listPayments(filter: PaymentFilter): Promise<DeferredPayment[]>;
+    addTransaction(accountId: string, tx: Omit<CreditTransaction, 'txId' | 'timestamp'>): Promise<CreditTransaction>;
+    /**
+     * Export all data
+     */
+    export(): {
+        accounts: CreditAccount[];
+        payments: DeferredPayment[];
+    };
+    /**
+     * Clear all data (including file)
+     */
+    clear(): void;
+}
+
+/**
+ * Deferred Payment Conversation Templates
+ *
+ * Natural language templates for Agent-to-Agent deferred payment flows.
+ */
+
+declare const DeferredStatusMarkers: {
+    creditAccountCreated: (accountId: string, limit: number) => string;
+    chargeAdded: (paymentId: string, amount: number) => string;
+    settlementReceived: (paymentId: string, txHash: string, amount: number) => string;
+    accountSettled: (accountId: string, txHash: string, amount: number) => string;
+    creditIssued: (accountId: string, amount: number) => string;
+    accountSuspended: (accountId: string, reason: string) => string;
+    paymentOverdue: (paymentId: string, amount: number) => string;
+};
+declare const DeferredSellerTemplates: {
+    /**
+     * Offer deferred payment option
+     */
+    offerDeferredPayment: (params: {
+        service: string;
+        price: number;
+        netDays?: number;
+    }) => string;
+    /**
+     * Explain credit account setup
+     */
+    explainCreditAccount: () => string;
+    /**
+     * Confirm credit account creation
+     */
+    creditAccountCreated: (account: CreditAccount) => string;
+    /**
+     * Charge confirmation
+     */
+    chargeConfirmation: (payment: DeferredPayment, availableCredit: number) => string;
+    /**
+     * Credit limit exceeded
+     */
+    creditLimitExceeded: (params: {
+        requested: number;
+        available: number;
+        balance: number;
+        limit: number;
+    }) => string;
+    /**
+     * Account summary/statement
+     */
+    accountStatement: (summary: AccountSummary) => string;
+    /**
+     * Settlement confirmation
+     */
+    settlementConfirmation: (params: {
+        amount: number;
+        txHash: string;
+        newBalance: number;
+        paymentId?: string;
+    }) => string;
+    /**
+     * Overdue notice
+     */
+    overdueNotice: (payments: DeferredPayment[]) => string;
+    /**
+     * Credit issued confirmation
+     */
+    creditIssued: (params: {
+        amount: number;
+        reason: string;
+        newBalance: number;
+        accountId: string;
+    }) => string;
+};
+declare const DeferredBuyerTemplates: {
+    /**
+     * Request deferred payment
+     */
+    requestDeferredPayment: (service: string) => string;
+    /**
+     * Accept credit account offer
+     */
+    acceptCreditAccount: () => string;
+    /**
+     * Request credit limit increase
+     */
+    requestCreditIncrease: (currentLimit: number, requestedLimit: number) => string;
+    /**
+     * Request account statement
+     */
+    requestStatement: () => string;
+    /**
+     * Announce settlement payment
+     */
+    announceSettlement: (params: {
+        amount: number;
+        txHash: string;
+        accountId?: string;
+    }) => string;
+    /**
+     * Dispute a charge
+     */
+    disputeCharge: (paymentId: string, reason: string) => string;
+};
+interface ParsedDeferredStatus {
+    type: string;
+    data: Record<string, string>;
+}
+declare function parseDeferredStatusMarker(text: string): ParsedDeferredStatus | null;
+
+export { type AccountSummary, AgentWallet, AuditAction, AuditEntry, AuditLog, BuyerTemplates, type CDPInitResult, CDPWallet, type CDPWalletConfig, type CDPWalletData, ChainConfig, ChainName, type ChargeResult, type CreateCreditAccountParams, type CreateDeferredPaymentParams, CreateInvoiceParams, type CreditAccount, type CreditAccountStatus, type CreditTransaction, type CreditTransactionType, DeferredBuyerTemplates, type DeferredPayment, DeferredPaymentManager, type DeferredPaymentManagerConfig, type DeferredPaymentStatus, type DeferredPaymentStore, DeferredSellerTemplates, DeferredStatusMarkers, type EIP3009Authorization, type Installment, Invoice, JsonDeferredStore, type JsonDeferredStoreConfig, MemoryDeferredStore, PAYMENT_HEADER, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, type ParsedDeferredStatus, PaymentAgent, PaymentAgentConfig, type PaymentFilter, type PaymentPlan, type PaymentTerms, type Receipt, type ReceiptParams, type RecordSettlementParams, SellerTemplates, type Settlement, type SettlementFrequency, type SettlementResult, StatusMarkers, VerifyOptions, VerifyResult, WalletBalance, type X402Client, type X402ClientConfig, type X402PaymentPayload, type X402PaymentRequirements, X402_VERSION, chainToNetwork, createExactEvmPayload, createPaymentRequiredResponse, createX402Client, encodePaymentPayload, formatReceiptJson, formatReceiptMessage, formatReceiptText, generateReceipt, generateReceiptFromInvoice, getAgentAddress, getCDPWalletAddress, getChain, initCDPWallet, isCDPAvailable, isX402Available, loadCDPWallet, networkToChain, parseDeferredStatusMarker, parsePaymentRequired, parseStatusMarker, signEIP3009, verifyPaymentHeader, wrapFetchWith402, x402Fetch };