/**
 * Type definitions for the TT-BBS App API
 *
 * These types define the interfaces that BBS apps must implement
 * to be compatible with the TT-BBS system.
 */
/**
 * BBS App interface
 *
 * All BBS apps must implement this interface to be loaded by the system.
 */
export interface BbsApp {
    /**
     * Unique identifier for the app
     * Use a short, lowercase string with no spaces
     */
    id: string;
    /**
     * Display name of the app
     * This is shown to users in the main menu
     */
    name: string;
    /**
     * Version of the app
     * Use semantic versioning (e.g. 1.0.0)
     */
    version: string;
    /**
     * Brief description of the app
     * This may be shown to users in the app list or help screens
     */
    description: string;
    /**
     * Author of the app
     * Your name or organization
     */
    author: string;
    /**
     * Optional source URL of the app
     * This is used for tracking where the app was loaded from (e.g., GitHub URL)
     */
    source?: string;
    /**
     * Get the welcome screen content
     * This is displayed when a user first enters the app
     *
     * @returns A string containing the welcome screen text
     */
    getWelcomeScreen: () => string;
    /**
     * Handle user commands
     * This is called whenever a user enters a command while using your app
     *
     * @param screenId The current screen ID (null for the initial screen)
     * @param command The command entered by the user
     * @param session The user's session data
     * @returns A CommandResult object with the response and navigation info
     */
    handleCommand: (screenId: string | null, command: string, session: BbsSession) => CommandResult;
    /**
     * Get help text for the current screen
     * This is called when a user types HELP while using your app
     *
     * @param screenId The current screen ID
     * @returns A string containing help text for the current screen
     */
    getHelp: (screenId: string | null) => string;
    /**
     * (Optional) Initialize the app
     * This is called when the app is first loaded by the system
     */
    onInit: (injectedServices?: any) => void;
    /**
     * (Optional) Handle user entry to your app
     * This is called when a user first enters your app
     *
     * @param userId The ID of the user
     * @param session The user's session data
     */
    onUserEnter?: (userId: string, session: BbsSession) => void;
    /**
     * (Optional) Handle user exit from your app
     * This is called when a user exits your app
     *
     * @param userId The ID of the user
     * @param session The user's session data
     */
    onUserExit?: (userId: string, session: BbsSession) => void;
}
/**
 * Command Result interface
 *
 * This is returned by the handleCommand method of BBS apps
 * to tell the system how to respond to the user's command.
 */
export interface CommandResult {
    /**
     * The screen to display next
     * - If a string, the system will navigate to that screen within your app
     * - If null, the system will exit your app and return to the main menu
     */
    screen: string | null;
    /**
     * Text response to display to the user
     */
    response: string;
    /**
     * Whether to refresh the entire screen
     * - true: Replace the entire screen with the response
     * - false: Append the response to the current screen
     */
    refresh: boolean;
    /**
     * (Optional) Additional data to pass to the client
     * This can be used for custom behavior in the terminal UI
     */
    data?: any;
    /**
     * (Optional) The area to navigate to
     * This is used by the system for internal routing between apps/screens
     * Apps shouldn't need to set this directly as it's handled by the core system
     */
    area?: string;
}
/**
 * Session interface
 *
 * This represents a user's session data.
 */
export interface BbsSession {
    /**
     * Unique identifier for the session
     */
    sessionId: string;
    /**
     * User ID, if the user is logged in
     */
    userId?: string;
    /**
     * Username, if the user is logged in
     */
    username?: string;
    /**
     * Current area in the format "appId:screenId" or "main"
     */
    currentArea: string;
    /**
     * Command history for this session
     */
    commandHistory: string[];
    /**
     * Custom session data that apps can use
     */
    data: Record<string, any>;
}
/**
 * User interface
 *
 * This represents a user of the BBS system.
 */
export interface BbsUser {
    /**
     * Unique identifier for the user
     */
    id: string;
    /**
     * Username
     */
    username: string;
    /**
     * Display name
     */
    displayName: string;
    /**
     * Email address
     */
    email?: string;
    /**
     * Bio or about text
     */
    bio?: string;
    /**
     * Join date
     */
    joinDate: string;
    /**
     * Last login date
     */
    lastLogin: string;
}
/**
 * Configuration for custom data persistence
 *
 * Apps can implement this interface to store custom data.
 */
export interface BbsStorage {
    /**
     * Get data from storage
     *
     * @param key The key to retrieve
     * @returns The data or null if not found
     */
    getData: (key: string) => Promise<any | null>;
    /**
     * Set data in storage
     *
     * @param key The key to store under
     * @param data The data to store
     * @returns Whether the operation was successful
     */
    setData: (key: string, data: any) => Promise<boolean>;
    /**
     * Delete data from storage
     *
     * @param key The key to delete
     * @returns Whether the operation was successful
     */
    deleteData: (key: string) => Promise<boolean>;
}
/**
 * Utility functions and helpers for BBS apps
 */
export interface BbsUtils {
    /**
     * Format a date string
     *
     * @param date The date to format
     * @param format The format string
     * @returns Formatted date string
     */
    formatDate: (date: Date | string, format?: string) => string;
    /**
     * Generate ASCII art for text
     *
     * @param text The text to convert to ASCII art
     * @returns ASCII art string
     */
    generateAsciiArt: (text: string) => string;
    /**
     * Create a horizontal rule/separator line
     *
     * @param char The character to use (default: ▄)
     * @param width The width of the line (default: 80)
     * @returns The separator string
     */
    createSeparator: (char?: string, width?: number) => string;
}
export interface CommandRequest {
    sessionId: string;
    command: string;
}