/**
 * Core interfaces and types for monie-utils
 */
/**
 * Represents a money amount with its currency
 */
interface Money {
    /** The amount in the currency's base unit */
    amount: number;
    /** ISO 4217 currency code */
    currency: string;
}
/**
 * Exchange rate information between two currencies
 */
interface ExchangeRate {
    /** Source currency code */
    from: string;
    /** Target currency code */
    to: string;
    /** Exchange rate value */
    rate: number;
    /** Timestamp when rate was fetched */
    timestamp: Date;
}
/**
 * Transaction information
 */
interface Transaction {
    /** Unique transaction identifier */
    id: string;
    /** Transaction amount */
    amount: Money;
    /** Transaction date */
    date: Date;
    /** Transaction description */
    description: string;
    /** Optional category */
    category?: string;
    /** Transaction type */
    type: 'credit' | 'debit';
}
/**
 * Currency information and metadata
 */
interface CurrencyInfo {
    /** ISO 4217 currency code */
    code: string;
    /** Full currency name */
    name: string;
    /** Currency symbol */
    symbol: string;
    /** Number of decimal places */
    decimalPlaces: number;
    /** Countries that use this currency */
    countries: string[];
    /** Whether this is a cryptocurrency */
    isCrypto: boolean;
}
/**
 * Formatting options for money display
 */
interface FormatOptions {
    /** Locale for formatting */
    locale?: string;
    /** Whether to show currency symbol */
    showSymbol?: boolean;
    /** Whether to show currency code */
    showCode?: boolean;
    /** Custom decimal places (overrides currency default) */
    decimalPlaces?: number;
    /** Whether to use compact notation (1M, 1B, etc.) */
    compact?: boolean;
}
/**
 * Fee structure for transaction calculations
 */
interface FeeStructure {
    /** Fixed fee amount */
    fixed?: number;
    /** Percentage fee rate */
    percentage?: number;
    /** Minimum fee */
    minimum?: number;
    /** Maximum fee */
    maximum?: number;
}
/**
 * Loan calculation parameters
 */
interface LoanParameters {
    /** Principal loan amount */
    principal: number;
    /** Annual interest rate (as decimal, e.g., 0.05 for 5%) */
    rate: number;
    /** Loan term in months */
    termMonths: number;
}
/**
 * Investment return data
 */
interface InvestmentReturn {
    /** Period identifier */
    period: string;
    /** Return value for the period */
    value: number;
    /** Date of the return */
    date: Date;
}
/**
 * Budget allocation item
 */
interface BudgetCategory {
    /** Category name */
    name: string;
    /** Allocated amount */
    amount: number;
    /** Allocation percentage */
    percentage: number;
}
/**
 * Subscription plan information
 */
interface SubscriptionPlan$1 {
    /** Plan name */
    name: string;
    /** Monthly cost */
    monthlyAmount: number;
    /** Annual cost (if different from 12x monthly) */
    annualAmount?: number;
    /** Billing frequency */
    frequency: 'monthly' | 'quarterly' | 'annually';
    /** Plan features */
    features: string[];
}
/**
 * Error types for validation and operations
 */
type MonieUtilsError$1 = 'INVALID_AMOUNT' | 'INVALID_CURRENCY' | 'CURRENCY_MISMATCH' | 'DIVISION_BY_ZERO' | 'INVALID_RANGE' | 'INVALID_PERCENTAGE' | 'INVALID_DATE' | 'EXCHANGE_RATE_NOT_FOUND';

/**
 * Custom error class for monie-utils
 */
declare class MonieUtilsError extends Error {
    readonly code: string;
    constructor(message: string);
}
/**
 * Create a standardized error
 */
declare function createError(message: string): MonieUtilsError;

/**
 * Type definitions for currency formatting utilities
 */
/**
 * Options for formatting currency amounts
 */
interface FormatCurrencyOptions {
    /** Locale for formatting (e.g., 'en-US', 'en-GB', 'de-DE') */
    locale?: string;
    /** Whether to show the currency symbol (default: true) */
    showSymbol?: boolean;
    /** Whether to show the currency code (default: false) */
    showCode?: boolean;
    /** Custom decimal places (overrides currency default) */
    decimalPlaces?: number;
    /** Whether to use compact notation for large numbers (1M, 1B, etc.) */
    compact?: boolean;
    /** Whether to use grouping separators (thousands separators) */
    useGrouping?: boolean;
    /** Custom currency symbol to override default */
    customSymbol?: string;
    /** Position of currency symbol ('start' | 'end') */
    symbolPosition?: 'start' | 'end';
}
/**
 * Result of currency formatting operation
 */
interface FormattedCurrency {
    /** The formatted string representation */
    formatted: string;
    /** The original amount */
    amount: number;
    /** The currency code used */
    currency: string;
    /** The locale used for formatting */
    locale: string;
    /** Whether compact notation was used */
    isCompact: boolean;
}
/**
 * Currency display information
 */
interface CurrencyDisplay {
    /** Currency code (e.g., 'USD', 'EUR') */
    code: string;
    /** Currency symbol (e.g., '$', '€') */
    symbol: string;
    /** Currency name (e.g., 'US Dollar', 'Euro') */
    name: string;
    /** Number of decimal places for this currency */
    decimalPlaces: number;
    /** Whether this currency uses grouping separators */
    usesGrouping: boolean;
}

/**
 * Currency formatting utilities
 */

/**
 * Formats a currency amount with locale-specific formatting
 *
 * @param amount - The amount to format
 * @param currency - The currency code (e.g., 'USD', 'EUR')
 * @param options - Formatting options
 * @returns Formatted currency object
 *
 * @throws {MonieUtilsError} When amount is invalid or currency is not supported
 *
 * @example
 * ```typescript
 * // Basic usage
 * formatCurrency(1234.56, 'USD')
 * // Returns: { formatted: '$1,234.56', amount: 1234.56, currency: 'USD', locale: 'en-US', isCompact: false }
 *
 * // With options
 * formatCurrency(1234.56, 'EUR', { locale: 'de-DE', showCode: true })
 * // Returns: { formatted: '1.234,56 EUR', amount: 1234.56, currency: 'EUR', locale: 'de-DE', isCompact: false }
 *
 * // Compact notation
 * formatCurrency(1500000, 'USD', { compact: true })
 * // Returns: { formatted: '$1.5M', amount: 1500000, currency: 'USD', locale: 'en-US', isCompact: true }
 * ```
 */
declare function formatCurrency(amount: number, currency: string, options?: FormatCurrencyOptions): FormattedCurrency;
/**
 * Simple currency formatter that returns just the formatted string
 *
 * @param amount - The amount to format
 * @param currency - The currency code
 * @param locale - Optional locale (defaults to 'en-US')
 * @returns Formatted currency string
 *
 * @example
 * ```typescript
 * formatMoney(1234.56, 'USD') // "$1,234.56"
 * formatMoney(1234.56, 'EUR', 'de-DE') // "1.234,56 €"
 * ```
 */
declare function formatMoney(amount: number, currency: string, locale?: string): string;
/**
 * Formats cents (smallest currency unit) to the main currency unit
 *
 * @param cents - Amount in cents (or smallest unit)
 * @param currency - The currency code
 * @param options - Formatting options
 * @returns Formatted currency object
 *
 * @example
 * ```typescript
 * formatCents(12345, 'USD') // Formats 123.45 USD
 * formatCents(100, 'JPY') // Formats 100 JPY (no conversion for JPY)
 * ```
 */
declare function formatCents(cents: number, currency: string, options?: FormatCurrencyOptions): FormattedCurrency;
/**
 * Formats a currency amount in compact notation for large numbers
 *
 * @param amount - The amount to format
 * @param currency - The currency code
 * @param options - Formatting options
 * @returns Formatted currency object with compact notation
 *
 * @example
 * ```typescript
 * formatCompactCurrency(1500000, 'USD') // "$1.5M"
 * formatCompactCurrency(2300000000, 'EUR') // "€2.3B"
 * ```
 */
declare function formatCompactCurrency(amount: number, currency: string, options?: FormatCurrencyOptions): FormattedCurrency;

/**
 * Constants used in currency formatting operations
 */

/**
 * Default formatting options
 */
declare const DEFAULT_FORMAT_OPTIONS: {
    readonly locale: "en-US";
    readonly showSymbol: true;
    readonly showCode: false;
    readonly useGrouping: true;
    readonly symbolPosition: "start";
};
/**
 * Currency information database
 * Contains symbols, decimal places, and other formatting info for major currencies
 */
declare const CURRENCY_INFO: Record<string, CurrencyDisplay>;
/**
 * Compact notation suffixes for large numbers
 */
declare const COMPACT_SUFFIXES: {
    readonly K: 1000;
    readonly M: 1000000;
    readonly B: 1000000000;
    readonly T: 1000000000000;
};
/**
 * Compact notation thresholds
 */
declare const COMPACT_THRESHOLDS: {
    readonly THOUSAND: 1000;
    readonly MILLION: 1000000;
    readonly BILLION: 1000000000;
    readonly TRILLION: 1000000000000;
};

/**
 * Type definitions for percentage formatting utilities
 */
/**
 * Options for formatting percentages
 */
interface FormatPercentageOptions {
    /** Number of decimal places to show (default: 2) */
    precision?: number;
    /** Locale for formatting (default: 'en-US') */
    locale?: string;
    /** Whether to use grouping separators (default: true) */
    useGrouping?: boolean;
    /** Custom suffix instead of % (optional) */
    suffix?: string;
    /** Whether to include a space before the suffix (default: false) */
    spaceBefore?: boolean;
}
/**
 * Result of percentage formatting
 */
interface FormattedPercentage {
    /** The formatted percentage string */
    formatted: string;
    /** The original decimal value */
    decimal: number;
    /** The percentage value (decimal * 100) */
    percentage: number;
    /** The precision used */
    precision: number;
    /** The locale used */
    locale: string;
}

/**
 * Percentage formatting utilities
 */

/**
 * Formats a decimal as a percentage with customizable options
 *
 * @param decimal - The decimal to format (e.g., 0.25 for 25%)
 * @param options - Formatting options
 * @returns Formatted percentage object
 *
 * @throws {MonieUtilsError} When decimal is invalid
 *
 * @example
 * ```typescript
 * // Basic usage
 * formatPercentage(0.25)
 * // Returns: { formatted: '25.00%', decimal: 0.25, percentage: 25, precision: 2, locale: 'en-US' }
 *
 * // With custom precision
 * formatPercentage(0.1234, { precision: 1 })
 * // Returns: { formatted: '12.3%', decimal: 0.1234, percentage: 12.3, precision: 1, locale: 'en-US' }
 *
 * // With custom locale
 * formatPercentage(0.1234, { locale: 'de-DE' })
 * // Returns: { formatted: '12,34 %', decimal: 0.1234, percentage: 12.34, precision: 2, locale: 'de-DE' }
 * ```
 */
declare function formatPercentage(decimal: number, options?: FormatPercentageOptions): FormattedPercentage;

/**
 * Default options and constants for percentage formatting
 */

/**
 * Default formatting options for percentages
 */
declare const DEFAULT_PERCENTAGE_OPTIONS: Required<Omit<FormatPercentageOptions, 'suffix'>>;

/**
 * Type definitions for localization utilities
 */
/**
 * Options for locale-based formatting
 */
interface LocaleFormatOptions {
    /** Whether to use grouping separators (default: true) */
    useGrouping?: boolean;
    /** Custom currency symbol */
    customSymbol?: string;
    /** Whether to show currency code instead of symbol */
    showCode?: boolean;
    /** Position of currency symbol */
    symbolPosition?: 'start' | 'end';
}
/**
 * Currency information for a specific locale
 */
interface LocaleCurrencyInfo {
    /** The currency code used in this locale */
    currency: string;
    /** The currency symbol */
    symbol: string;
    /** The currency name */
    name: string;
    /** Number of decimal places */
    decimalPlaces: number;
    /** The locale code */
    locale: string;
}
/**
 * Formatted number with grouping
 */
interface FormattedWithGrouping {
    /** The formatted number string */
    formatted: string;
    /** The original amount */
    amount: number;
    /** The locale used */
    locale: string;
    /** Whether grouping was applied */
    hasGrouping: boolean;
}
/**
 * Formatted decimal places result
 */
interface FormattedDecimalPlaces {
    /** The formatted number string */
    formatted: string;
    /** The original amount */
    amount: number;
    /** The decimal places used */
    decimalPlaces: number;
}

/**
 * Localization utilities for currency and number formatting
 */

/**
 * Formats currency using locale-specific conventions
 *
 * @param amount - The amount to format
 * @param currency - The currency code
 * @param locale - The locale for formatting
 * @param options - Additional formatting options
 * @returns Formatted currency string
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * formatCurrencyByLocale(1234.56, 'USD', 'en-US') // "$1,234.56"
 * formatCurrencyByLocale(1234.56, 'EUR', 'de-DE') // "1.234,56 €"
 * ```
 */
declare function formatCurrencyByLocale(amount: number, currency: string, locale: string, options?: LocaleFormatOptions): string;
/**
 * Gets currency information for a specific locale
 *
 * @param locale - The locale to get currency info for
 * @returns Currency information object
 *
 * @throws {MonieUtilsError} When locale is invalid or not supported
 *
 * @example
 * ```typescript
 * getLocaleCurrencyInfo('en-US')
 * // Returns: { currency: 'USD', symbol: '$', name: 'US Dollar', decimalPlaces: 2, locale: 'en-US' }
 * ```
 */
declare function getLocaleCurrencyInfo(locale: string): LocaleCurrencyInfo;
/**
 * Formats a number with locale-specific grouping separators
 *
 * @param amount - The amount to format
 * @param locale - The locale for formatting (defaults to 'en-US')
 * @returns Formatted number with grouping information
 *
 * @throws {MonieUtilsError} When amount is invalid or locale is unsupported
 *
 * @example
 * ```typescript
 * formatWithGrouping(1234567.89) // "1,234,567.89"
 * formatWithGrouping(1234567.89, 'de-DE') // "1.234.567,89"
 * ```
 */
declare function formatWithGrouping(amount: number, locale?: string): FormattedWithGrouping;
/**
 * Formats a number with specific decimal places
 *
 * @param amount - The amount to format
 * @param decimalPlaces - Number of decimal places to show
 * @returns Formatted number with specified decimal places
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * formatDecimalPlaces(123.456789, 2) // "123.46"
 * formatDecimalPlaces(123, 4) // "123.0000"
 * ```
 */
declare function formatDecimalPlaces(amount: number, decimalPlaces: number): FormattedDecimalPlaces;

/**
 * Constants and mappings for localization utilities
 */

/**
 * Mapping of locales to their primary currencies
 */
declare const LOCALE_CURRENCY_MAP: Record<string, LocaleCurrencyInfo>;

/**
 * Type definitions for validation and parsing utilities
 */
/**
 * Result of parsing an amount string
 */
interface ParsedAmount {
    /** The parsed numeric value */
    amount: number;
    /** Whether the original string was valid */
    isValid: boolean;
    /** The original string that was parsed */
    originalString: string;
}
/**
 * Result of parsing a currency string
 */
interface ParsedCurrency {
    /** The extracted amount */
    amount: number;
    /** The extracted currency code */
    currency: string;
    /** Whether the parsing was successful */
    isValid: boolean;
    /** The original string that was parsed */
    originalString: string;
}
/**
 * Options for normalizing amounts
 */
interface NormalizeOptions {
    /** Number of decimal places to round to */
    decimalPlaces?: number;
    /** Whether to round or truncate */
    roundingMode?: 'round' | 'floor' | 'ceil';
}
/**
 * Range validation options
 */
interface RangeOptions {
    /** Whether min/max are inclusive (default: true) */
    inclusive?: boolean;
}

/**
 * Validation and parsing utilities
 */

/**
 * Checks if an amount is a valid money value
 *
 * @param amount - The value to validate
 * @returns True if the amount is valid for money operations
 *
 * @example
 * ```typescript
 * isValidAmount(123.45) // true
 * isValidAmount(NaN) // false
 * isValidAmount(Infinity) // false
 * ```
 */
declare function isValidAmount(amount: unknown): amount is number;
/**
 * Validates if a currency code is supported (ISO 4217)
 *
 * @param currencyCode - The currency code to validate
 * @returns True if the currency is supported
 *
 * @example
 * ```typescript
 * isValidCurrency('USD') // true
 * isValidCurrency('INVALID') // false
 * ```
 */
declare function isValidCurrency(currencyCode: unknown): currencyCode is string;
/**
 * Validates a money object structure
 *
 * @param moneyObject - The object to validate
 * @returns True if the object is a valid Money structure
 *
 * @example
 * ```typescript
 * validateMoneyObject({ amount: 100, currency: 'USD' }) // true
 * validateMoneyObject({ amount: 'invalid', currency: 'USD' }) // false
 * ```
 */
declare function validateMoneyObject(moneyObject: unknown): moneyObject is Money;
/**
 * Checks if an amount is positive
 *
 * @param amount - The amount to check
 * @returns True if amount is positive
 *
 * @example
 * ```typescript
 * isPositiveAmount(100) // true
 * isPositiveAmount(-50) // false
 * isPositiveAmount(0) // false
 * ```
 */
declare function isPositiveAmount(amount: number): boolean;
/**
 * Checks if an amount is within a specified range
 *
 * @param amount - The amount to check
 * @param min - Minimum value
 * @param max - Maximum value
 * @param options - Range validation options
 * @returns True if amount is within range
 *
 * @example
 * ```typescript
 * isWithinRange(50, 0, 100) // true
 * isWithinRange(150, 0, 100) // false
 * ```
 */
declare function isWithinRange(amount: number, min: number, max: number, options?: RangeOptions): boolean;
/**
 * Parses a string to extract a numeric amount
 *
 * @param amountString - The string to parse
 * @returns Parsed amount result
 *
 * @example
 * ```typescript
 * parseAmount('123.45') // { amount: 123.45, isValid: true, originalString: '123.45' }
 * parseAmount('$1,234.56') // { amount: 1234.56, isValid: true, originalString: '$1,234.56' }
 * ```
 */
declare function parseAmount(amountString: string): ParsedAmount;
/**
 * Extracts amount and currency from a formatted string
 *
 * @param currencyString - The string to parse
 * @returns Parsed currency result
 *
 * @example
 * ```typescript
 * parseCurrencyString('$123.45 USD') // { amount: 123.45, currency: 'USD', isValid: true, originalString: '$123.45 USD' }
 * parseCurrencyString('€1,234.56 EUR') // { amount: 1234.56, currency: 'EUR', isValid: true, originalString: '€1,234.56 EUR' }
 * ```
 */
declare function parseCurrencyString(currencyString: string): ParsedCurrency;
/**
 * Normalizes an amount to a standard format
 *
 * @param amount - The amount to normalize
 * @param options - Normalization options
 * @returns Normalized amount
 *
 * @throws {MonieUtilsError} When amount is invalid
 *
 * @example
 * ```typescript
 * normalizeAmount(123.456789) // 123.46 (default 2 decimal places)
 * normalizeAmount(123.456789, { decimalPlaces: 4 }) // 123.4568
 * ```
 */
declare function normalizeAmount(amount: number, options?: NormalizeOptions): number;
/**
 * Parses a formatted currency string based on locale
 *
 * @param formattedString - The formatted currency string
 * @param locale - The locale for parsing (defaults to 'en-US')
 * @returns Parsed amount
 *
 * @throws {MonieUtilsError} When parsing fails
 *
 * @example
 * ```typescript
 * parseFormattedCurrency('$1,234.56') // 1234.56
 * parseFormattedCurrency('1.234,56 €', 'de-DE') // 1234.56
 * ```
 */
declare function parseFormattedCurrency(formattedString: string, locale?: string): number;

/**
 * Currency conversion result
 */
interface ConversionResult {
    /** Original amount */
    originalAmount: number;
    /** Converted amount */
    convertedAmount: number;
    /** Source currency */
    fromCurrency: string;
    /** Target currency */
    toCurrency: string;
    /** Exchange rate used */
    exchangeRate: number;
    /** Timestamp of conversion */
    timestamp: Date;
}
/**
 * Conversion with fee result
 */
interface ConversionWithFeeResult extends ConversionResult {
    /** Fee amount deducted */
    feeAmount: number;
    /** Fee percentage applied */
    feePercentage: number;
    /** Amount after fee deduction */
    amountAfterFee: number;
}
/**
 * Bulk conversion result
 */
interface BulkConversionResult {
    /** Array of individual conversion results */
    conversions: ConversionResult[];
    /** Total original amount */
    totalOriginalAmount: number;
    /** Total converted amount */
    totalConvertedAmount: number;
    /** Exchange rate used */
    exchangeRate: number;
    /** Currencies involved */
    fromCurrency: string;
    toCurrency: string;
}

/**
 * Currency conversion utilities
 */

/**
 * Converts currency amount between two currencies
 *
 * @param amount - Amount to convert
 * @param fromCurrency - Source currency code
 * @param toCurrency - Target currency code
 * @param rate - Optional custom exchange rate
 * @returns Conversion result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * convertCurrency(100, 'USD', 'EUR') // Uses default rate
 * convertCurrency(100, 'USD', 'EUR', 0.85) // Uses custom rate
 * ```
 */
declare function convertCurrency(amount: number, fromCurrency: string, toCurrency: string, rate?: number): ConversionResult;
/**
 * Converts currency with transaction fee
 *
 * @param amount - Amount to convert
 * @param rate - Exchange rate
 * @param feePercentage - Fee percentage (e.g., 2.5 for 2.5%)
 * @returns Conversion result with fee information
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * convertWithFee(100, 0.85, 2.5) // 2.5% fee
 * ```
 */
declare function convertWithFee(amount: number, rate: number, feePercentage: number): ConversionWithFeeResult;
/**
 * Converts multiple amounts using the same exchange rate
 *
 * @param amounts - Array of amounts to convert
 * @param fromCurrency - Source currency code
 * @param toCurrency - Target currency code
 * @param rate - Optional custom exchange rate
 * @returns Bulk conversion result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * bulkConvert([100, 200, 300], 'USD', 'EUR')
 * ```
 */
declare function bulkConvert(amounts: number[], fromCurrency: string, toCurrency: string, rate?: number): BulkConversionResult;

/**
 * Type definitions for arithmetic operations utilities
 */
/**
 * Rounding modes for financial calculations
 */
type RoundingMode = 'round' | 'floor' | 'ceil' | 'bankers';
/**
 * Result of money arithmetic operations
 */
interface ArithmeticResult {
    /** The calculated amount */
    amount: number;
    /** The currency code */
    currency?: string;
    /** The operation performed */
    operation: string;
    /** Original operands */
    operands: number[];
}
/**
 * Split amount result
 */
interface SplitResult {
    /** Array of split amounts */
    amounts: number[];
    /** Total amount that was split */
    totalAmount: number;
    /** Number of parts */
    numberOfParts: number;
    /** Any remainder from splitting */
    remainder: number;
}
/**
 * Proportional distribution result
 */
interface DistributionResult {
    /** Array of distributed amounts */
    amounts: number[];
    /** Total amount that was distributed */
    totalAmount: number;
    /** Ratios used for distribution */
    ratios: number[];
    /** Any remainder from distribution */
    remainder: number;
}
/**
 * Interest calculation result
 */
interface InterestResult {
    /** Principal amount */
    principal: number;
    /** Interest rate used */
    rate: number;
    /** Time period */
    time: number;
    /** Calculated interest */
    interest: number;
    /** Final amount (principal + interest) */
    finalAmount: number;
    /** Type of interest calculation */
    type: 'simple' | 'compound';
    /** Compounding frequency (for compound interest) */
    frequency?: number;
}
/**
 * Percentage calculation result
 */
interface PercentageResult {
    /** The percentage value */
    percentage: number;
    /** The amount used */
    amount: number;
    /** The total used */
    total: number;
}

/**
 * Arithmetic operations utilities
 */

/**
 * Rounds a money amount using the specified rounding mode
 *
 * @param amount - The amount to round
 * @param precision - Number of decimal places (default: 2)
 * @param mode - Rounding mode (default: 'round')
 * @returns Rounded amount
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * roundMoney(123.456) // 123.46
 * roundMoney(123.456, 1) // 123.5
 * roundMoney(123.456, 2, 'floor') // 123.45
 * ```
 */
declare function roundMoney(amount: number, precision?: number, mode?: RoundingMode): number;
/**
 * Adds two money amounts
 *
 * @param amount1 - First amount
 * @param amount2 - Second amount
 * @param currency - Optional currency code for validation
 * @returns Addition result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * addMoney(100.50, 25.25) // 125.75
 * addMoney(100.50, 25.25, 'USD') // 125.75 with currency validation
 * ```
 */
declare function addMoney(amount1: number, amount2: number, currency?: string): number;
/**
 * Subtracts two money amounts
 *
 * @param amount1 - Amount to subtract from
 * @param amount2 - Amount to subtract
 * @param currency - Optional currency code for validation
 * @returns Subtraction result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * subtractMoney(100.75, 25.25) // 75.50
 * ```
 */
declare function subtractMoney(amount1: number, amount2: number, currency?: string): number;
/**
 * Multiplies money amount by a number
 *
 * @param amount - The amount to multiply
 * @param multiplier - The multiplier
 * @returns Multiplication result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * multiplyMoney(100.50, 2.5) // 251.25
 * ```
 */
declare function multiplyMoney(amount: number, multiplier: number): number;
/**
 * Divides money amount by a number
 *
 * @param amount - The amount to divide
 * @param divisor - The divisor
 * @returns Division result
 *
 * @throws {MonieUtilsError} When inputs are invalid or divisor is zero
 *
 * @example
 * ```typescript
 * divideMoney(100.50, 2) // 50.25
 * ```
 */
declare function divideMoney(amount: number, divisor: number): number;
/**
 * Calculates tip amount
 *
 * @param amount - The bill amount
 * @param percentage - Tip percentage (e.g., 15 for 15%)
 * @returns Tip amount
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateTip(100, 15) // 15.00
 * calculateTip(50.75, 20) // 10.15
 * ```
 */
declare function calculateTip(amount: number, percentage: number): number;
/**
 * Calculates tax amount
 *
 * @param amount - The amount to calculate tax on
 * @param taxRate - Tax rate (e.g., 8.5 for 8.5%)
 * @returns Tax amount
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateTax(100, 8.5) // 8.50
 * ```
 */
declare function calculateTax(amount: number, taxRate: number): number;
/**
 * Calculates discount amount
 *
 * @param amount - The original amount
 * @param discountRate - Discount rate (e.g., 10 for 10% off)
 * @returns Discount amount
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateDiscount(100, 10) // 10.00 (discount amount)
 * ```
 */
declare function calculateDiscount(amount: number, discountRate: number): number;
/**
 * Calculates simple interest
 *
 * @param principal - Principal amount
 * @param rate - Annual interest rate (e.g., 5 for 5%)
 * @param time - Time in years
 * @returns Interest calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateSimpleInterest(1000, 5, 2) // Interest: 100, Final: 1100
 * ```
 */
declare function calculateSimpleInterest(principal: number, rate: number, time: number): InterestResult;
/**
 * Calculates compound interest
 *
 * @param principal - Principal amount
 * @param rate - Annual interest rate (e.g., 5 for 5%)
 * @param time - Time in years
 * @param frequency - Compounding frequency per year (default: 1)
 * @returns Interest calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateCompoundInterest(1000, 5, 2) // Annual compounding
 * calculateCompoundInterest(1000, 5, 2, 12) // Monthly compounding
 * ```
 */
declare function calculateCompoundInterest(principal: number, rate: number, time: number, frequency?: number): InterestResult;
/**
 * Splits an amount into equal parts
 *
 * @param totalAmount - Total amount to split
 * @param numberOfParts - Number of parts to split into
 * @returns Split result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * splitAmount(100, 3) // [33.33, 33.33, 33.34] (last part gets remainder)
 * ```
 */
declare function splitAmount(totalAmount: number, numberOfParts: number): SplitResult;
/**
 * Distributes an amount proportionally based on ratios
 *
 * @param totalAmount - Total amount to distribute
 * @param ratios - Array of ratios for distribution
 * @returns Distribution result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * distributeProportionally(100, [1, 2, 1]) // [25, 50, 25]
 * distributeProportionally(100, [30, 70]) // [30, 70]
 * ```
 */
declare function distributeProportionally(totalAmount: number, ratios: number[]): DistributionResult;
/**
 * Calculates what percentage one amount is of a total
 *
 * @param amount - The amount to calculate percentage for
 * @param total - The total amount
 * @returns Percentage result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculatePercentageOfTotal(25, 100) // 25%
 * calculatePercentageOfTotal(33.33, 100) // 33.33%
 * ```
 */
declare function calculatePercentageOfTotal(amount: number, total: number): PercentageResult;

/**
 * Type definitions for loan and credit utilities
 */
/**
 * Loan payment calculation result
 */
interface LoanPaymentResult {
    /** Monthly payment amount */
    monthlyPayment: number;
    /** Principal amount */
    principal: number;
    /** Annual interest rate */
    rate: number;
    /** Term in months */
    termMonths: number;
    /** Total amount to be paid */
    totalAmount: number;
    /** Total interest to be paid */
    totalInterest: number;
}
/**
 * Loan balance calculation result
 */
interface LoanBalanceResult {
    /** Remaining balance */
    remainingBalance: number;
    /** Principal paid so far */
    principalPaid: number;
    /** Interest paid so far */
    interestPaid: number;
    /** Number of payments made */
    paymentsMade: number;
    /** Number of payments remaining */
    paymentsRemaining: number;
}
/**
 * Single amortization payment entry
 */
interface AmortizationPayment {
    /** Payment number */
    paymentNumber: number;
    /** Payment amount */
    paymentAmount: number;
    /** Principal portion of payment */
    principalAmount: number;
    /** Interest portion of payment */
    interestAmount: number;
    /** Remaining balance after payment */
    remainingBalance: number;
}
/**
 * Amortization schedule result
 */
interface AmortizationSchedule {
    /** Array of payment details */
    payments: AmortizationPayment[];
    /** Loan summary */
    summary: LoanPaymentResult;
}
/**
 * Credit utilization result
 */
interface CreditUtilizationResult {
    /** Utilization percentage */
    utilizationPercentage: number;
    /** Used credit amount */
    usedCredit: number;
    /** Total credit limit */
    totalCredit: number;
    /** Available credit */
    availableCredit: number;
    /** Risk level based on utilization */
    riskLevel: 'low' | 'medium' | 'high';
}
/**
 * Minimum payment calculation result
 */
interface MinimumPaymentResult {
    /** Minimum payment amount */
    minimumPayment: number;
    /** Current balance */
    balance: number;
    /** Interest rate */
    interestRate: number;
    /** Minimum payment rate */
    minimumRate: number;
    /** Interest portion */
    interestPortion: number;
    /** Principal portion */
    principalPortion: number;
}
/**
 * Payoff time calculation result
 */
interface PayoffTimeResult {
    /** Time to pay off in months */
    monthsToPayoff: number;
    /** Time to pay off in years */
    yearsToPayoff: number;
    /** Total interest paid */
    totalInterestPaid: number;
    /** Total amount paid */
    totalAmountPaid: number;
    /** Monthly payment amount */
    monthlyPayment: number;
}

/**
 * Loan and credit utilities
 */

/**
 * Calculates monthly payment for a loan
 *
 * @param principal - Loan principal amount
 * @param rate - Annual interest rate (e.g., 5 for 5%)
 * @param termMonths - Loan term in months
 * @returns Loan payment calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateMonthlyPayment(100000, 5, 360) // 30-year mortgage
 * // Returns: { monthlyPayment: 536.82, totalAmount: 193253.50, ... }
 * ```
 */
declare function calculateMonthlyPayment(principal: number, rate: number, termMonths: number): LoanPaymentResult;
/**
 * Calculates remaining loan balance after payments
 *
 * @param principal - Original loan principal
 * @param rate - Annual interest rate (e.g., 5 for 5%)
 * @param termMonths - Original loan term in months
 * @param paymentsMade - Number of payments made
 * @returns Loan balance calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateLoanBalance(100000, 5, 360, 120) // After 10 years of payments
 * ```
 */
declare function calculateLoanBalance(principal: number, rate: number, termMonths: number, paymentsMade: number): LoanBalanceResult;
/**
 * Calculates total interest for a loan
 *
 * @param principal - Loan principal amount
 * @param rate - Annual interest rate (e.g., 5 for 5%)
 * @param termMonths - Loan term in months
 * @returns Total interest amount
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateTotalInterest(100000, 5, 360) // Total interest over 30 years
 * ```
 */
declare function calculateTotalInterest(principal: number, rate: number, termMonths: number): number;
/**
 * Generates complete amortization schedule
 *
 * @param principal - Loan principal amount
 * @param rate - Annual interest rate (e.g., 5 for 5%)
 * @param termMonths - Loan term in months
 * @returns Complete amortization schedule
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * generateAmortizationSchedule(100000, 5, 360)
 * // Returns schedule with 360 payment entries
 * ```
 */
declare function generateAmortizationSchedule(principal: number, rate: number, termMonths: number): AmortizationSchedule;
/**
 * Calculates credit utilization ratio
 *
 * @param usedCredit - Amount of credit currently used
 * @param totalCredit - Total credit limit available
 * @returns Credit utilization result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateCreditUtilization(2500, 10000)
 * // Returns: { utilizationPercentage: 25, riskLevel: 'medium', ... }
 * ```
 */
declare function calculateCreditUtilization(usedCredit: number, totalCredit: number): CreditUtilizationResult;
/**
 * Calculates minimum credit card payment
 *
 * @param balance - Current credit card balance
 * @param rate - Annual interest rate (e.g., 18 for 18%)
 * @param minimumRate - Minimum payment rate (e.g., 2 for 2%)
 * @returns Minimum payment calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * calculateMinimumPayment(5000, 18, 2)
 * // Returns minimum payment details
 * ```
 */
declare function calculateMinimumPayment(balance: number, rate: number, minimumRate: number): MinimumPaymentResult;
/**
 * Calculates time to pay off debt with fixed payments
 *
 * @param balance - Current debt balance
 * @param payment - Monthly payment amount
 * @param rate - Annual interest rate (e.g., 18 for 18%)
 * @returns Payoff time calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid or payment is too low
 *
 * @example
 * ```typescript
 * calculatePayoffTime(5000, 200, 18)
 * // Returns: { monthsToPayoff: 30, yearsToPayoff: 2.5, ... }
 * ```
 */
declare function calculatePayoffTime(balance: number, payment: number, rate: number): PayoffTimeResult;

/**
 * @fileoverview Type definitions for investment and returns utilities
 * @module Investment/Types
 */
/**
 * Result of return on investment calculation
 */
interface ROIResult {
    /** The ROI as a decimal (e.g., 0.25 for 25% return) */
    roi: number;
    /** The ROI as a percentage (e.g., 25 for 25% return) */
    roiPercentage: number;
    /** The absolute gain or loss amount */
    gainLoss: number;
    /** Whether the investment resulted in a gain (true) or loss (false) */
    isGain: boolean;
}
/**
 * Result of annualized return calculation
 */
interface AnnualizedReturnResult {
    /** The annualized return as a decimal */
    annualizedReturn: number;
    /** The annualized return as a percentage */
    annualizedReturnPercentage: number;
    /** The total return over the entire period as a decimal */
    totalReturn: number;
    /** The total return over the entire period as a percentage */
    totalReturnPercentage: number;
}
/**
 * Result of dividend yield calculation
 */
interface DividendYieldResult {
    /** The dividend yield as a decimal */
    yield: number;
    /** The dividend yield as a percentage */
    yieldPercentage: number;
    /** The annual dividend income per share */
    dividendPerShare: number;
    /** The current share price */
    sharePrice: number;
}
/**
 * Result of future value calculation
 */
interface FutureValueResult {
    /** The future value of the investment */
    futureValue: number;
    /** The initial present value */
    presentValue: number;
    /** The total interest earned */
    totalInterest: number;
    /** The effective annual rate used */
    effectiveRate: number;
    /** The number of compounding periods */
    periods: number;
}

/**
 * @fileoverview Investment and returns calculation utilities
 * @module Investment
 */

/**
 * Calculate return on investment (ROI)
 *
 * @param initialInvestment - The initial investment amount
 * @param finalValue - The final value of the investment
 * @returns ROI calculation result with percentage and gain/loss information
 *
 * @throws {MonieUtilsError} When initial investment or final value is invalid
 * @throws {MonieUtilsError} When initial investment is zero or negative
 *
 * @example
 * ```typescript
 * const result = calculateROI(1000, 1250);
 * console.log(result.roiPercentage); // 25 (25% return)
 * console.log(result.gainLoss); // 250
 * console.log(result.isGain); // true
 * ```
 */
declare function calculateROI(initialInvestment: number, finalValue: number): ROIResult;
/**
 * Calculate annualized return on investment
 *
 * @param initialValue - The initial investment value
 * @param finalValue - The final investment value
 * @param years - The number of years the investment was held
 * @returns Annualized return calculation with total return information
 *
 * @throws {MonieUtilsError} When any parameter is invalid
 * @throws {MonieUtilsError} When initial value is zero or negative
 * @throws {MonieUtilsError} When years is zero or negative
 *
 * @example
 * ```typescript
 * const result = calculateAnnualizedReturn(1000, 1500, 3);
 * console.log(result.annualizedReturnPercentage); // ~14.47 (14.47% per year)
 * console.log(result.totalReturnPercentage); // 50 (50% total return)
 * ```
 */
declare function calculateAnnualizedReturn(initialValue: number, finalValue: number, years: number): AnnualizedReturnResult;
/**
 * Calculate dividend yield
 *
 * @param dividendPerShare - The annual dividend payment per share
 * @param pricePerShare - The current price per share
 * @returns Dividend yield calculation with percentage information
 *
 * @throws {MonieUtilsError} When dividend per share or price per share is invalid
 * @throws {MonieUtilsError} When price per share is zero or negative
 * @throws {MonieUtilsError} When dividend per share is negative
 *
 * @example
 * ```typescript
 * const result = calculateDividendYield(2.50, 50);
 * console.log(result.yieldPercentage); // 5 (5% dividend yield)
 * console.log(result.dividendPerShare); // 2.50
 * ```
 */
declare function calculateDividendYield(dividendPerShare: number, pricePerShare: number): DividendYieldResult;
/**
 * Calculate future value of an investment with compound interest
 *
 * @param presentValue - The present value of the investment
 * @param rate - The interest rate per period (as decimal, e.g., 0.05 for 5%)
 * @param periods - The number of compounding periods
 * @returns Future value calculation with interest breakdown
 *
 * @throws {MonieUtilsError} When any parameter is invalid
 * @throws {MonieUtilsError} When present value is zero or negative
 * @throws {MonieUtilsError} When rate is negative
 * @throws {MonieUtilsError} When periods is negative or not an integer
 *
 * @example
 * ```typescript
 * const result = calculateFutureValue(1000, 0.05, 10);
 * console.log(result.futureValue); // ~1628.89
 * console.log(result.totalInterest); // ~628.89
 * ```
 */
declare function calculateFutureValue(presentValue: number, rate: number, periods: number): FutureValueResult;

/**
 * @fileoverview Type definitions for subscription and recurring payment utilities
 * @module Subscription/Types
 */
/**
 * Subscription plan structure
 */
interface SubscriptionPlan {
    /** Unique identifier for the plan */
    id: string;
    /** Display name of the plan */
    name: string;
    /** Monthly cost of the plan */
    monthlyAmount: number;
    /** Currency code (e.g., 'USD', 'EUR') */
    currency: string;
    /** Optional annual discount as decimal (e.g., 0.1 for 10% off) */
    annualDiscount?: number;
    /** Features included in this plan */
    features?: string[];
    /** Maximum number of users/seats allowed */
    maxUsers?: number;
}
/**
 * Result of subscription value calculation
 */
interface SubscriptionValueResult {
    /** Total cost for the specified period */
    totalCost: number;
    /** Monthly amount */
    monthlyAmount: number;
    /** Number of months */
    months: number;
    /** Currency code */
    currency: string;
    /** Average monthly cost (useful for prorated calculations) */
    averageMonthlyCost: number;
}
/**
 * Result of subscription plan comparison
 */
interface PlanComparisonResult {
    /** Array of plans with calculated costs and metrics */
    plans: PlanAnalysis[];
    /** Recommended plan based on cost-effectiveness */
    recommendedPlan: PlanAnalysis;
    /** Potential savings by choosing the recommended plan */
    maxSavings: number;
}
/**
 * Individual plan analysis in comparison
 */
interface PlanAnalysis {
    /** Original plan information */
    plan: SubscriptionPlan;
    /** Monthly cost (may include discounts) */
    effectiveMonthlyRate: number;
    /** Annual cost */
    annualCost: number;
    /** Cost per user (if applicable) */
    costPerUser?: number;
    /** Value score (0-100, higher is better) */
    valueScore: number;
}
/**
 * Result of proration calculation
 */
interface ProrationResult {
    /** Prorated amount based on usage */
    proratedAmount: number;
    /** Original full amount */
    fullAmount: number;
    /** Number of days used */
    daysUsed: number;
    /** Total days in the period */
    totalDays: number;
    /** Usage percentage */
    usagePercentage: number;
}
/**
 * Result of upgrade credit calculation
 */
interface UpgradeCreditResult {
    /** Credit amount to apply to new plan */
    creditAmount: number;
    /** Remaining value from old plan */
    oldPlanRemainingValue: number;
    /** Prorated cost of new plan for remaining period */
    newPlanProratedCost: number;
    /** Net amount due (positive) or credit (negative) */
    netAmountDue: number;
    /** Days remaining in the billing period */
    daysRemaining: number;
}
/**
 * Payment frequency types
 */
type PaymentFrequency = 'daily' | 'weekly' | 'bi-weekly' | 'monthly' | 'quarterly' | 'semi-annually' | 'annually';
/**
 * Result of annual equivalent calculation
 */
interface AnnualEquivalentResult {
    /** Annual equivalent amount */
    annualAmount: number;
    /** Original amount */
    originalAmount: number;
    /** Payment frequency */
    frequency: PaymentFrequency;
    /** Number of payments per year */
    paymentsPerYear: number;
}
/**
 * Result of recurring cost calculation
 */
interface RecurringCostResult {
    /** Total cost over the duration */
    totalCost: number;
    /** Number of payments */
    numberOfPayments: number;
    /** Payment amount per period */
    amountPerPeriod: number;
    /** Payment frequency */
    frequency: PaymentFrequency;
    /** Duration in the specified time unit */
    duration: number;
    /** Time unit for duration */
    durationUnit: 'days' | 'weeks' | 'months' | 'years';
}

/**
 * @fileoverview Subscription and recurring payment utilities
 * @module Subscription
 */

/**
 * Calculate total subscription value over a period
 *
 * @param monthlyAmount - Monthly subscription amount
 * @param months - Number of months
 * @param currency - Currency code (default: 'USD')
 * @returns Subscription value calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const result = calculateSubscriptionValue(29.99, 12);
 * console.log(result.totalCost); // 359.88
 * console.log(result.averageMonthlyCost); // 29.99
 * ```
 */
declare function calculateSubscriptionValue(monthlyAmount: number, months: number, currency?: string): SubscriptionValueResult;
/**
 * Compare multiple subscription plans
 *
 * @param plans - Array of subscription plans to compare
 * @returns Plan comparison result with recommendations
 *
 * @throws {MonieUtilsError} When plans array is invalid
 *
 * @example
 * ```typescript
 * const plans = [
 *   { id: 'basic', name: 'Basic', monthlyAmount: 9.99, currency: 'USD' },
 *   { id: 'pro', name: 'Pro', monthlyAmount: 19.99, currency: 'USD', annualDiscount: 0.2 }
 * ];
 * const comparison = compareSubscriptionPlans(plans);
 * console.log(comparison.recommendedPlan.plan.name);
 * ```
 */
declare function compareSubscriptionPlans(plans: SubscriptionPlan[]): PlanComparisonResult;
/**
 * Calculate prorated amount based on usage
 *
 * @param amount - Full amount for the period
 * @param daysUsed - Number of days used
 * @param totalDays - Total days in the period
 * @returns Proration calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const result = calculateProrationAmount(100, 15, 30);
 * console.log(result.proratedAmount); // 50.00
 * console.log(result.usagePercentage); // 50
 * ```
 */
declare function calculateProrationAmount(amount: number, daysUsed: number, totalDays: number): ProrationResult;
/**
 * Calculate upgrade credit when switching plans
 *
 * @param oldPlan - Current subscription plan
 * @param newPlan - New subscription plan to upgrade to
 * @param daysRemaining - Days remaining in current billing period
 * @returns Upgrade credit calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const oldPlan = { id: 'basic', name: 'Basic', monthlyAmount: 9.99, currency: 'USD' };
 * const newPlan = { id: 'pro', name: 'Pro', monthlyAmount: 19.99, currency: 'USD' };
 * const result = calculateUpgradeCredit(oldPlan, newPlan, 15);
 * console.log(result.creditAmount); // Credit from unused portion of old plan
 * console.log(result.netAmountDue); // Additional amount to pay
 * ```
 */
declare function calculateUpgradeCredit(oldPlan: SubscriptionPlan, newPlan: SubscriptionPlan, daysRemaining: number): UpgradeCreditResult;
/**
 * Convert payment amount to annual equivalent
 *
 * @param amount - Payment amount per period
 * @param frequency - Payment frequency
 * @returns Annual equivalent calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const result = calculateAnnualEquivalent(500, 'monthly');
 * console.log(result.annualAmount); // 6000
 * console.log(result.paymentsPerYear); // 12
 * ```
 */
declare function calculateAnnualEquivalent(amount: number, frequency: PaymentFrequency): AnnualEquivalentResult;
/**
 * Calculate next payment date based on start date and frequency
 *
 * @param startDate - Start date of the payment cycle
 * @param frequency - Payment frequency
 * @returns Next payment date
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const nextDate = calculateNextPaymentDate(new Date('2024-01-01'), 'monthly');
 * console.log(nextDate.toISOString()); // 2024-02-01T00:00:00.000Z
 * ```
 */
declare function calculateNextPaymentDate(startDate: Date, frequency: PaymentFrequency): Date;
/**
 * Calculate total recurring cost over a duration
 *
 * @param amount - Payment amount per period
 * @param frequency - Payment frequency
 * @param duration - Duration in months
 * @returns Total recurring cost calculation result
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const result = calculateTotalRecurringCost(100, 'monthly', 24);
 * console.log(result.totalCost); // 2400
 * console.log(result.numberOfPayments); // 24
 * ```
 */
declare function calculateTotalRecurringCost(amount: number, frequency: PaymentFrequency, duration: number): RecurringCostResult;

/**
 * @fileoverview Type definitions for utility functions
 * @module Utils/Types
 */
/**
 * Result of number-to-words conversion
 */
interface NumberToWordsResult {
    /** The number converted to words */
    words: string;
    /** The original number */
    originalNumber: number;
    /** Whether the number was negative */
    isNegative: boolean;
    /** The currency denomination (if applicable) */
    currency?: string;
}
/**
 * Options for formatting account numbers
 */
interface AccountNumberOptions {
    /** Character to use for masking (default: '*') */
    maskChar?: string;
    /** Number of characters to show at the start (default: 4) */
    showFirst?: number;
    /** Number of characters to show at the end (default: 4) */
    showLast?: number;
    /** Whether to apply masking (default: true) */
    applyMask?: boolean;
    /** Separator character for grouping (default: ' ') */
    separator?: string;
    /** Group size for formatting (default: 4) */
    groupSize?: number;
}
/**
 * Result of account number formatting
 */
interface FormattedAccountResult {
    /** The formatted account number */
    formatted: string;
    /** The original account number */
    original: string;
    /** Whether masking was applied */
    isMasked: boolean;
    /** Number of characters masked */
    maskedCharacters: number;
}
/**
 * Options for thousand formatting
 */
interface ThousandFormatOptions {
    /** Separator for thousands (default: ',') */
    separator?: string;
    /** Locale for formatting */
    locale?: string;
    /** Whether to include decimal places */
    includeDecimals?: boolean;
    /** Number of decimal places to show */
    decimalPlaces?: number;
}
/**
 * Banker's rounding mode
 */
type BankersRoundingMode = 'half-even' | 'half-odd';
/**
 * Rounding result with metadata
 */
interface RoundingResult {
    /** The rounded value */
    rounded: number;
    /** The original value */
    original: number;
    /** The rounding method used */
    method: string;
    /** Whether the value was rounded up or down */
    direction: 'up' | 'down' | 'none';
    /** The difference between original and rounded */
    difference: number;
}

/**
 * @fileoverview Utility functions for rounding, precision, and formatting
 * @module Utils
 */

/**
 * Round amount to nearest cent (2 decimal places)
 *
 * @param amount - The amount to round
 * @returns The amount rounded to nearest cent
 *
 * @throws {MonieUtilsError} When amount is invalid
 *
 * @example
 * ```typescript
 * const rounded = roundToNearestCent(123.456);
 * console.log(rounded); // 123.46
 *
 * const rounded2 = roundToNearestCent(123.454);
 * console.log(rounded2); // 123.45
 * ```
 */
declare function roundToNearestCent(amount: number): number;
/**
 * Apply banker's rounding (round half to even)
 *
 * @param amount - The amount to round
 * @param decimalPlaces - Number of decimal places (default: 2)
 * @param mode - Rounding mode (default: 'half-even')
 * @returns The amount with banker's rounding applied
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const rounded = roundToBankersRounding(2.125, 2);
 * console.log(rounded); // 2.12 (rounds to even)
 *
 * const rounded2 = roundToBankersRounding(2.135, 2);
 * console.log(rounded2); // 2.14 (rounds to even)
 * ```
 */
declare function roundToBankersRounding(amount: number, decimalPlaces?: number, mode?: BankersRoundingMode): number;
/**
 * Truncate number to specified decimal places (no rounding)
 *
 * @param amount - The amount to truncate
 * @param places - Number of decimal places to keep
 * @returns The truncated amount
 *
 * @throws {MonieUtilsError} When inputs are invalid
 *
 * @example
 * ```typescript
 * const truncated = truncateToDecimalPlaces(123.456, 2);
 * console.log(truncated); // 123.45
 *
 * const truncated2 = truncateToDecimalPlaces(123.999, 1);
 * console.log(truncated2); // 123.9
 * ```
 */
declare function truncateToDecimalPlaces(amount: number, places: number): number;
/**
 * Ceil amount to nearest cent (round up to 2 decimal places)
 *
 * @param amount - The amount to ceil
 * @returns The amount ceiled to nearest cent
 *
 * @throws {MonieUtilsError} When amount is invalid
 *
 * @example
 * ```typescript
 * const ceiled = ceilToNearestCent(123.451);
 * console.log(ceiled); // 123.46
 *
 * const ceiled2 = ceilToNearestCent(123.00);
 * console.log(ceiled2); // 123.00
 * ```
 */
declare function ceilToNearestCent(amount: number): number;
/**
 * Add thousand separators to a number
 *
 * @param number - The number to format
 * @param options - Formatting options
 * @returns The number with thousand separators
 *
 * @throws {MonieUtilsError} When number is invalid
 *
 * @example
 * ```typescript
 * const formatted = formatThousands(1234567.89);
 * console.log(formatted); // "1,234,567.89"
 *
 * const formatted2 = formatThousands(1234567, { separator: ' ' });
 * console.log(formatted2); // "1 234 567"
 * ```
 */
declare function formatThousands(number: number, options?: ThousandFormatOptions): string;
/**
 * Format amount to hundreds (divide by 100 and format)
 *
 * @param amount - The amount in smallest units (cents)
 * @param options - Formatting options
 * @returns The amount formatted in hundreds
 *
 * @throws {MonieUtilsError} When amount is invalid
 *
 * @example
 * ```typescript
 * const formatted = formatToHundreds(12345);
 * console.log(formatted); // "123.45"
 *
 * const formatted2 = formatToHundreds(12345, { separator: ' ' });
 * console.log(formatted2); // "123.45"
 * ```
 */
declare function formatToHundreds(amount: number, options?: ThousandFormatOptions): string;
/**
 * Remove formatting from a formatted number string
 *
 * @param formattedString - The formatted string to clean
 * @returns The clean number as string
 *
 * @throws {MonieUtilsError} When string is invalid or empty
 *
 * @example
 * ```typescript
 * const clean = removeFormattingFromNumber("1,234,567.89");
 * console.log(clean); // "1234567.89"
 *
 * const clean2 = removeFormattingFromNumber("$1 234 567.89");
 * console.log(clean2); // "1234567.89"
 * ```
 */
declare function removeFormattingFromNumber(formattedString: string): string;
/**
 * Convert number to words (English)
 *
 * @param amount - The number to convert
 * @param currency - Optional currency to include
 * @returns Object with words and metadata
 *
 * @throws {MonieUtilsError} When amount is invalid or too large
 *
 * @example
 * ```typescript
 * const result = convertToWords(123.45);
 * console.log(result.words); // "one hundred twenty-three and forty-five"
 *
 * const result2 = convertToWords(1500, 'USD');
 * console.log(result2.words); // "one thousand five hundred dollars"
 * ```
 */
declare function convertToWords(amount: number, currency?: string): NumberToWordsResult;
/**
 * Format account number with optional masking
 *
 * @param accountNumber - The account number to format
 * @param options - Formatting options
 * @returns Formatted account number result
 *
 * @throws {MonieUtilsError} When account number is invalid
 *
 * @example
 * ```typescript
 * const result = formatAccountNumber("1234567890123456");
 * console.log(result.formatted); // "1234 **** **** 3456"
 *
 * const result2 = formatAccountNumber("1234567890", { showFirst: 2, showLast: 2 });
 * console.log(result2.formatted); // "12** **67 90"
 * ```
 */
declare function formatAccountNumber(accountNumber: string, options?: AccountNumberOptions): FormattedAccountResult;

/**
 * Monie Utils - A comprehensive TypeScript library for money-related utilities
 *
 * @author Oluwaferanmi Adeniji
 * @version 0.1.0
 * @license MIT
 */

declare const VERSION = "0.1.0";
/**
 * Library information
 */
declare const LIBRARY_INFO: {
    readonly name: "monie-utils";
    readonly version: "0.1.0";
    readonly description: "A comprehensive TypeScript library for money-related utilities";
    readonly author: "Oluwaferanmi Adeniji";
    readonly license: "MIT";
};

export { type AccountNumberOptions, type AmortizationPayment, type AmortizationSchedule, type AnnualEquivalentResult, type AnnualizedReturnResult, type ArithmeticResult, type BankersRoundingMode, type BudgetCategory, type BulkConversionResult, COMPACT_SUFFIXES, COMPACT_THRESHOLDS, CURRENCY_INFO, type ConversionResult, type ConversionWithFeeResult, type CreditUtilizationResult, type CurrencyDisplay, type CurrencyInfo, DEFAULT_FORMAT_OPTIONS, DEFAULT_PERCENTAGE_OPTIONS, type DistributionResult, type DividendYieldResult, type ExchangeRate, type FeeStructure, type FormatCurrencyOptions, type FormatOptions, type FormatPercentageOptions, type FormattedAccountResult, type FormattedCurrency, type FormattedDecimalPlaces, type FormattedPercentage, type FormattedWithGrouping, type FutureValueResult, type InterestResult, type InvestmentReturn, LIBRARY_INFO, LOCALE_CURRENCY_MAP, type LoanBalanceResult, type LoanParameters, type LoanPaymentResult, type LocaleCurrencyInfo, type LocaleFormatOptions, type MinimumPaymentResult, type Money, MonieUtilsError, type MonieUtilsError$1 as MonieUtilsErrorType, type NormalizeOptions, type NumberToWordsResult, type ParsedAmount, type ParsedCurrency, type PaymentFrequency, type PayoffTimeResult, type PercentageResult, type PlanAnalysis, type PlanComparisonResult, type ProrationResult, type ROIResult, type RangeOptions, type RecurringCostResult, type RoundingMode, type RoundingResult, type SplitResult, type SubscriptionPlan$1 as SubscriptionPlan, type SubscriptionValueResult, type ThousandFormatOptions, type Transaction, type UpgradeCreditResult, VERSION, addMoney, bulkConvert, calculateAnnualEquivalent, calculateAnnualizedReturn, calculateCompoundInterest, calculateCreditUtilization, calculateDiscount, calculateDividendYield, calculateFutureValue, calculateLoanBalance, calculateMinimumPayment, calculateMonthlyPayment, calculateNextPaymentDate, calculatePayoffTime, calculatePercentageOfTotal, calculateProrationAmount, calculateROI, calculateSimpleInterest, calculateSubscriptionValue, calculateTax, calculateTip, calculateTotalInterest, calculateTotalRecurringCost, calculateUpgradeCredit, ceilToNearestCent, compareSubscriptionPlans, convertCurrency, convertToWords, convertWithFee, createError, distributeProportionally, divideMoney, formatAccountNumber, formatCents, formatCompactCurrency, formatCurrency, formatCurrencyByLocale, formatDecimalPlaces, formatMoney, formatPercentage, formatThousands, formatToHundreds, formatWithGrouping, generateAmortizationSchedule, getLocaleCurrencyInfo, isPositiveAmount, isValidAmount, isValidCurrency, isWithinRange, multiplyMoney, normalizeAmount, parseAmount, parseCurrencyString, parseFormattedCurrency, removeFormattingFromNumber, roundMoney, roundToBankersRounding, roundToNearestCent, splitAmount, subtractMoney, truncateToDecimalPlaces, validateMoneyObject };