@anuragchvn-blip/mandatekit
Version:
Production-ready Web3 autopay SDK for crypto-based recurring payments using EIP-712 mandates
193 lines • 6.08 kB
TypeScript
/**
* Cadence enforcement utilities for MandateKit SDK
* Handles payment scheduling, interval calculation, and execution validation
* @module utils/cadence
*/
import type { Cadence } from '../types/index.js';
/**
* Seconds in common time intervals (for calculations)
*/
export declare const TIME_CONSTANTS: {
readonly SECOND: 1;
readonly MINUTE: 60;
readonly HOUR: 3600;
readonly DAY: 86400;
readonly WEEK: 604800;
readonly MONTH: 2592000;
readonly YEAR: 31536000;
};
/**
* Converts a cadence configuration to seconds
*
* @param cadence - Cadence configuration
* @returns Number of seconds between payments
*
* @example
* ```typescript
* const seconds = cadenceToSeconds({ interval: 'weekly', count: 2 });
* // Returns: 1209600 (2 weeks in seconds)
* ```
*/
export declare function cadenceToSeconds(cadence: Cadence): number;
/**
* Calculates the next execution timestamp based on last execution and cadence
*
* @param lastExecutionTime - Unix timestamp of last payment
* @param cadence - Cadence configuration
* @returns Unix timestamp of next allowed execution
*
* @example
* ```typescript
* const lastExecution = 1704067200; // Jan 1, 2024
* const next = calculateNextExecution(lastExecution, {
* interval: 'monthly',
* count: 1
* });
* // Returns: ~1706745600 (Feb 1, 2024)
* ```
*/
export declare function calculateNextExecution(lastExecutionTime: number, cadence: Cadence): number;
/**
* Checks if a payment is due based on last execution and cadence
*
* @param lastExecutionTime - Unix timestamp of last payment
* @param cadence - Cadence configuration
* @param currentTime - Current unix timestamp (defaults to now)
* @returns True if payment is due
*
* @example
* ```typescript
* const isDue = isPaymentDue(
* lastExecutionTimestamp,
* { interval: 'daily', count: 1 },
* Date.now() / 1000
* );
* ```
*/
export declare function isPaymentDue(lastExecutionTime: number, cadence: Cadence, currentTime?: number): boolean;
/**
* Validates that a payment can be executed now
* Throws descriptive errors if execution is not allowed
*
* @param lastExecutionTime - Unix timestamp of last payment
* @param cadence - Cadence configuration
* @param currentTime - Current unix timestamp (defaults to now)
* @throws {ExecutionTooEarlyError} If trying to execute before next scheduled time
*
* @example
* ```typescript
* try {
* validateExecutionTiming(lastExecution, cadence);
* // Safe to execute
* } catch (error) {
* if (error instanceof ExecutionTooEarlyError) {
* console.log('Next execution at:', error.details.nextExecutionTime);
* }
* }
* ```
*/
export declare function validateExecutionTiming(lastExecutionTime: number, cadence: Cadence, currentTime?: number): void;
/**
* Calculates time remaining until next execution
*
* @param lastExecutionTime - Unix timestamp of last payment
* @param cadence - Cadence configuration
* @param currentTime - Current unix timestamp (defaults to now)
* @returns Seconds until next execution (0 if already due)
*
* @example
* ```typescript
* const secondsRemaining = getTimeUntilNextExecution(
* lastExecution,
* { interval: 'weekly', count: 1 }
* );
* console.log(`Next payment in ${secondsRemaining} seconds`);
* ```
*/
export declare function getTimeUntilNextExecution(lastExecutionTime: number, cadence: Cadence, currentTime?: number): number;
/**
* Validates cadence configuration
*
* @param cadence - Cadence to validate
* @throws {ValidationError} If cadence is invalid
*
* @example
* ```typescript
* validateCadence({ interval: 'monthly', count: 1 }); // OK
* validateCadence({ interval: 'daily', count: 0 }); // Throws ValidationError
* ```
*/
export declare function validateCadence(cadence: Cadence): void;
/**
* Generates a human-readable description of a cadence
*
* @param cadence - Cadence configuration
* @returns Human-friendly description string
*
* @example
* ```typescript
* describeCadence({ interval: 'monthly', count: 1 });
* // Returns: "Every month"
*
* describeCadence({ interval: 'weekly', count: 2 });
* // Returns: "Every 2 weeks"
* ```
*/
export declare function describeCadence(cadence: Cadence): string;
/**
* Calculates all scheduled execution times between two dates
* Useful for generating payment calendars
*
* @param startTime - First execution timestamp
* @param endTime - End timestamp
* @param cadence - Cadence configuration
* @returns Array of scheduled execution timestamps
*
* @example
* ```typescript
* const schedule = generateExecutionSchedule(
* startTime,
* endTime,
* { interval: 'weekly', count: 1 }
* );
* // Returns: [timestamp1, timestamp2, timestamp3, ...]
* ```
*/
export declare function generateExecutionSchedule(startTime: number, endTime: number, cadence: Cadence): number[];
/**
* Calculates execution count based on elapsed time
* Useful for estimating how many payments should have occurred
*
* @param firstExecutionTime - Timestamp of first payment
* @param currentTime - Current timestamp
* @param cadence - Cadence configuration
* @returns Number of payments that should have been executed
*
* @example
* ```typescript
* const expectedCount = calculateExpectedExecutionCount(
* startTime,
* Date.now() / 1000,
* { interval: 'monthly', count: 1 }
* );
* ```
*/
export declare function calculateExpectedExecutionCount(firstExecutionTime: number, currentTime: number, cadence: Cadence): number;
/**
* Checks if a cadence represents a reasonable payment frequency
* Returns warnings for unusual configurations
*
* @param cadence - Cadence to check
* @returns Validation result with warnings
*
* @example
* ```typescript
* const result = checkCadenceReasonableness({ interval: 'daily', count: 365 });
* // result.warnings: ["Cadence exceeds 1 year, consider using yearly interval"]
* ```
*/
export declare function checkCadenceReasonableness(cadence: Cadence): {
isReasonable: boolean;
warnings: string[];
};
//# sourceMappingURL=cadence.d.ts.map