/**
 * Core XP manipulation functions that integrate with store, math, and events.
 *
 * ## Multi-Store Support
 *
 * All functions accept an optional `storeId` field within their options objects to target
 * specific data stores. The default store ('default') is used by built-in commands.
 *
 * Events emitted by these functions include the `storeId` field, allowing event listeners
 * to filter events by store. Role rewards only process default store events to avoid
 * conflicts (e.g., reputation store shouldn't grant Discord roles).
 *
 * ## Custom Level Curves
 *
 * All XP manipulation functions automatically resolve and use the configured level curve
 * for the guild and store. Curves are resolved using three-tier precedence:
 * 1. Plugin getCurve callback (code-based, dynamic)
 * 2. Guild preset configuration (stored in Flashcore)
 * 3. Default quadratic curve (standard formula)
 *
 * If a curve defines a maxLevel, users cannot exceed it through any XP operation.
 * XP values are automatically capped at the maxLevel threshold.
 *
 * @example
 * ```typescript
 * import { addXP, removeXP, setXP, recalcLevel } from './core/xp.js'
 *
 * // Award XP to a user (default store)
 * const result = await addXP('guildId', 'userId', 100, { reason: 'contest_winner' })
 * if (result.leveledUp) {
 *   console.log(`User leveled up to ${result.newLevel}!`)
 * }
 *
 * // Award XP to custom reputation store
 * await addXP('guildId', 'userId', 50, { reason: 'helped_user', storeId: 'reputation' })
 *
 * // Get XP from custom credits store
 * const credits = await getXP('guildId', 'userId', { storeId: 'credits' })
 *
 * // Recalculate level from total XP
 * await recalcLevel('guildId', 'userId')
 *
 * // Event listeners can filter by storeId
 * events.on('levelUp', (event) => {
 *   if (event.storeId === 'reputation') {
 *     console.log('Reputation level up!')
 *   }
 * })
 * ```
 */
import type { UserXP, AddXPOptions, GetXPOptions, RecalcOptions } from '../types.js';
export interface XPChangeResult {
    oldXp: number;
    newXp: number;
    oldLevel: number;
    newLevel: number;
    leveledUp: boolean;
}
export interface XPRemoveResult {
    oldXp: number;
    newXp: number;
    oldLevel: number;
    newLevel: number;
    leveledDown: boolean;
}
export interface XPSetResult {
    oldXp: number;
    newXp: number;
    oldLevel: number;
    newLevel: number;
}
export interface RecalcResult {
    oldLevel: number;
    newLevel: number;
    totalXp: number;
    reconciled: boolean;
}
/**
 * Adds XP to a user, computes level changes, and emits events.
 * Events are emitted after persistence for consistency.
 * Role reconciliation happens automatically via event listeners.
 * If the guild's level curve defines a maxLevel, users cannot exceed it.
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param amount - Amount of XP to add (must be positive)
 * @param options - Optional settings like reason and storeId
 * @returns Result object with old/new XP, levels, and leveledUp flag
 *
 * @example
 * // Default store
 * await addXP('guildId', 'userId', 100, { reason: 'message' })
 *
 * @example
 * // Custom store
 * await addXP('guildId', 'userId', 50, { reason: 'quest', storeId: 'reputation' })
 */
export declare function addXP(guildId: string, userId: string, amount: number, options?: AddXPOptions): Promise<XPChangeResult>;
/**
 * Removes XP from a user (calls addXP with negative amount).
 * Ensures XP doesn't go below 0.
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param amount - Amount of XP to remove (must be positive)
 * @param options - Optional settings like reason and storeId
 * @returns Result object with old/new XP, levels, and leveledDown flag
 */
export declare function removeXP(guildId: string, userId: string, amount: number, options?: AddXPOptions): Promise<XPRemoveResult>;
/**
 * Sets absolute XP value for a user.
 * If the guild's level curve defines a maxLevel, users cannot exceed it.
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param totalXp - New total XP (must be non-negative)
 * @param options - Optional settings like reason and storeId
 * @returns Result object with old/new XP and levels
 */
export declare function setXP(guildId: string, userId: string, totalXp: number, options?: AddXPOptions): Promise<XPSetResult>;
/**
 * Recalculates level from total XP and reconciles roles.
 * Useful for fixing inconsistencies after config changes or manual database edits.
 * Recalculation uses the current level curve configuration, which may differ from
 * when XP was originally awarded.
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param options - Optional settings like storeId
 * @returns Result object with old/new levels and reconciliation status
 *
 * @example
 * // Default store
 * await recalcLevel('guildId', 'userId')
 *
 * @example
 * // Custom store
 * await recalcLevel('guildId', 'userId', { storeId: 'reputation' })
 */
export declare function recalcLevel(guildId: string, userId: string, options?: RecalcOptions): Promise<RecalcResult>;
/**
 * Returns user's total XP (0 if not found).
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param options - Optional settings like storeId
 * @returns Total XP
 *
 * @example
 * // Default store
 * const xp = await getXP('guildId', 'userId')
 *
 * @example
 * // Custom store
 * const reputation = await getXP('guildId', 'userId', { storeId: 'reputation' })
 */
export declare function getXP(guildId: string, userId: string, options?: GetXPOptions): Promise<number>;
/**
 * Returns user's level (0 if not found).
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param options - Optional settings like storeId
 * @returns User level
 *
 * @example
 * // Default store
 * const level = await getLevel('guildId', 'userId')
 *
 * @example
 * // Custom store
 * const repLevel = await getLevel('guildId', 'userId', { storeId: 'reputation' })
 */
export declare function getLevel(guildId: string, userId: string, options?: GetXPOptions): Promise<number>;
/**
 * Returns full user XP record.
 *
 * @param guildId - Guild snowflake ID
 * @param userId - User snowflake ID
 * @param options - Optional settings like storeId
 * @returns User XP record or null if not found
 *
 * @example
 * // Default store
 * const userData = await getUserData('guildId', 'userId')
 *
 * @example
 * // Custom store
 * const repData = await getUserData('guildId', 'userId', { storeId: 'reputation' })
 */
export declare function getUserData(guildId: string, userId: string, options?: GetXPOptions): Promise<UserXP | null>;