/**
 * UAE Dirham currency symbol constants.
 *
 * This package maps the Dirham glyph to the official Unicode codepoint U+20C3
 * (UAE DIRHAM SIGN) via a custom web font. The codepoint was accepted by the
 * Unicode Technical Committee for Unicode 18.0 (expected September 2026).
 *
 * Until system fonts ship native U+20C3 glyphs, the bundled web font provides
 * the rendering. When OS/font support lands, the web font becomes optional;
 * zero migration required.
 *
 * @module dirham
 * @see https://www.unicode.org/alloc/Pipeline.html
 */
/** Unicode character for the Dirham symbol (U+20C3, requires Dirham web font until system fonts support it) */
declare const DIRHAM_UNICODE = "\u20C3";
/** HTML entity for the Dirham symbol */
declare const DIRHAM_HTML_ENTITY = "⃃";
/** CSS content value for use in `::before` / `::after` pseudo-elements */
declare const DIRHAM_CSS_CONTENT = "\\20C3";
/** ISO 4217 currency code for UAE Dirham */
declare const DIRHAM_CURRENCY_CODE = "AED";
/** Arabic text representation of the Dirham symbol (د.إ) */
declare const DIRHAM_SYMBOL_TEXT = "\u062F.\u0625";
/** The font family name used for the Dirham web font */
declare const DIRHAM_FONT_FAMILY = "Dirham";
/** CSS class name for the Dirham icon */
declare const DIRHAM_CSS_CLASS = "dirham-symbol";
/** Unicode codepoint as a number (0x20C3) */
declare const DIRHAM_CODEPOINT = 8387;
/**
 * Supported visual weights for the Dirham symbol SVG component.
 *
 * Because the Dirham symbol is not yet in standard fonts (until Unicode 18.0),
 * weight simulation is applied via SVG stroke to match surrounding text weight,
 * similar to how $, €, £ adapt to their font's weight.
 */
type DirhamWeight = "thin" | "extralight" | "light" | "regular" | "medium" | "semibold" | "bold" | "extrabold" | "black";
/**
 * Map from weight name to CSS `font-weight` numeric value.
 * Used for matching the symbol weight to surrounding text.
 */
declare const DIRHAM_WEIGHT_MAP: Record<DirhamWeight, number>;
/**
 * SVG stroke-width values that simulate font weight.
 * Applied with `paint-order: stroke` so stroke renders behind fill.
 */
declare const DIRHAM_STROKE_MAP: Record<DirhamWeight, number>;

/**
 * Options for formatting a Dirham amount.
 */
interface FormatDirhamOptions {
    /**
     * Locale string for number formatting.
     * @default "en-AE"
     */
    locale?: string;
    /**
     * Number of decimal places.
     * @default 2
     */
    decimals?: number;
    /**
     * Whether to place the symbol before the amount.
     * When `undefined`, determined by locale:
     * - Arabic locales (ar-*): symbol after amount
     * - Other locales: symbol before amount
     */
    symbolFirst?: boolean;
    /**
     * Use ISO currency code (AED) instead of the symbol.
     * @default false
     */
    useCode?: boolean;
    /**
     * Separator between symbol and amount.
     * @default " " (non-breaking space)
     */
    separator?: string;
    /**
     * Number notation style.
     * - `"standard"` — full digits (e.g. 1,500,000.00)
     * - `"compact"` — abbreviated (e.g. 1.5M)
     * @default "standard"
     */
    notation?: "standard" | "compact";
}
/**
 * Format a number as a Dirham currency string.
 *
 * @example
 * ```ts
 * formatDirham(100);          // "\u20C3 100.00"
 * formatDirham(1234.5);       // "\u20C3 1,234.50"
 * formatDirham(100, { locale: "ar-AE" }); // "100.00 \u20C3"
 * formatDirham(100, { useCode: true });   // "AED 100.00"
 * formatDirham(1500000, { notation: "compact" }); // "\u20C3 1.5M"
 * ```
 */
declare function formatDirham(amount: number, options?: FormatDirhamOptions): string;
/**
 * Options for parsing a Dirham-formatted string.
 */
interface ParseDirhamOptions {
    /**
     * Normalize Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩ / U+0660–U+0669) to ASCII
     * digits before parsing. Enables round-tripping strings produced by
     * `formatDirham` with Arabic locales (e.g. `"ar-AE"`).
     * @default true
     */
    normalizeArabicNumerals?: boolean;
}
/**
 * Parse a Dirham-formatted string back to a number.
 * Strips currency symbols, codes, and formatting characters.
 * By default also normalizes Arabic-Indic digits so strings produced by
 * `formatDirham({ locale: "ar-AE" })` round-trip correctly.
 *
 * @example
 * ```ts
 * parseDirham("\u20C3 1,234.50");                  // 1234.5
 * parseDirham("AED 100.00");                        // 100
 * parseDirham("١٬٢٣٤٫٥٠ \u20C3");                  // 1234.5
 * parseDirham("١٠٠٫٠٠ \u20C3", { normalizeArabicNumerals: false }); // throws
 * ```
 */
declare function parseDirham(value: string, options?: ParseDirhamOptions): number;

/**
 * Format of the Dirham symbol to copy.
 *
 * - `"unicode"` — the character itself (`\u20C3`)
 * - `"html"` — HTML entity (`&#x20C3;`)
 * - `"css"` — CSS content value (`\\20C3`)
 * - `"arabic"` — Arabic text (د.إ)
 */
type DirhamCopyFormat = "unicode" | "html" | "css" | "arabic";
/**
 * Copy the Dirham symbol to the clipboard in the specified format.
 *
 * @returns A promise that resolves when the text is on the clipboard.
 * @throws If the Clipboard API is unavailable (e.g. non-browser environment).
 *
 * @example
 * ```ts
 * import { copyDirhamSymbol } from "dirham";
 *
 * await copyDirhamSymbol();          // copies "\u20C3"
 * await copyDirhamSymbol("html");    // copies "&#x20C3;"
 * await copyDirhamSymbol("css");     // copies "\\20C3"
 * ```
 */
declare function copyDirhamSymbol(format?: DirhamCopyFormat): Promise<void>;

/**
 * Copy a formatted Dirham amount to the clipboard.
 *
 * Combines `formatDirham()` with the Clipboard API so users can
 * paste a fully formatted price (e.g. "ৃ 1,234.50") into documents.
 *
 * @example
 * ```ts
 * import { copyDirhamAmount } from "dirham";
 *
 * await copyDirhamAmount(1234.5);                      // copies "ৃ 1,234.50"
 * await copyDirhamAmount(1234.5, { useCode: true });   // copies "AED 1,234.50"
 * await copyDirhamAmount(500, { locale: "ar-AE" });    // copies "500.00 ৃ"
 * ```
 *
 * @returns A promise that resolves when the text is on the clipboard.
 * @throws If the Clipboard API is unavailable or the amount is not finite.
 */
declare function copyDirhamAmount(amount: number, options?: FormatDirhamOptions): Promise<void>;

/**
 * UAE VAT rate (5%).
 * @see https://tax.gov.ae/en/taxes/vat.aspx
 */
declare const UAE_VAT_RATE = 0.05;
/**
 * Options for VAT calculation.
 */
interface VATOptions {
    /**
     * VAT rate as a decimal (e.g. 0.05 for 5%).
     * @default 0.05 (UAE standard rate)
     */
    rate?: number;
    /**
     * Number of decimal places to round the result to.
     * @default 2
     */
    decimals?: number;
}
/**
 * Add VAT to an amount.
 *
 * @example
 * ```ts
 * addVAT(100);           // 105
 * addVAT(100, { rate: 0.1 }); // 110
 * addVAT(99.99);         // 104.99
 * ```
 */
declare function addVAT(amount: number, options?: VATOptions): number;
/**
 * Remove VAT from a VAT-inclusive amount.
 * Returns the original pre-VAT amount.
 *
 * @example
 * ```ts
 * removeVAT(105);         // 100
 * removeVAT(110, { rate: 0.1 }); // 100
 * ```
 */
declare function removeVAT(amount: number, options?: VATOptions): number;
/**
 * Get the VAT amount from a pre-VAT price.
 *
 * @example
 * ```ts
 * getVAT(100);  // 5
 * getVAT(200);  // 10
 * ```
 */
declare function getVAT(amount: number, options?: VATOptions): number;

/**
 * Options for currency conversion.
 */
interface ConvertOptions {
    /**
     * Number of decimal places for the result.
     * @default 2
     */
    decimals?: number;
    /**
     * Custom exchange rate (AED per 1 unit of target currency).
     * When provided, skips network fetch.
     */
    rate?: number;
}
/**
 * Fetch exchange rates from the Central Bank of UAE open API.
 * Results are cached in memory for 1 hour.
 *
 * Uses the free, no-auth-required exchangerate.host API as a fallback-safe source.
 *
 * @returns Map of currency codes to their AED exchange rates.
 */
declare function fetchExchangeRates(): Promise<Record<string, number>>;
/**
 * Clear the in-memory exchange rate cache.
 * Useful for testing or forcing a refresh.
 */
declare function clearRateCache(): void;
/**
 * Convert an AED amount to another currency.
 *
 * @example
 * ```ts
 * const usd = await convertFromAED(100, "USD");
 * const eur = await convertFromAED(100, "EUR", { decimals: 4 });
 * const manual = await convertFromAED(100, "USD", { rate: 0.2723 });
 * ```
 */
declare function convertFromAED(amount: number, currency: string, options?: ConvertOptions): Promise<number>;
/**
 * Convert a foreign currency amount to AED.
 *
 * @example
 * ```ts
 * const aed = await convertToAED(27.23, "USD");
 * ```
 */
declare function convertToAED(amount: number, currency: string, options?: ConvertOptions): Promise<number>;

export { type ConvertOptions, DIRHAM_CODEPOINT, DIRHAM_CSS_CLASS, DIRHAM_CSS_CONTENT, DIRHAM_CURRENCY_CODE, DIRHAM_FONT_FAMILY, DIRHAM_HTML_ENTITY, DIRHAM_STROKE_MAP, DIRHAM_SYMBOL_TEXT, DIRHAM_UNICODE, DIRHAM_WEIGHT_MAP, type DirhamCopyFormat, type DirhamWeight, type FormatDirhamOptions, UAE_VAT_RATE, type VATOptions, addVAT, clearRateCache, convertFromAED, convertToAED, copyDirhamAmount, copyDirhamSymbol, fetchExchangeRates, formatDirham, getVAT, parseDirham, removeVAT };