/**
 * Tutorial System
 * Manages tutorial progress, tooltips, and onboarding flow.
 * Ported from Python retention/tutorial.py
 *
 * Features:
 * - Tutorial step progression with database persistence
 * - Tooltip tracking to prevent showing tooltips multiple times
 * - Onboarding completion with achievement rewards
 * - Tutorial mode detection based on game hours played
 */
import { Player } from '../../models/Player.js';
import { awardDiamonds } from '../../monetization/diamondEconomy.js';
export interface TutorialState {
    step: number;
    isComplete: boolean;
    onboardingComplete: boolean;
    tooltipsShown: Set<string>;
    tooltipsSeen: Record<string, boolean>;
    skipTutorial: boolean;
    startedAt: Date;
    completedAt: Date | null;
    firstSessionDate: Date | null;
}
export interface TooltipConfig {
    id: string;
    title: string;
    message: string;
    targetElement: string;
    position: 'top' | 'bottom' | 'left' | 'right';
    arrowDirection: 'up' | 'down' | 'left' | 'right';
    order: number;
}
export interface TutorialMessage {
    type: string;
    step?: number;
    message?: string;
    isComplete?: boolean;
    reward?: number;
    error?: string;
    [key: string]: unknown;
}
/**
 * Result types for database operations
 */
export interface TutorialOperationResult {
    success: boolean;
    error?: string;
    tutorialStep?: number;
    onboardingComplete?: boolean;
    newStep?: number;
    rewardDiamonds?: number;
}
export declare const TUTORIAL_STEPS: {
    step: number;
    title: string;
    message: string;
    targetElement: string;
}[];
export declare const TUTORIAL_COMPLETION_REWARD = 50;
export declare const ONBOARDING_COMPLETION_REWARD = 25;
export declare const TUTORIAL_MODE_HOURS = 24;
export declare const TUTORIAL_GAME_SPEED_MULTIPLIER = 2;
/**
 * Validate tooltip ID contains only safe characters
 * Prevents JSON path injection in database queries
 */
export declare function validateTooltipId(tooltipId: string): boolean;
/**
 * Check if player is in tutorial mode (first 24 in-game hours)
 * Ported from Python is_tutorial_mode()
 *
 * @param player - Player object
 * @param gameHours - Optional override for testing
 * @returns true if player is in tutorial mode
 */
export declare function isTutorialMode(player: Player, gameHours?: number): boolean;
/**
 * Apply tutorial game speed modifier
 * Makes the game run slower during tutorial mode to give players time to learn
 * Ported from Python apply_tutorial_modifiers() (game speed portion)
 *
 * @param player - Player object
 * @param requestedSpeed - The speed the player requested
 * @returns Modified game speed (slower during tutorial)
 */
export declare function applyTutorialGameSpeedModifier(player: Player, requestedSpeed: number): number;
/**
 * Get the recommended tutorial game speed
 * Returns a slower default speed for new players
 *
 * @param player - Player object
 * @param defaultSpeed - The normal default speed
 * @returns Tutorial-appropriate game speed
 */
export declare function getTutorialGameSpeed(player: Player, defaultSpeed: number): number;
/**
 * Check if the game should auto-pause for a tutorial moment
 * Some events during tutorial should pause the game to let players read
 *
 * @param player - Player object
 * @param eventType - Type of event being triggered
 * @returns true if game should pause
 */
export declare function shouldPauseForTutorial(player: Player, eventType: string): boolean;
/**
 * Initialize tutorial tracking for new player in database
 * Ported from Python initialize_tutorial()
 *
 * @param playerId - Player ID (number for database)
 * @returns Operation result with tutorial state
 */
export declare function initializeTutorialInDb(playerId: number): Promise<TutorialOperationResult>;
/**
 * Get tutorial progress from database
 * Ported from Python get_tutorial_progress()
 *
 * @param playerId - Player ID
 * @returns Tutorial state or null if not found
 */
export declare function getTutorialProgressFromDb(playerId: number): Promise<TutorialState | null>;
/**
 * Update tutorial step in database
 * Ported from Python update_tutorial_step()
 *
 * @param playerId - Player ID
 * @param newStep - New tutorial step (0-99)
 * @returns Operation result
 */
export declare function updateTutorialStepInDb(playerId: number, newStep: number): Promise<TutorialOperationResult>;
/**
 * Mark a tooltip as seen in database
 * Ported from Python mark_tooltip_seen()
 *
 * Uses JSON_SET for atomic update to prevent race conditions
 *
 * @param playerId - Player ID
 * @param tooltipId - Tooltip identifier (must match pattern)
 * @returns Operation result
 */
export declare function markTooltipSeenInDb(playerId: number, tooltipId: string): Promise<TutorialOperationResult>;
/**
 * Mark onboarding as complete and award achievement
 * Ported from Python complete_onboarding()
 *
 * @param playerId - Player ID
 * @returns Operation result with reward amount
 */
export declare function completeOnboardingInDb(playerId: number): Promise<TutorialOperationResult>;
/**
 * Initialize tutorial state for a new player
 * Creates in-memory state and optionally syncs to database
 *
 * @param playerId - Player ID (string for in-memory, converted to number for DB)
 * @param syncToDb - Whether to also initialize in database (default: false)
 */
export declare function initializeTutorial(playerId: string, syncToDb?: boolean): TutorialState;
/**
 * Load tutorial state from database into memory cache
 *
 * @param playerId - Player ID
 * @returns Tutorial state or null if not found
 */
export declare function loadTutorialState(playerId: string): Promise<TutorialState | null>;
/**
 * Get current tutorial state for a player
 */
export declare function getTutorialState(playerId: string): TutorialState | null;
/**
 * Check if tutorial is complete
 */
export declare function isTutorialComplete(playerId: string): boolean;
/**
 * Get current tutorial step
 */
export declare function getCurrentStep(playerId: string): number;
/**
 * Advance to next tutorial step
 */
export declare function advanceTutorialStep(playerId: string): TutorialMessage;
/**
 * Complete the tutorial and award reward
 */
export declare function completeTutorial(playerId: string): TutorialMessage;
/**
 * Complete the onboarding phase (distinct from tutorial completion)
 * Marks onboarding as complete and awards the "First Steps" achievement
 * Ported from Python complete_onboarding()
 *
 * @param playerId - Player ID
 * @param syncToDb - Whether to sync to database (default: true)
 * @returns Tutorial message with reward info
 */
export declare function completeOnboarding(playerId: string, syncToDb?: boolean, playerState?: Parameters<typeof awardDiamonds>[3]): Promise<TutorialMessage>;
/**
 * Skip the tutorial
 */
export declare function skipTutorial(playerId: string): TutorialMessage;
/**
 * Reset tutorial for a player (for replay)
 */
export declare function resetTutorial(playerId: string): TutorialMessage;
/**
 * Mark a tooltip as shown
 * Updates both in-memory state and database
 *
 * @param playerId - Player ID
 * @param tooltipId - Tooltip identifier
 * @param syncToDb - Whether to sync to database (default: true)
 */
export declare function markTooltipShown(playerId: string, tooltipId: string, syncToDb?: boolean): void;
/**
 * Check if a tooltip has been shown
 */
export declare function hasTooltipBeenShown(playerId: string, tooltipId: string): boolean;
/**
 * Get list of tooltips not yet shown
 */
export declare function getUnshownTooltips(playerId: string, tooltipIds: string[]): string[];
export interface TutorialActionMessage {
    action?: string;
    tooltipId?: string;
    step?: number;
}
export type SendToClientFn = (playerId: string, message: Record<string, unknown>) => void;
/**
 * Tutorial trigger condition
 */
export interface TutorialTrigger {
    name: string;
    condition: (player: Player) => boolean;
    eventType: string;
}
/**
 * Define all tutorial trigger conditions
 * Each trigger checks a specific game state condition
 */
export declare const TUTORIAL_TRIGGERS: TutorialTrigger[];
/**
 * Check which tutorial events should be triggered based on player state
 * Ported from Python check_tutorial_triggers()
 *
 * @param player - Player object
 * @returns Array of trigger names that should fire
 */
export declare function checkTutorialTriggers(player: Player): string[];
/**
 * Get tutorial state for client including current triggers
 *
 * @param player - Player object
 * @returns Full tutorial state with triggers
 */
export declare function getTutorialStateForPlayer(player: Player): {
    step: number;
    isComplete: boolean;
    onboardingComplete: boolean;
    isTutorialMode: boolean;
    pendingTriggers: string[];
    totalSteps: number;
    currentStepInfo: (typeof TUTORIAL_STEPS)[number] | null;
};
/**
 * Handle tutorial-related WebSocket messages
 */
export declare function handleTutorialAction(playerId: string, messageData: TutorialActionMessage, sendToClient: SendToClientFn): void;
/**
 * Handle tutorialStepComplete message from client
 * Ported from Python handle_tutorial_step_complete()
 */
export declare function handleTutorialStepComplete(playerId: string, messageData: {
    step: number;
}, sendToClient: SendToClientFn): Promise<void>;
/**
 * Handle tooltipSeen message from client
 * Ported from Python handle_tooltip_seen()
 */
export declare function handleTooltipSeen(playerId: string, messageData: {
    tooltipId: string;
}): void;
/**
 * Handle completeOnboarding message from client
 * Ported from Python handle_complete_onboarding()
 */
export declare function handleCompleteOnboarding(playerId: string, sendToClient: SendToClientFn, playerState?: Parameters<typeof awardDiamonds>[3]): Promise<void>;
/**
 * Clear tutorial state for a player
 */
export declare function clearPlayerTutorial(playerId: string): void;
/**
 * Clear all tutorial states (for testing)
 */
export declare function clearAllTutorials(): void;
export declare const tutorialManager: {
    initializeTutorial: typeof initializeTutorial;
    getTutorialState: typeof getTutorialState;
    isTutorialComplete: typeof isTutorialComplete;
    getCurrentStep: typeof getCurrentStep;
    advanceTutorialStep: typeof advanceTutorialStep;
    completeTutorial: typeof completeTutorial;
    skipTutorial: typeof skipTutorial;
    resetTutorial: typeof resetTutorial;
    isTutorialMode: typeof isTutorialMode;
    applyTutorialGameSpeedModifier: typeof applyTutorialGameSpeedModifier;
    getTutorialGameSpeed: typeof getTutorialGameSpeed;
    shouldPauseForTutorial: typeof shouldPauseForTutorial;
    completeOnboarding: typeof completeOnboarding;
    markTooltipShown: typeof markTooltipShown;
    hasTooltipBeenShown: typeof hasTooltipBeenShown;
    getUnshownTooltips: typeof getUnshownTooltips;
    validateTooltipId: typeof validateTooltipId;
    checkTutorialTriggers: typeof checkTutorialTriggers;
    getTutorialStateForPlayer: typeof getTutorialStateForPlayer;
    TUTORIAL_TRIGGERS: TutorialTrigger[];
    handleTutorialAction: typeof handleTutorialAction;
    handleTutorialStepComplete: typeof handleTutorialStepComplete;
    handleTooltipSeen: typeof handleTooltipSeen;
    handleCompleteOnboarding: typeof handleCompleteOnboarding;
    initializeTutorialInDb: typeof initializeTutorialInDb;
    getTutorialProgressFromDb: typeof getTutorialProgressFromDb;
    updateTutorialStepInDb: typeof updateTutorialStepInDb;
    markTooltipSeenInDb: typeof markTooltipSeenInDb;
    completeOnboardingInDb: typeof completeOnboardingInDb;
    loadTutorialState: typeof loadTutorialState;
    clearPlayerTutorial: typeof clearPlayerTutorial;
    clearAllTutorials: typeof clearAllTutorials;
    TUTORIAL_STEPS: {
        step: number;
        title: string;
        message: string;
        targetElement: string;
    }[];
    TUTORIAL_COMPLETION_REWARD: number;
    ONBOARDING_COMPLETION_REWARD: number;
    TUTORIAL_MODE_HOURS: number;
    TUTORIAL_GAME_SPEED_MULTIPLIER: number;
};
//# sourceMappingURL=tutorial.d.ts.map