@usex/key-fleur/dist/index.d.mts

Generate beautiful, memorable, and poetic API keys and unique identifiers for your applications.

type ThemeKey = "haiku" | "nocturnal" | "sunny" | "floreal" | "oceanic" | "crystalline" | "mythic" | "forest" | "desert" | "celestial" | "library" | "decay" | "steampunk";
type ModeKey = "haiku" | "lace" | "mirrora" | "rune" | "sonnet" | "sigil" | "seed" | "mantra" | "quartz";
type ThemeWords = Record<ThemeKey, string[]>;
type ModeFunction = (theme: ThemeKey) => string;
type ModeFunctions = Record<ModeKey, ModeFunction>;

declare const THEMES: ThemeWords;

/**
 * Dictionary mapping mode names to their corresponding generation functions.
 * Each function takes a ThemeKey and returns a generated key string.
 *
 * Available modes:
 * - haiku: 5-7-5 syllable pattern
 * - lace: Palindromic pattern with word reversals
 * - mirrora: Simple syllable mirroring
 * - rune: Haiku combined with temporal runes
 * - sonnet: Words with syllable embellishments
 * - sigil: Word-number-word format
 * - seed: Word prefix with hexadecimal
 * - mantra: Repetitive word patterns
 * - quartz: Complex mirroring with numbers
 */
declare const MODES: ModeFunctions;

/**
 * Generates a poetic key using the specified mode and theme.
 * This is the core function that orchestrates key generation.
 *
 * @param mode - Generation mode to use (defaults to "haiku")
 * @param theme - Thematic word collection to use (defaults to "haiku")
 * @returns A generated poetic key string
 * @example
 * ```typescript
 * poeticKey(); // Uses default haiku mode and theme
 * poeticKey("sigil", "celestial"); // Generate celestial-themed sigil
 * poeticKey("lace", "oceanic"); // Generate oceanic-themed lace pattern
 * ```
 */
declare function poeticKey(mode?: ModeKey, theme?: ThemeKey): string;
/**
 * Main generation function - primary interface for creating KeyFleur keys.
 * Provides a clean API with comprehensive options and validation.
 *
 * @param options - Configuration object for key generation
 * @param options.mode - Generation mode (defaults to "haiku")
 * @param options.theme - Theme collection (defaults to "haiku")
 * @param options.count - Number of keys to generate (defaults to 1)
 * @returns Single key string or array of keys if count > 1
 * @example
 * ```typescript
 * generateKeyFleur(); // Single haiku key
 * generateKeyFleur({ mode: "sigil", theme: "mythic" }); // Mythic sigil
 * generateKeyFleur({ count: 5, theme: "oceanic" }); // Array of 5 oceanic keys
 * ```
 */
declare function generateKeyFleur(options?: {
    mode?: ModeKey;
    theme?: ThemeKey;
    count?: number;
}): string | string[];
/**
 * Validates if a string matches KeyFleur key patterns.
 * Checks against known patterns for each generation mode.
 *
 * @param key - String to validate
 * @param mode - Expected mode (optional - will check all modes if not specified)
 * @returns Object with validation result and details
 * @example
 * ```typescript
 * isValidKeyFleur("Luna-Eclipse-Void"); // { valid: true, mode: "haiku", ... }
 * isValidKeyFleur("Crystal-459-Gem", "sigil"); // { valid: true, mode: "sigil", ... }
 * isValidKeyFleur("invalid"); // { valid: false, reason: "...", ... }
 * ```
 */
declare function isValidKeyFleur(key: string, mode?: ModeKey): {
    valid: boolean;
    mode?: ModeKey;
    reason?: string;
    parts?: string[];
};

export { MODES, THEMES, generateKeyFleur, isValidKeyFleur, poeticKey };
export type { ModeKey, ThemeKey };