/**
 * Plugin configuration options
 */
/**
 * Plugin operation mode
 *
 * Controls how the Vite plugin operates during development:
 * - `'platform'`: Full Playcademy platform experience with sandbox server, backend bundling, and shell wrapper (default)
 * - `'demo'`: Shell-backed development mode that initializes the SDK with `mode: 'demo'`
 * - `'standalone'`: Backend only, no sandbox or shell
 *
 * @default 'platform'
 */
export type PlaycademyMode = 'platform' | 'demo' | 'standalone';
/**
 * Configuration options for exporting/building Playcademy games
 *
 * Controls how your game is packaged for deployment.
 */
export interface PlaycademyExportOptions {
    /**
     * Automatically create a deployment zip archive after build.
     *
     * The zip file is created at `.playcademy/{project-name}.zip` and contains
     * all files needed for deployment (frontend assets + backend bundle).
     *
     * @default true
     * @example
     * ```ts
     * export: {
     *   autoZip: false // Disable auto-zipping
     * }
     * ```
     */
    autoZip?: boolean;
}
/**
 * Configuration options for the Playcademy sandbox server
 *
 * The sandbox server provides a local development environment that simulates
 * the Playcademy platform, including API endpoints, authentication, and database.
 */
export interface PlaycademySandboxOptions {
    /**
     * Automatically start the sandbox server when Vite starts.
     *
     * Set to `false` if you want to start the sandbox server manually.
     *
     * @default true
     * @example
     * ```ts
     * sandbox: {
     *   autoStart: false // Start sandbox manually
     * }
     * ```
     */
    autoStart?: boolean;
    /**
     * Custom URL for the sandbox server.
     *
     * Useful if you need to run the sandbox on a specific host or port.
     * By default, the sandbox uses `http://localhost:{port}` where port
     * is auto-assigned.
     *
     * @example
     * ```ts
     * sandbox: {
     *   url: 'http://localhost:8788'
     * }
     * ```
     */
    url?: string;
    /**
     * Enable verbose logging for the sandbox server.
     *
     * Shows detailed information about requests, database operations, and more.
     * Equivalent to setting `logLevel: 'debug'`.
     *
     * @default false
     * @example
     * ```ts
     * sandbox: {
     *   verbose: true
     * }
     * ```
     */
    verbose?: boolean;
    /**
     * Log level for the sandbox server.
     *
     * Controls the verbosity of sandbox server logs:
     * - `'debug'`: Very detailed logs (all operations)
     * - `'info'`: Standard operational logs
     * - `'warn'`: Warnings only
     * - `'error'`: Errors only
     *
     * @default 'info'
     * @example
     * ```ts
     * sandbox: {
     *   logLevel: 'debug' // Show all debug info
     * }
     * ```
     */
    logLevel?: 'debug' | 'info' | 'warn' | 'error';
    /**
     * Recreate the sandbox database on each server start.
     *
     * When `true`, the database is dropped and recreated with seed data
     * every time the dev server starts. Useful for ensuring a clean state
     * during development.
     *
     * **Warning**: All existing data will be lost on each restart.
     *
     * @default false
     * @example
     * ```ts
     * sandbox: {
     *   recreateDb: true // Fresh database on every restart
     * }
     * ```
     */
    recreateDb?: boolean;
    /**
     * Seed the database with demo data on startup.
     *
     * Creates demo users, games, achievements, and other platform data
     * for testing. Disable if you want to start with an empty database.
     *
     * @default true
     * @example
     * ```ts
     * sandbox: {
     *   seed: false // Start with empty database
     * }
     * ```
     */
    seed?: boolean;
    /**
     * Use an in-memory database instead of a file.
     *
     * The database only exists in RAM and is lost when the server stops.
     * Faster but non-persistent. Useful for testing and CI environments.
     *
     * @default false
     * @example
     * ```ts
     * sandbox: {
     *   memoryOnly: true // Database in RAM only
     * }
     * ```
     */
    memoryOnly?: boolean;
    /**
     * Custom path for the database file.
     *
     * Specifies where the SQLite database file should be stored.
     * If not provided, defaults to a path based on node_modules location.
     *
     * Special value `':memory:'` creates an in-memory database
     * (equivalent to `memoryOnly: true`).
     *
     * @example
     * ```ts
     * sandbox: {
     *   databasePath: './my-game-sandbox.db'
     * }
     * ```
     *
     * @example
     * ```ts
     * sandbox: {
     *   databasePath: ':memory:' // In-memory database
     * }
     * ```
     */
    databasePath?: string;
}
/**
 * Timeback integration configuration for local development.
 *
 * By default, all courses from playcademy.config.js are enrolled with mock IDs.
 * Use this to override specific courses or exclude them from enrollment.
 *
 * @example
 * ```ts
 * // Use all defaults (all courses from config with mock IDs)
 * timeback: {}
 *
 * // Override role only (still enrolls all courses with mock IDs)
 * timeback: {
 *   role: 'teacher',
 * }
 *
 * // Override specific course with real ID (others still use mock)
 * timeback: {
 *   courses: {
 *     'FastMath:3': 'real-course-id-g3',
 *   },
 * }
 *
 * // Exclude a course from enrollment (test partial enrollment)
 * timeback: {
 *   courses: {
 *     'FastMath:4': false,  // Not enrolled in grade 4
 *   },
 * }
 *
 * // Full real Timeback integration
 * timeback: {
 *   id: 'real-student-sourced-id',
 *   courses: {
 *     'FastMath:3': 'real-course-id-g3',
 *     'FastMath:4': 'real-course-id-g4',
 *   },
 * }
 * ```
 */
export interface PlaycademyTimebackOptions {
    /**
     * Timeback ID for the test user. Defaults to auto-generated mock ID.
     * Set to a real student sourcedId for testing against real Timeback.
     */
    id?: string;
    /**
     * User role for testing. Defaults to 'student'.
     * Use this to test parent/teacher views of your game.
     */
    role?: 'student' | 'parent' | 'teacher' | 'administrator' | 'guardian';
    /**
     * Organization (school/district) configuration.
     * Defaults to PLAYCADEMY mock organization. All properties are optional -
     * only override what you need.
     */
    organization?: 'mock' | {
        /** Organization sourcedId (defaults to PLAYCADEMY) */
        id?: string;
        /** Organization display name (defaults to 'Playcademy Studios') */
        name?: string;
        /** Organization type (defaults to 'department') */
        type?: 'school' | 'district' | 'department' | 'local' | 'state' | 'national';
    };
    /**
     * Course enrollment overrides. By default, all courses from playcademy.config.js
     * are enrolled with mock IDs.
     *
     * - Omit entirely: Use all courses from config with mock IDs
     * - `'mock'` or omit key: Use mock ID for that course
     * - Real string: Use that course ID
     * - `null` or `false`: Exclude from enrollment
     */
    courses?: Record<string, 'mock' | string | null | false>;
}
/**
 * Configuration options for the development shell wrapper
 *
 * The shell provides the platform UI during development, including the
 * Playcademy badge and iframe wrapper used by `platform` and `demo` modes.
 */
export interface PlaycademyDisplayOptions {
    /**
     * Hide the Playcademy badge in the corner during development.
     *
     * @default false
     * @example
     * ```ts
     * display: {
     *   hideBadge: true // Hide the badge
     * }
     * ```
     */
    hideBadge?: boolean;
}
/**
 * Main configuration options for the Playcademy Vite plugin
 *
 * Configure how your game integrates with the Playcademy platform during
 * development and build.
 *
 * @example
 * ```ts
 * // vite.config.ts
 * import { playcademy } from '@playcademy/vite-plugin'
 *
 * export default defineConfig({
 *   plugins: [
 *     playcademy({
 *       mode: 'platform',
 *       sandbox: {
 *         logLevel: 'debug',
 *         recreateDb: true
 *       },
 *       display: {
 *         hideBadge: true
 *       }
 *     })
 *   ]
 * })
 * ```
 */
export interface PlaycademyPluginOptions {
    /**
     * Path to the playcademy.config.js file.
     *
     * By default, the plugin searches for the config file in the current directory
     * and up to 3 parent directories. Use this option to explicitly specify the
     * config file path when using non-standard project structures.
     *
     * @example
     * ```ts
     * // When running from a client/ subdirectory with config in root
     * {
     *   configPath: '../playcademy.config.js'
     * }
     * ```
     */
    configPath?: string;
    /**
     * Plugin operation mode.
     *
     * - `'platform'`: Full development experience with sandbox server and shell (recommended)
     * - `'demo'`: Sandbox + shell, but initializes the SDK with `mode: 'demo'`
     * - `'standalone'`: Backend bundling only, no platform features
     *
     * Most games should use `'platform'` mode; use `'demo'` to exercise
     * anonymous/demo-specific SDK flows during local development.
     *
     * @default 'platform'
     * @example
     * ```ts
     * {
     *   mode: 'standalone' // For testing backend in isolation
     * }
     * ```
     */
    mode?: PlaycademyMode;
    /**
     * Export/build configuration options.
     *
     * Controls how your game is packaged for deployment.
     *
     * @example
     * ```ts
     * {
     *   export: {
     *     autoZip: true // Create deployment zip automatically
     *   }
     * }
     * ```
     */
    export?: PlaycademyExportOptions;
    /**
     * Sandbox server configuration options.
     *
     * The sandbox provides a local Playcademy platform environment for development.
     *
     * @example
     * ```ts
     * {
     *   sandbox: {
     *     logLevel: 'debug',
     *     recreateDb: true
     *   }
     * }
     * ```
     */
    sandbox?: PlaycademySandboxOptions;
    /**
     * Display configuration options.
     *
     * Control visual elements during development.
     *
     * @example
     * ```ts
     * {
     *   display: {
     *     hideBadge: true
     *   }
     * }
     * ```
     */
    display?: PlaycademyDisplayOptions;
    /**
     * Timeback integration configuration.
     *
     * Configure mock or real Timeback enrollments for local development.
     * Timeback `id` is auto-generated for mock testing.
     *
     * @example
     * ```ts
     * timeback: {
     *   courses: {
     *     'FastMath:3': 'mock',
     *     'FastMath:4': 'mock',
     *   },
     * }
     * ```
     *
     * Set to `false` to explicitly disable Timeback even if configured in playcademy.config.
     */
    timeback?: PlaycademyTimebackOptions | false;
}
