@playcademy/sdk 0.5.0 → 0.6.0-beta.1

package/dist/types.d.ts

@@ -487,6 +487,23 @@ interface UserInfo {
 interface DeveloperStatusResponse {
     status: DeveloperStatusEnumType;
 }
+interface DemoProfile {
+    displayName: string;
+    isDefault: boolean;
+}
+/**
+ * Update shape for `client.demo.profile.update(...)`.
+ *
+ * Kept as a named type so callers typed against it pick up new fields
+ * automatically, but `displayName` is the only updatable field today and
+ * the server's `DemoProfileSchema` requires it — a no-field payload would
+ * 400 at runtime, so we model that at the type level too. When additional
+ * fields land, make them required/optional individually based on server
+ * validation, rather than blanket-optional.
+ */
+interface DemoProfileUpdate {
+    displayName: string;
+}
 /**
  * Authenticated user for API responses.
  * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
@@ -893,6 +910,23 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        isAnonymous: drizzle_orm_pg_core.PgColumn<{
+            name: "is_anonymous";
+            tableName: "user";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         timebackId: drizzle_orm_pg_core.PgColumn<{
             name: "timeback_id";
             tableName: "user";
@@ -4376,6 +4410,197 @@ type SpriteTemplateRow = typeof spriteTemplates.$inferSelect;
 
 type NotificationRow = InferSelectModel<typeof notifications>;
 
+/**
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
+ */
+
+/**
+ * Base configuration for TimeBack integration (shared across all courses).
+ * References upstream TimeBack types from @playcademy/timeback.
+ *
+ * All fields are optional and support template variables: {grade}, {subject}, {gameSlug}
+ */
+interface TimebackBaseConfig {
+    /** Organization configuration (shared across all courses) */
+    organization?: Partial<OrganizationConfig>;
+    /** Course defaults (can be overridden per-course) */
+    course?: Partial<CourseConfig>;
+    /** Component defaults */
+    component?: Partial<ComponentConfig>;
+    /** Resource defaults */
+    resource?: Partial<ResourceConfig>;
+    /** ComponentResource defaults */
+    componentResource?: Partial<ComponentResourceConfig>;
+}
+/**
+ * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
+ * Used in playcademy.config.* to allow per-course customization.
+ */
+interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
+    title?: string;
+    courseCode?: string;
+    level?: string;
+    metadata?: CourseConfig['metadata'];
+    totalXp?: number | null;
+    masterableUnits?: number | null;
+}
+/**
+ * TimeBack integration configuration for Playcademy config file.
+ *
+ * Supports two levels of customization:
+ * 1. `base`: Shared defaults for all courses (organization, course, component, resource, componentResource)
+ * 2. Per-course overrides in the `courses` array (title, courseCode, level, gradingScheme, metadata)
+ *
+ * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
+ */
+interface TimebackIntegrationConfig {
+    /** Multi-grade course configuration (array of grade/subject/totalXp with optional per-course overrides) */
+    courses: TimebackCourseConfigWithOverrides[];
+    /** Optional base configuration (shared across all courses, can be overridden per-course) */
+    base?: TimebackBaseConfig;
+}
+/**
+ * Custom API routes integration
+ */
+interface CustomRoutesIntegration {
+    /** Directory for custom API routes (defaults to 'server/api') */
+    directory?: string;
+}
+/**
+ * Database integration
+ */
+interface DatabaseIntegration {
+    /** Database directory (defaults to 'db') */
+    directory?: string;
+    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
+     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
+    strategy?: 'push' | 'migrate';
+}
+interface QueueConfig {
+    maxBatchSize?: number;
+    maxRetries?: number;
+    maxBatchTimeout?: number;
+    maxConcurrency?: number;
+    retryDelay?: number;
+    deadLetterQueue?: string;
+}
+/**
+ * Integrations configuration
+ * All backend features (database, custom routes, external services) are configured here
+ */
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig | null;
+    /** Custom API routes (optional) */
+    customRoutes?: CustomRoutesIntegration | boolean;
+    /** Database (optional) */
+    database?: DatabaseIntegration | boolean;
+    /** Key-Value storage (optional) */
+    kv?: boolean;
+    /** Bucket storage (optional) */
+    bucket?: boolean;
+    /** Authentication (optional) */
+    auth?: boolean;
+    /** Queues (optional) */
+    queues?: Record<string, QueueConfig | boolean>;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Integrations (database, custom routes, external services) */
+    integrations?: IntegrationsConfig;
+}
+
+/**
+ * Configuration options for initializing a PlaycademyClient instance.
+ *
+ * @example
+ * ```typescript
+ * const config: PlaycademyServerClientConfig = {
+ *   apiKey: process.env.PLAYCADEMY_API_KEY!,
+ *   gameId: 'my-math-game',
+ *   configPath: './playcademy.config.js'
+ * }
+ * ```
+ */
+interface PlaycademyServerClientConfig {
+    /**
+     * Playcademy API key for server-to-server authentication.
+     * Obtain from the Playcademy developer dashboard.
+     */
+    apiKey: string;
+    /**
+     * Optional path to playcademy.config.js file.
+     * If not provided, searches current directory and up to 3 parent directories.
+     * Ignored if `config` is provided directly.
+     *
+     * @example './config/playcademy.config.js'
+     */
+    configPath?: string;
+    /**
+     * Optional config object (for edge environments without filesystem).
+     * If provided, skips filesystem-based config loading.
+     *
+     * @example { name: 'My Game', integrations: { timeback: {...} } }
+     */
+    config?: PlaycademyConfig;
+    /**
+     * Optional base URL for Playcademy API.
+     * Defaults to environment variables or 'https://hub.playcademy.net'.
+     *
+     * @example 'http://localhost:3000' for local development
+     */
+    baseUrl?: string;
+    /**
+     * Optional game ID.
+     * If not provided, will attempt to fetch from API using the API token.
+     *
+     * @example 'my-math-game'
+     */
+    gameId?: string;
+}
+/**
+ * Internal state maintained by the PlaycademyClient instance.
+ *
+ * @internal
+ */
+interface PlaycademyServerClientState {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API requests */
+    baseUrl: string;
+    /** Game identifier */
+    gameId: string;
+    /** Loaded game configuration from playcademy.config.js */
+    config: PlaycademyConfig;
+    /**
+     * TimeBack course ID fetched from the Playcademy API.
+     * Used for all TimeBack event recording.
+     */
+    courseId?: string;
+}
+
 /**
  * Connection monitoring types
  *
@@ -4565,218 +4790,29 @@ declare class ConnectionManager {
 }
 
 /**
- * @fileoverview Authentication Strategy Pattern
+ * @fileoverview Playcademy Messaging System
  *
- * Provides different authentication strategies for the Playcademy SDK.
- * Each strategy knows how to add its authentication headers to requests.
- */
-
-/**
- * Base interface for authentication strategies
+ * This file implements a unified messaging system for the Playcademy platform that handles
+ * communication between different contexts:
+ *
+ * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
+ *    they need to communicate with the parent window using postMessage API
+ *
+ * 2. **Local Communication**: When games run in the same context (local development),
+ *    they use CustomEvents for internal messaging
+ *
+ * The system automatically detects the runtime environment and chooses the appropriate
+ * transport method, abstracting this complexity from the developer.
+ *
+ * **Architecture Overview**:
+ * - Games run in iframes for security and isolation
+ * - Parent window (Playcademy shell) manages game lifecycle
+ * - Messages flow bidirectionally between parent and iframe
+ * - Local development mode simulates this architecture without iframes
  */
-interface AuthStrategy {
-    /** Get the token value */
-    getToken(): string | null;
-    /** Get the token type */
-    getType(): TokenType;
-    /** Get authentication headers for a request */
-    getHeaders(): Record<string, string>;
-}
 
 /**
- * Base Playcademy SDK client with shared infrastructure.
- * Provides authentication, HTTP requests, events, connection monitoring,
- * and fundamental namespaces used by all clients.
- *
- * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
- */
-declare abstract class PlaycademyBaseClient {
-    baseUrl: string;
-    gameUrl?: string;
-    protected authStrategy: AuthStrategy;
-    protected gameId?: string;
-    protected config: Partial<ClientConfig>;
-    protected listeners: EventListeners;
-    protected internalClientSessionId?: string;
-    protected authContext?: {
-        isInIframe: boolean;
-    };
-    protected initPayload?: InitPayload;
-    protected connectionManager?: ConnectionManager;
-    protected launchId?: string;
-    /**
-     * Internal session manager for automatic session lifecycle.
-     * @private
-     * @internal
-     */
-    protected _sessionManager: {
-        startSession: (gameId: string) => Promise<{
-            sessionId: string;
-        }>;
-        endSession: (sessionId: string, gameId: string) => Promise<void>;
-    };
-    constructor(config?: Partial<ClientConfig>);
-    /**
-     * Gets the effective base URL for API requests.
-     */
-    getBaseUrl(): string;
-    /**
-     * Gets the effective game backend URL for integration requests.
-     */
-    protected getGameBackendUrl(): string;
-    /**
-     * Simple ping method for testing connectivity.
-     */
-    ping(): string;
-    /**
-     * Sets the authentication token for API requests.
-     */
-    setToken(token: string | null, tokenType?: TokenType): void;
-    setLaunchId(launchId: string | null | undefined): void;
-    /**
-     * Gets the current token type.
-     */
-    getTokenType(): TokenType;
-    /**
-     * Gets the current authentication token.
-     */
-    getToken(): string | null;
-    /**
-     * Checks if the client has a valid API token.
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Registers a callback to be called when authentication state changes.
-     */
-    onAuthChange(callback: (token: string | null) => void): void;
-    /**
-     * Registers a callback to be called when connection issues are detected.
-     */
-    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
-    /**
-     * Gets the current connection state.
-     */
-    getConnectionState(): ConnectionState | 'unknown';
-    /**
-     * Manually triggers a connection check immediately.
-     */
-    checkConnection(): Promise<ConnectionState | 'unknown'>;
-    /**
-     * Sets the authentication context for the client.
-     * @internal
-     */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
-    /**
-     * Registers an event listener for client events.
-     */
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
-    /**
-     * Emits an event to all registered listeners.
-     */
-    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
-    /**
-     * Makes an authenticated HTTP request to the platform API.
-     */
-    protected request<T>(path: string, method: Method, options?: {
-        body?: unknown;
-        headers?: Record<string, string>;
-        raw?: boolean;
-        retryPolicy?: RetryPolicy;
-    }): Promise<T>;
-    /**
-     * Makes an authenticated HTTP request to the game's backend Worker.
-     */
-    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, options?: {
-        raw?: boolean;
-        retryPolicy?: RetryPolicy;
-    }): Promise<T>;
-    /**
-     * Ensures a gameId is available, throwing an error if not.
-     */
-    protected _ensureGameId(): string;
-    /**
-     * Detects and sets the authentication context (iframe vs standalone).
-     */
-    private _detectAuthContext;
-    /**
-     * Initializes connection monitoring if enabled.
-     */
-    private _initializeConnectionMonitor;
-    private _initializeInternalSession;
-    /**
-     * Current user data and inventory management.
-     * - `me()` - Get authenticated user profile
-     * - `inventory.get()` - List user's items
-     * - `inventory.add(slug, qty)` - Award items to user
-     */
-    users: {
-        me: () => Promise<AuthenticatedUser>;
-        inventory: {
-            get: () => Promise<InventoryItemWithItem[]>;
-            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            quantity: (identifier: string) => Promise<number>;
-            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-        };
-    };
-}
-
-/**
- * Options for configuring activity tracking behavior.
- */
-interface StartActivityOptions {
-    /**
-     * How long the tab can stay hidden before the timing window resets on return.
-     * Defaults to 10 minutes. Set to `Infinity` to disable.
-     */
-    hiddenTimeoutMs?: number;
-    /**
-     * How often to flush periodic heartbeats with accumulated time data.
-     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
-     * final unload/endActivity flushes still run.
-     */
-    heartbeatIntervalMs?: number;
-    /**
-     * Stable identifier for this activity run. When provided, it is used on
-     * every heartbeat and on endActivity instead of a freshly-generated UUID.
-     *
-     * Pass the same `runId` across multiple `startActivity()` calls (for
-     * example, after the player closes and reopens a resumable activity) so
-     * downstream systems can correlate related sessions into a single run.
-     *
-     * Must be a UUID (the backend validates it as such) and unique per
-     * logical run. If omitted, the SDK generates a new UUID on each call,
-     * which means every session is treated as its own run.
-     */
-    runId?: string;
-}
-
-/**
- * @fileoverview Playcademy Messaging System
- *
- * This file implements a unified messaging system for the Playcademy platform that handles
- * communication between different contexts:
- *
- * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
- *    they need to communicate with the parent window using postMessage API
- *
- * 2. **Local Communication**: When games run in the same context (local development),
- *    they use CustomEvents for internal messaging
- *
- * The system automatically detects the runtime environment and chooses the appropriate
- * transport method, abstracting this complexity from the developer.
- *
- * **Architecture Overview**:
- * - Games run in iframes for security and isolation
- * - Parent window (Playcademy shell) manages game lifecycle
- * - Messages flow bidirectionally between parent and iframe
- * - Local development mode simulates this architecture without iframes
- */
-
-/**
- * Enumeration of all message types used in the Playcademy messaging system.
+ * Enumeration of all message types used in the Playcademy messaging system.
  *
  * **Message Flow Patterns**:
  *
@@ -4879,6 +4915,15 @@ declare enum MessageEvents {
      * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
      */
     DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
+    /**
+     * Game signals that demo mode has ended.
+     * Sent when a demo experience reaches its CTA/upgrade boundary.
+     * Payload:
+     * - `score?`: number
+     * - `durationMs?`: number
+     * - `metadata?`: `Record<string, unknown>`
+     */
+    DEMO_END = "PLAYCADEMY_DEMO_END",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -4962,7 +5007,197 @@ declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(thi
  * }
  * ```
  */
-declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+
+/**
+ * @fileoverview Authentication Strategy Pattern
+ *
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
+ */
+
+/**
+ * Base interface for authentication strategies
+ */
+interface AuthStrategy {
+    /** Get the token value */
+    getToken(): string | null;
+    /** Get the token type */
+    getType(): TokenType;
+    /** Get authentication headers for a request */
+    getHeaders(): Record<string, string>;
+}
+
+/**
+ * Base Playcademy SDK client with shared infrastructure.
+ * Provides authentication, HTTP requests, events, connection monitoring,
+ * and fundamental namespaces used by all clients.
+ *
+ * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
+ */
+declare abstract class PlaycademyBaseClient {
+    baseUrl: string;
+    gameUrl?: string;
+    mode: PlaycademyMode;
+    protected authStrategy: AuthStrategy;
+    protected gameId?: string;
+    protected config: Partial<ClientConfig>;
+    protected listeners: EventListeners;
+    protected internalClientSessionId?: string;
+    protected authContext?: {
+        isInIframe: boolean;
+    };
+    protected initPayload?: InitPayload;
+    protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
+    /**
+     * Internal session manager for automatic session lifecycle.
+     * @private
+     * @internal
+     */
+    protected _sessionManager: {
+        startSession: (gameId: string) => Promise<{
+            sessionId: string;
+        }>;
+        endSession: (sessionId: string, gameId: string) => Promise<void>;
+    };
+    constructor(config?: Partial<ClientConfig>);
+    /**
+     * Gets the effective base URL for API requests.
+     */
+    getBaseUrl(): string;
+    /**
+     * Gets the effective game backend URL for integration requests.
+     */
+    protected getGameBackendUrl(): string;
+    /**
+     * Simple ping method for testing connectivity.
+     */
+    ping(): string;
+    /**
+     * Sets the authentication token for API requests.
+     */
+    setToken(token: string | null, tokenType?: TokenType): void;
+    setLaunchId(launchId: string | null | undefined): void;
+    /**
+     * Gets the current token type.
+     */
+    getTokenType(): TokenType;
+    /**
+     * Gets the current authentication token.
+     */
+    getToken(): string | null;
+    /**
+     * Checks if the client has a valid API token.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Registers a callback to be called when authentication state changes.
+     */
+    onAuthChange(callback: (token: string | null) => void): void;
+    /**
+     * Registers a callback to be called when connection issues are detected.
+     */
+    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    /**
+     * Gets the current connection state.
+     */
+    getConnectionState(): ConnectionState | 'unknown';
+    /**
+     * Manually triggers a connection check immediately.
+     */
+    checkConnection(): Promise<ConnectionState | 'unknown'>;
+    /**
+     * Sets the authentication context for the client.
+     * @internal
+     */
+    _setAuthContext(context: {
+        isInIframe: boolean;
+    }): void;
+    /**
+     * Registers an event listener for client events.
+     */
+    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
+    /**
+     * Emits an event to all registered listeners.
+     */
+    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
+    /**
+     * Makes an authenticated HTTP request to the platform API.
+     */
+    protected request<T>(path: string, method: Method, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        raw?: boolean;
+        retryPolicy?: RetryPolicy;
+    }): Promise<T>;
+    /**
+     * Makes an authenticated HTTP request to the game's backend Worker.
+     */
+    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, options?: {
+        raw?: boolean;
+        retryPolicy?: RetryPolicy;
+    }): Promise<T>;
+    /**
+     * Ensures a gameId is available, throwing an error if not.
+     */
+    protected _ensureGameId(): string;
+    /**
+     * Detects and sets the authentication context (iframe vs standalone).
+     */
+    private _detectAuthContext;
+    /**
+     * Initializes connection monitoring if enabled.
+     */
+    private _initializeConnectionMonitor;
+    private _initializeInternalSession;
+    /**
+     * Current user data and inventory management.
+     * - `me()` - Get authenticated user profile
+     * - `inventory.get()` - List user's items
+     * - `inventory.add(slug, qty)` - Award items to user
+     */
+    users: {
+        me: () => Promise<AuthenticatedUser>;
+        inventory: {
+            get: () => Promise<InventoryItemWithItem[]>;
+            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+            quantity: (identifier: string) => Promise<number>;
+            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
+        };
+    };
+}
+
+/**
+ * Options for configuring activity tracking behavior.
+ */
+interface StartActivityOptions {
+    /**
+     * How long the tab can stay hidden before the timing window resets on return.
+     * Defaults to 10 minutes. Set to `Infinity` to disable.
+     */
+    hiddenTimeoutMs?: number;
+    /**
+     * How often to flush periodic heartbeats with accumulated time data.
+     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
+     * final unload/endActivity flushes still run.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Stable identifier for this activity run. When provided, it is used on
+     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     *
+     * Pass the same `runId` across multiple `startActivity()` calls (for
+     * example, after the player closes and reopens a resumable activity) so
+     * downstream systems can correlate related sessions into a single run.
+     *
+     * Must be a UUID (the backend validates it as such) and unique per
+     * logical run. If omitted, the SDK generates a new UUID on each call,
+     * which means every session is treated as its own run.
+     */
+    runId?: string;
+}
 
 /**
  * Playcademy SDK client for game developers.
@@ -5053,10 +5288,31 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
     };
     /**
      * Game score submission and leaderboards.
-     * - `submit(gameId, score, metadata?)` - Record a game score
+     * - `submit(score, metadata?)` - Record a game score
      */
     scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
+        submit: (score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
+    };
+    /**
+     * Read-only leaderboard access for the current game scope.
+     * - `fetch(options?)` - Fetch leaderboard entries
+     */
+    leaderboard: {
+        fetch: (options?: LeaderboardOptions | undefined) => Promise<GameLeaderboardEntry[]>;
+    };
+    /**
+     * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
+     * so callers should gate on the mode before reaching in.
+     * - `profile.get()` - Read the anonymous demo player's profile
+     * - `profile.update(updates)` - Update the demo player's profile (today: the required `displayName`)
+     * - `end(score, options?)` - Signal to the parent shell that the demo has ended
+     */
+    demo: {
+        profile: {
+            get: () => Promise<DemoProfile>;
+            update: (updates: DemoProfileUpdate) => Promise<DemoProfile>;
+        };
+        end: (score: number, options?: DemoEndOptions | undefined) => void;
     };
     /**
      * Realtime multiplayer authentication.
@@ -5232,6 +5488,20 @@ interface XpResponse {
  */
 
 type TokenType = 'session' | 'apiKey' | 'gameJwt';
+/**
+ * Runtime mode for a Playcademy game client.
+ *
+ * - `'platform'` — game is embedded in the platform (e.g. the cademy hub)
+ *   with a real authenticated user and full access to SDK namespaces.
+ * - `'demo'` — game is embedded in the landing page demo shell with an
+ *   anonymous user; platform-only namespaces throw, and `client.demo.*`
+ *   is the supported surface for signaling demo lifecycle events and
+ *   reading/updating the anonymous profile.
+ * - `'standalone'` — game is running outside any iframe (e.g. `bun run dev`
+ *   or direct-deploy preview) with a mock token and no real platform
+ *   context. API calls will not succeed; use this to branch UX locally.
+ */
+type PlaycademyMode = 'platform' | 'demo' | 'standalone';
 interface ClientConfig {
     baseUrl: string;
     gameUrl?: string;
@@ -5242,6 +5512,7 @@ interface ClientConfig {
     autoStartSession?: boolean;
     onDisconnect?: DisconnectHandler;
     enableConnectionMonitoring?: boolean;
+    mode?: PlaycademyMode;
 }
 /**
  * Handler called when connection state changes to offline or degraded.
@@ -5277,6 +5548,8 @@ interface InitPayload {
     realtimeUrl?: string;
     /** Timeback context (if user has a Timeback account) */
     timeback?: TimebackInitContext;
+    /** Runtime mode for the game client */
+    mode?: PlaycademyMode;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -5305,6 +5578,7 @@ interface GameContextPayload {
     realtimeUrl: string;
     gameId: string;
     forwardKeys?: string[];
+    mode?: PlaycademyMode;
 }
 type EventListeners = {
     [E in keyof ClientEvents]?: ((payload: ClientEvents[E]) => void)[];
@@ -5427,6 +5701,26 @@ interface ConnectionStatePayload {
     state: 'online' | 'offline' | 'degraded';
     reason: string;
 }
+/**
+ * Options for `client.demo.end(score, options?)`.
+ *
+ * All optional. The landing-page demo shell can render a meaningful CTA
+ * from `score` alone, but `durationMs` enables a nicer summary and
+ * `metadata` lets games pass any extra context they want to surface.
+ */
+interface DemoEndOptions {
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Wire payload for the `PLAYCADEMY_DEMO_END` message.
+ *
+ * `score` is required — the demo shell always needs something to display
+ * when the round ends. `durationMs` and `metadata` are optional.
+ */
+interface DemoEndPayload extends DemoEndOptions {
+    score: number;
+}
 
 /**
  * SDK-specific API response types
@@ -5685,196 +5979,5 @@ interface XpSummaryResponse {
     total: TotalXpResponse;
 }
 
-/**
- * @fileoverview Server SDK Type Definitions
- *
- * TypeScript type definitions for the server-side Playcademy SDK.
- * Includes configuration types, client state, and re-exported TimeBack types.
- */
-
-/**
- * Base configuration for TimeBack integration (shared across all courses).
- * References upstream TimeBack types from @playcademy/timeback.
- *
- * All fields are optional and support template variables: {grade}, {subject}, {gameSlug}
- */
-interface TimebackBaseConfig {
-    /** Organization configuration (shared across all courses) */
-    organization?: Partial<OrganizationConfig>;
-    /** Course defaults (can be overridden per-course) */
-    course?: Partial<CourseConfig>;
-    /** Component defaults */
-    component?: Partial<ComponentConfig>;
-    /** Resource defaults */
-    resource?: Partial<ResourceConfig>;
-    /** ComponentResource defaults */
-    componentResource?: Partial<ComponentResourceConfig>;
-}
-/**
- * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
- * Used in playcademy.config.* to allow per-course customization.
- */
-interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
-    title?: string;
-    courseCode?: string;
-    level?: string;
-    metadata?: CourseConfig['metadata'];
-    totalXp?: number | null;
-    masterableUnits?: number | null;
-}
-/**
- * TimeBack integration configuration for Playcademy config file.
- *
- * Supports two levels of customization:
- * 1. `base`: Shared defaults for all courses (organization, course, component, resource, componentResource)
- * 2. Per-course overrides in the `courses` array (title, courseCode, level, gradingScheme, metadata)
- *
- * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
- */
-interface TimebackIntegrationConfig {
-    /** Multi-grade course configuration (array of grade/subject/totalXp with optional per-course overrides) */
-    courses: TimebackCourseConfigWithOverrides[];
-    /** Optional base configuration (shared across all courses, can be overridden per-course) */
-    base?: TimebackBaseConfig;
-}
-/**
- * Custom API routes integration
- */
-interface CustomRoutesIntegration {
-    /** Directory for custom API routes (defaults to 'server/api') */
-    directory?: string;
-}
-/**
- * Database integration
- */
-interface DatabaseIntegration {
-    /** Database directory (defaults to 'db') */
-    directory?: string;
-    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
-     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
-    strategy?: 'push' | 'migrate';
-}
-interface QueueConfig {
-    maxBatchSize?: number;
-    maxRetries?: number;
-    maxBatchTimeout?: number;
-    maxConcurrency?: number;
-    retryDelay?: number;
-    deadLetterQueue?: string;
-}
-/**
- * Integrations configuration
- * All backend features (database, custom routes, external services) are configured here
- */
-interface IntegrationsConfig {
-    /** TimeBack integration (optional) */
-    timeback?: TimebackIntegrationConfig | null;
-    /** Custom API routes (optional) */
-    customRoutes?: CustomRoutesIntegration | boolean;
-    /** Database (optional) */
-    database?: DatabaseIntegration | boolean;
-    /** Key-Value storage (optional) */
-    kv?: boolean;
-    /** Bucket storage (optional) */
-    bucket?: boolean;
-    /** Authentication (optional) */
-    auth?: boolean;
-    /** Queues (optional) */
-    queues?: Record<string, QueueConfig | boolean>;
-}
-/**
- * Unified Playcademy configuration
- * Used for playcademy.config.{js,json}
- */
-interface PlaycademyConfig {
-    /** Game name */
-    name: string;
-    /** Game description */
-    description?: string;
-    /** Game emoji icon */
-    emoji?: string;
-    /** Build command to run before deployment */
-    buildCommand?: string[];
-    /** Path to build output */
-    buildPath?: string;
-    /** Game type */
-    gameType?: 'hosted' | 'external';
-    /** External URL (for external games) */
-    externalUrl?: string;
-    /** Game platform */
-    platform?: 'web' | 'unity' | 'godot';
-    /** Integrations (database, custom routes, external services) */
-    integrations?: IntegrationsConfig;
-}
-
-/**
- * Configuration options for initializing a PlaycademyClient instance.
- *
- * @example
- * ```typescript
- * const config: PlaycademyServerClientConfig = {
- *   apiKey: process.env.PLAYCADEMY_API_KEY!,
- *   gameId: 'my-math-game',
- *   configPath: './playcademy.config.js'
- * }
- * ```
- */
-interface PlaycademyServerClientConfig {
-    /**
-     * Playcademy API key for server-to-server authentication.
-     * Obtain from the Playcademy developer dashboard.
-     */
-    apiKey: string;
-    /**
-     * Optional path to playcademy.config.js file.
-     * If not provided, searches current directory and up to 3 parent directories.
-     * Ignored if `config` is provided directly.
-     *
-     * @example './config/playcademy.config.js'
-     */
-    configPath?: string;
-    /**
-     * Optional config object (for edge environments without filesystem).
-     * If provided, skips filesystem-based config loading.
-     *
-     * @example { name: 'My Game', integrations: { timeback: {...} } }
-     */
-    config?: PlaycademyConfig;
-    /**
-     * Optional base URL for Playcademy API.
-     * Defaults to environment variables or 'https://hub.playcademy.net'.
-     *
-     * @example 'http://localhost:3000' for local development
-     */
-    baseUrl?: string;
-    /**
-     * Optional game ID.
-     * If not provided, will attempt to fetch from API using the API token.
-     *
-     * @example 'my-math-game'
-     */
-    gameId?: string;
-}
-/**
- * Internal state maintained by the PlaycademyClient instance.
- *
- * @internal
- */
-interface PlaycademyServerClientState {
-    /** API key for authentication */
-    apiKey: string;
-    /** Base URL for API requests */
-    baseUrl: string;
-    /** Game identifier */
-    gameId: string;
-    /** Loaded game configuration from playcademy.config.js */
-    config: PlaycademyConfig;
-    /**
-     * TimeBack course ID fetched from the Playcademy API.
-     * Used for all TimeBack event recording.
-     */
-    courseId?: string;
-}
-
 export { AchievementCompletionType, NotificationStatus, NotificationType, PlaycademyClient };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };