@playcademy/sandbox 0.1.9 → 0.1.11

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Configuration Type Definitions
+ */
+type TimebackMode = 'local' | 'remote' | 'disabled';
+interface TimebackConfig {
+    mode: TimebackMode;
+    onerosterApiUrl?: string;
+    caliperApiUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    authUrl?: string;
+    courseId?: string;
+    studentId?: string;
+}
+interface AuthConfig {
+    betterAuthSecret: string;
+    gameJwtSecret: string;
+}
+interface SandboxConfig {
+    embedded: boolean;
+    auth: AuthConfig;
+    timeback: TimebackConfig;
+}
+
+/**
+ * Configuration Mutation Functions
+ */
+declare function setEmbeddedMode(embedded: boolean): void;
+
+/**
+ * TimeBack Configuration Helpers
+ */
+
+declare function isTimebackEnabled(): boolean;
+declare function hasTimebackCredentials(): boolean;
+declare function hasTimebackFullConfig(): boolean;
+declare function requireTimebackCredentials(): TimebackConfig;
+declare function configureTimeback(options: Partial<TimebackConfig>): void;
+
+declare const config: SandboxConfig;
+
+export { config, configureTimeback, hasTimebackCredentials, hasTimebackFullConfig, isTimebackEnabled, requireTimebackCredentials, setEmbeddedMode };
+export type { AuthConfig, SandboxConfig, TimebackConfig, TimebackMode };

package/dist/server.d.ts

@@ -1,7 +1,290 @@
-import type { ProjectInfo, ServerOptions } from './types';
-export declare function startServer(port: number, project?: ProjectInfo, options?: Omit<ServerOptions, 'port' | 'project'>): Promise<{
-    main: import("@hono/node-server").ServerType;
-    realtime: Bun.Server<import("@playcademy/realtime/server").WebSocketData> | import("@playcademy/realtime/server/sandbox").SandboxRealtimeServer | null;
+import * as _playcademy_realtime_server_sandbox from '@playcademy/realtime/server/sandbox';
+import * as _playcademy_realtime_server from '@playcademy/realtime/server';
+import * as _hono_node_server from '@hono/node-server';
+
+/**
+ * Configuration Type Definitions
+ */
+type TimebackMode = 'local' | 'remote' | 'disabled';
+interface TimebackConfig {
+    mode: TimebackMode;
+    onerosterApiUrl?: string;
+    caliperApiUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    authUrl?: string;
+    courseId?: string;
+    studentId?: string;
+}
+
+/**
+ * Project information types
+ */
+/**
+ * Information about the current game project
+ * Used for seeding and display
+ */
+interface ProjectInfo {
+    slug: string;
+    displayName: string;
+    version: string;
+    description?: string;
+}
+
+/**
+ * Server configuration types
+ */
+
+/**
+ * Logger interface for embedding the sandbox in other tools (e.g., Vite plugin)
+ *
+ * Allows external tools to capture and display sandbox logs in their own format.
+ */
+interface PluginLogger {
+    /** Log informational messages */
+    info: (msg: string) => void;
+    /** Log warning messages */
+    warn: (msg: string) => void;
+    /** Log error messages */
+    error: (msg: string) => void;
+}
+/**
+ * Configuration options for starting the Playcademy sandbox server
+ *
+ * The sandbox provides a local development environment that simulates the
+ * Playcademy platform, including API endpoints, authentication, and database.
+ *
+ * @example
+ * ```ts
+ * import { startServer } from '@playcademy/sandbox'
+ *
+ * await startServer({
+ *   port: 8788,
+ *   seed: true,
+ *   logLevel: 'debug'
+ * })
+ * ```
+ */
+interface ServerOptions {
+    /**
+     * Port number for the sandbox server.
+     *
+     * The sandbox will listen on this port for HTTP requests.
+     *
+     * @example
+     * ```ts
+     * {
+     *   port: 8788
+     * }
+     * ```
+     */
+    port: number;
+    /**
+     * Project information for context.
+     *
+     * Provides metadata about the game being developed. Usually provided
+     * automatically by the Vite plugin.
+     */
+    project?: ProjectInfo;
+    /**
+     * Enable verbose logging.
+     *
+     * Shows detailed information about all operations. Equivalent to
+     * setting `logLevel: 'debug'`.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * {
+     *   verbose: true // Show all debug output
+     * }
+     * ```
+     */
+    verbose?: boolean;
+    /**
+     * Run in quiet mode (minimal logging).
+     *
+     * Suppresses most log output except errors. Useful when embedding
+     * the sandbox in other tools.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * {
+     *   quiet: true // Suppress most logs
+     * }
+     * ```
+     */
+    quiet?: boolean;
+    /**
+     * Seed the database with demo data on startup.
+     *
+     * Creates demo users, games, achievements, and other platform data
+     * for testing. Recommended for development.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * {
+     *   seed: false // Don't seed demo data
+     * }
+     * ```
+     */
+    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.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * {
+     *   memoryOnly: true // Database in RAM only
+     * }
+     * ```
+     */
+    memoryOnly?: boolean;
+    /**
+     * Recreate the database on each server start.
+     *
+     * Drops and recreates the database with fresh seed data every time
+     * the server starts. Ensures a clean state for development.
+     *
+     * **Warning**: All existing data will be lost on each restart.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * {
+     *   recreateDb: true // Fresh database every restart
+     * }
+     * ```
+     */
+    recreateDb?: 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
+     * {
+     *   databasePath: './my-sandbox.db'
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * {
+     *   databasePath: ':memory:' // In-memory database
+     * }
+     * ```
+     */
+    databasePath?: string;
+    /**
+     * Log level for the sandbox server.
+     *
+     * Controls the verbosity of server logs:
+     * - `'debug'`: Very detailed logs (all operations)
+     * - `'info'`: Standard operational logs (default)
+     * - `'warn'`: Warnings only
+     * - `'error'`: Errors only
+     *
+     * @default 'info'
+     * @example
+     * ```ts
+     * {
+     *   logLevel: 'debug' // Show all debug information
+     * }
+     * ```
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    /**
+     * Realtime/WebSocket server configuration.
+     *
+     * The realtime server provides WebSocket support for live updates,
+     * multiplayer features, and other real-time functionality.
+     *
+     * @example
+     * ```ts
+     * {
+     *   realtime: {
+     *     enabled: true,
+     *     port: 8789 // Run WebSocket server on port 8789
+     *   }
+     * }
+     * ```
+     */
+    realtime?: {
+        /**
+         * Enable the realtime/WebSocket server.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Port for the WebSocket server.
+         *
+         * By default, uses the HTTP port + 1 (e.g., if HTTP is 8788,
+         * WebSocket will be 8789).
+         */
+        port?: number;
+    };
+    /**
+     * Timeback (time travel) integration configuration.
+     *
+     * Timeback allows you to simulate time-based game mechanics during
+     * development (e.g., daily rewards, energy refills).
+     *
+     * @example
+     * ```ts
+     * {
+     *   timeback: {
+     *     enabled: true,
+     *     port: 3210
+     *   }
+     * }
+     * ```
+     */
+    timeback?: Partial<TimebackConfig>;
+    /**
+     * Custom logger for capturing sandbox output.
+     *
+     * Allows external tools (like the Vite plugin) to capture and display
+     * sandbox logs in their own format. If not provided, logs go to console.
+     *
+     * @example
+     * ```ts
+     * {
+     *   logger: {
+     *     info: (msg) => console.log('[SANDBOX]', msg),
+     *     warn: (msg) => console.warn('[SANDBOX]', msg),
+     *     error: (msg) => console.error('[SANDBOX]', msg)
+     *   }
+     * }
+     * ```
+     */
+    logger?: PluginLogger;
+}
+
+declare const version: string;
+/**
+ * Start the sandbox server
+ *
+ * @param port - Port to listen on
+ * @param project - Optional project information for seeding
+ * @param options - Server configuration options
+ * @returns Server instance with stop method
+ */
+declare function startServer(port: number, project?: ProjectInfo, options?: Omit<ServerOptions, 'port' | 'project'>): Promise<{
+    main: _hono_node_server.ServerType;
+    realtime: Bun.Server<_playcademy_realtime_server.WebSocketData> | _playcademy_realtime_server_sandbox.SandboxRealtimeServer | null;
     stop: () => void;
 }>;
-export declare const version: string;
+
+export { startServer, version };