@playcademy/sdk 0.2.1 → 0.2.2

package/dist/internal.d.ts

@@ -1,531 +1,246 @@
 import * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import { CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
-import * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
+import { SchemaInfo } from '@playcademy/cloudflare';
 import { InferSelectModel } from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as drizzle_zod from 'drizzle-zod';
 import { z } from 'zod';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
-import { SchemaInfo } from '@playcademy/cloudflare';
 
-/**
- * Cache configuration types for runtime customization
- */
-/**
- * Runtime configuration for TTL cache behavior
- */
-interface TTLCacheConfig {
-    /** Time-to-live in milliseconds. Set to 0 to disable caching for this call. */
-    ttl?: number;
-    /** Force refresh, bypassing cache */
-    force?: boolean;
-    /** Skip cache and fetch fresh data (alias for force) */
-    skipCache?: boolean;
-}
-/**
- * Runtime configuration for cooldown cache behavior
- */
-interface CooldownCacheConfig {
-    /** Cooldown period in milliseconds. Set to 0 to disable cooldown for this call. */
-    cooldown?: number;
-    /** Force refresh, bypassing cooldown */
-    force?: boolean;
-}
+declare const userRoleEnum: drizzle_orm_pg_core.PgEnum<["admin", "player", "developer"]>;
+declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "user";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: drizzle_orm_pg_core.PgColumn<{
+            name: "name";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        username: drizzle_orm_pg_core.PgColumn<{
+            name: "username";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        email: drizzle_orm_pg_core.PgColumn<{
+            name: "email";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timebackId: drizzle_orm_pg_core.PgColumn<{
+            name: "timeback_id";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        emailVerified: drizzle_orm_pg_core.PgColumn<{
+            name: "email_verified";
+            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;
+        }, {}, {}>;
+        image: drizzle_orm_pg_core.PgColumn<{
+            name: "image";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        role: drizzle_orm_pg_core.PgColumn<{
+            name: "role";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "admin" | "player" | "developer";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["admin", "player", "developer"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        developerStatus: drizzle_orm_pg_core.PgColumn<{
+            name: "developer_status";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "none" | "pending" | "approved";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["none", "pending", "approved"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        characterCreated: drizzle_orm_pg_core.PgColumn<{
+            name: "character_created";
+            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;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 
+type GameMetadata = {
+    description?: string;
+    emoji?: string;
+    [key: string]: unknown;
+};
 /**
- * Base error class for Cademy SDK specific errors.
- */
-declare class PlaycademyError extends Error {
-    constructor(message: string);
-}
-declare class ApiError extends Error {
-    status: number;
-    details: unknown;
-    constructor(status: number, message: string, details: unknown);
-}
-/**
- * Structure of error response bodies returned by API endpoints
+ * DNS validation records for custom hostname
+ * Structure for the validationRecords JSON field in game_custom_hostnames table
  */
-interface ErrorResponseBody {
-    error?: string;
-    message?: string;
-}
-/**
- * Extract useful error information from an API error
- * Useful for displaying errors to users in a friendly way
- */
-interface ApiErrorInfo {
-    status: number;
-    statusText: string;
-    error?: string;
-    message?: string;
-    details?: unknown;
-}
-declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
-
-/**
- * Connection monitoring types
- *
- * Type definitions for connection state, configuration, and callbacks.
- */
-/**
- * Possible connection states.
- *
- * - **online**: Connection is stable and healthy
- * - **offline**: Complete loss of network connectivity
- * - **degraded**: Connection is slow or experiencing intermittent issues
- */
-type ConnectionState = 'online' | 'offline' | 'degraded';
-/**
- * Configuration options for ConnectionMonitor.
- *
- * @see {@link ConnectionMonitor} for usage
- */
-interface ConnectionMonitorConfig {
-    /** Base URL for heartbeat pings (e.g., 'https://api.playcademy.com') */
-    baseUrl: string;
-    /** How often to send heartbeat pings in milliseconds (default: 10000) */
-    heartbeatInterval?: number;
-    /** How long to wait for heartbeat response in milliseconds (default: 5000) */
-    heartbeatTimeout?: number;
-    /** Number of consecutive failures before triggering disconnect (default: 2) */
-    failureThreshold?: number;
-    /** Enable periodic heartbeat monitoring (default: true) */
-    enableHeartbeat?: boolean;
-    /** Enable browser online/offline event listeners (default: true) */
-    enableOfflineEvents?: boolean;
-}
-/**
- * Callback function signature for connection state changes.
- *
- * @param state - The new connection state
- * @param reason - Human-readable reason for the state change
- */
-type ConnectionChangeCallback = (state: ConnectionState, reason: string) => void;
-
-/**
- * Connection Monitor
- *
- * Monitors network connectivity using multiple signals:
- * 1. navigator.onLine - Instant offline detection
- * 2. Periodic heartbeat - Detects slow/degraded connections
- * 3. Request failure tracking - Piggybacks on actual API calls
- *
- * Designed for school WiFi environments where connections may be
- * unstable or degraded without fully disconnecting.
- */
-
-/**
- * Monitors network connectivity using multiple signals and notifies callbacks of state changes.
- *
- * The ConnectionMonitor uses a multi-signal approach to detect connection issues:
- *
- * 1. **navigator.onLine events** - Instant detection of hard disconnects
- * 2. **Heartbeat pings** - Periodic checks to detect slow/degraded connections
- * 3. **Request failure tracking** - Piggybacks on actual API calls
- *
- * This comprehensive approach ensures reliable detection across different network
- * failure modes common in school WiFi environments (hard disconnect, slow connection,
- * intermittent failures).
- *
- * @example
- * ```typescript
- * const monitor = new ConnectionMonitor({
- *   baseUrl: 'https://api.playcademy.com',
- *   heartbeatInterval: 10000,  // Check every 10s
- *   failureThreshold: 2         // Trigger after 2 failures
- * })
- *
- * monitor.onChange((state, reason) => {
- *   console.log(`Connection: ${state} - ${reason}`)
- * })
- *
- * monitor.start()
- * ```
- *
- * @see {@link ConnectionManagerConfig} for configuration options
- */
-declare class ConnectionMonitor {
-    private state;
-    private callbacks;
-    private heartbeatInterval?;
-    private consecutiveFailures;
-    private isMonitoring;
-    private config;
-    /**
-     * Creates a new ConnectionMonitor instance.
-     *
-     * The monitor starts in a stopped state. Call `start()` to begin monitoring.
-     *
-     * @param config - Configuration options
-     * @param config.baseUrl - Base URL for heartbeat pings
-     * @param config.heartbeatInterval - How often to check (default: 10000ms)
-     * @param config.heartbeatTimeout - Request timeout (default: 5000ms)
-     * @param config.failureThreshold - Failures before triggering disconnect (default: 2)
-     * @param config.enableHeartbeat - Enable periodic checks (default: true)
-     * @param config.enableOfflineEvents - Listen to browser events (default: true)
-     */
-    constructor(config: ConnectionMonitorConfig);
-    /**
-     * Starts monitoring the connection state.
-     *
-     * Sets up event listeners and begins heartbeat checks based on configuration.
-     * Idempotent - safe to call multiple times.
-     */
-    start(): void;
-    /**
-     * Stops monitoring the connection state and cleans up resources.
-     *
-     * Removes event listeners and clears heartbeat intervals.
-     * Idempotent - safe to call multiple times.
-     */
-    stop(): void;
-    /**
-     * Registers a callback to be notified of all connection state changes.
-     *
-     * The callback fires for all state transitions: online → offline,
-     * offline → degraded, degraded → online, etc.
-     *
-     * @param callback - Function called with (state, reason) when connection changes
-     * @returns Cleanup function to unregister the callback
-     *
-     * @example
-     * ```typescript
-     * const cleanup = monitor.onChange((state, reason) => {
-     *   console.log(`Connection: ${state}`)
-     *   if (state === 'offline') {
-     *     showReconnectingUI()
-     *   }
-     * })
-     *
-     * // Later: cleanup() to unregister
-     * ```
-     */
-    onChange(callback: ConnectionChangeCallback): () => void;
-    /**
-     * Gets the current connection state.
-     *
-     * @returns The current state ('online', 'offline', or 'degraded')
-     */
-    getState(): ConnectionState;
-    /**
-     * Manually triggers an immediate connection check.
-     *
-     * Forces a heartbeat ping to verify connectivity right now, bypassing
-     * the normal interval. Useful before critical operations.
-     *
-     * @returns Promise resolving to the current connection state after the check
-     *
-     * @example
-     * ```typescript
-     * const state = await monitor.checkNow()
-     * if (state !== 'online') {
-     *   alert('Please check your internet connection')
-     * }
-     * ```
-     */
-    checkNow(): Promise<ConnectionState>;
-    /**
-     * Reports a request failure for tracking.
-     *
-     * This should be called from your request wrapper whenever an API call fails.
-     * Only network errors are tracked (TypeError, fetch failures) - HTTP error
-     * responses (4xx, 5xx) are ignored.
-     *
-     * After consecutive failures exceed the threshold, the monitor transitions
-     * to 'degraded' or 'offline' state.
-     *
-     * @param error - The error from the failed request
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   await fetch('/api/data')
-     * } catch (error) {
-     *   monitor.reportRequestFailure(error)
-     *   throw error
-     * }
-     * ```
-     */
-    reportRequestFailure(error: unknown): void;
-    /**
-     * Reports a successful request.
-     *
-     * This should be called from your request wrapper whenever an API call succeeds.
-     * Resets the consecutive failure counter and transitions from 'degraded' to
-     * 'online' if the connection has recovered.
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const result = await fetch('/api/data')
-     *   monitor.reportRequestSuccess()
-     *   return result
-     * } catch (error) {
-     *   monitor.reportRequestFailure(error)
-     *   throw error
-     * }
-     * ```
-     */
-    reportRequestSuccess(): void;
-    private _detectInitialState;
-    private _handleOnline;
-    private _handleOffline;
-    private _startHeartbeat;
-    private _performHeartbeat;
-    private _handleHeartbeatFailure;
-    private _setState;
-}
-
-/**
- * OAuth 2.0 implementation for the Playcademy SDK
- */
-
-/**
- * Parses an OAuth state parameter to extract CSRF token and any encoded data.
- *
- * @param state - The OAuth state parameter to parse
- * @returns Object containing CSRF token and optional decoded data
- */
-declare function parseOAuthState(state: string): {
-    csrfToken: string;
-    data?: Record<string, string>;
-};
-
-declare const userRoleEnum: drizzle_orm_pg_core.PgEnum<["admin", "player", "developer"]>;
-declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "user";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: true;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        name: drizzle_orm_pg_core.PgColumn<{
-            name: "name";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        username: drizzle_orm_pg_core.PgColumn<{
-            name: "username";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        email: drizzle_orm_pg_core.PgColumn<{
-            name: "email";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        timebackId: drizzle_orm_pg_core.PgColumn<{
-            name: "timeback_id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        emailVerified: drizzle_orm_pg_core.PgColumn<{
-            name: "email_verified";
-            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;
-        }, {}, {}>;
-        image: drizzle_orm_pg_core.PgColumn<{
-            name: "image";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        role: drizzle_orm_pg_core.PgColumn<{
-            name: "role";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "admin" | "player" | "developer";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["admin", "player", "developer"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        developerStatus: drizzle_orm_pg_core.PgColumn<{
-            name: "developer_status";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "none" | "pending" | "approved";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["none", "pending", "approved"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        characterCreated: drizzle_orm_pg_core.PgColumn<{
-            name: "character_created";
-            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;
-        }, {}, {}>;
-        createdAt: drizzle_orm_pg_core.PgColumn<{
-            name: "created_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
-
-type GameMetadata = {
-    description?: string;
-    emoji?: string;
-    [key: string]: unknown;
-};
-/**
- * DNS validation records for custom hostname
- * Structure for the validationRecords JSON field in game_custom_hostnames table
- */
-type CustomHostnameValidationRecords = {
-    /** TXT record for ownership verification */
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    /** TXT records for SSL certificate validation */
-    ssl?: Array<{
-        txt_name?: string;
-        txt_value?: string;
-    }>;
+type CustomHostnameValidationRecords = {
+    /** TXT record for ownership verification */
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    /** TXT records for SSL certificate validation */
+    ssl?: Array<{
+        txt_name?: string;
+        txt_value?: string;
+    }>;
 };
 declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "games";
@@ -3974,29 +3689,82 @@ type UserRoleEnumType = (typeof userRoleEnum.enumValues)[number];
 type DeveloperStatusResponse = z.infer<typeof DeveloperStatusResponseSchema>;
 type DeveloperStatusValue = DeveloperStatusResponse['status'];
 /**
- * User data with authentication provider information.
- * Returned by the /users/me endpoint with additional auth context.
+ * TimeBack enrollment information for a game.
  */
-type AuthenticatedUser = User & {
-    /** Whether the user authenticated via Timeback SSO */
-    hasTimebackAccount: boolean;
+type UserEnrollment = {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
 };
-
 /**
- * Cross-Domain Composite Types
- * Types that combine data from multiple domains
+ * TimeBack user role (matches OneRoster spec).
  */
-type ManifestV1 = z.infer<typeof ManifestV1Schema>;
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
 /**
- * Basic user information in the shape of the claims from identity providers
+ * Organization type (matches OneRoster spec).
  */
-interface UserInfo {
-    /** Unique user identifier (sub claim from JWT) */
-    sub: string;
-    /** User's email address */
-    email: string;
-    /** User's display name */
-    name: string;
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * TimeBack organization data for a user.
+ * Represents schools, districts, or other educational organizations.
+ */
+type UserOrganization = {
+    /** Organization ID (OneRoster sourcedId) */
+    id: string;
+    /** Organization name */
+    name: string | null;
+    /** Organization type (school, district, etc.) */
+    type: TimebackOrgType | string;
+    /** Whether this is the user's primary organization */
+    isPrimary: boolean;
+};
+/**
+ * TimeBack student profile (role + organizations).
+ * Subset of UserTimebackData returned by OneRoster API.
+ */
+type TimebackStudentProfile = {
+    /** User's primary role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's organizations (schools/districts) */
+    organizations: UserOrganization[];
+};
+/**
+ * TimeBack-related data for a user.
+ */
+type UserTimebackData = TimebackStudentProfile & {
+    /** User's TimeBack ID (sourcedId) */
+    id: string;
+    /** Course enrollments */
+    enrollments: UserEnrollment[];
+};
+/**
+ * User data with authentication provider information.
+ * Returned by the /users/me endpoint with additional auth context.
+ */
+type AuthenticatedUser = Omit<User, 'timebackId'> & {
+    /** Whether the user authenticated via Timeback SSO */
+    hasTimebackAccount: boolean;
+    /** TimeBack data (id, role, enrollments, organizations) - only present if user has a timeback account */
+    timeback?: UserTimebackData;
+};
+
+/**
+ * Cross-Domain Composite Types
+ * Types that combine data from multiple domains
+ */
+type ManifestV1 = z.infer<typeof ManifestV1Schema>;
+/**
+ * Basic user information in the shape of the claims from identity providers
+ */
+interface UserInfo {
+    /** Unique user identifier (sub claim from JWT) */
+    sub: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name: string;
     /** Whether the email has been verified */
     email_verified: boolean;
     /** Optional given name (first name) */
@@ -4386,1819 +4154,2178 @@ type EndActivityResponse = {
     inProgress?: string;
 };
 
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
 /**
- * Auto-initializes a PlaycademyClient with context from the environment.
- * Works in both iframe mode (production/development) and standalone mode (local dev).
+ * Base error class for Cademy SDK specific errors.
+ */
+declare class PlaycademyError extends Error {
+    constructor(message: string);
+}
+declare class ApiError extends Error {
+    status: number;
+    details: unknown;
+    constructor(status: number, message: string, details: unknown);
+}
+/**
+ * Structure of error response bodies returned by API endpoints
+ */
+interface ErrorResponseBody {
+    error?: string;
+    message?: string;
+}
+/**
+ * Extract useful error information from an API error
+ * Useful for displaying errors to users in a friendly way
+ */
+interface ApiErrorInfo {
+    status: number;
+    statusText: string;
+    error?: string;
+    message?: string;
+    details?: unknown;
+}
+declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
+
+/**
+ * Connection monitoring types
  *
- * This is the recommended way to initialize the SDK as it automatically:
- * - Detects the runtime environment (iframe vs standalone)
- * - Configures the client with the appropriate context
- * - Sets up event listeners for token refresh
- * - Exposes the client for debugging in development mode
+ * Type definitions for connection state, configuration, and callbacks.
+ */
+/**
+ * Possible connection states.
  *
- * @param options - Optional configuration overrides
- * @param options.baseUrl - Override the base URL for API requests
- * @returns Promise resolving to a fully initialized PlaycademyClient
- * @throws Error if not running in a browser context
+ * - **online**: Connection is stable and healthy
+ * - **offline**: Complete loss of network connectivity
+ * - **degraded**: Connection is slow or experiencing intermittent issues
+ */
+type ConnectionState = 'online' | 'offline' | 'degraded';
+/**
+ * Configuration options for ConnectionMonitor.
  *
- * @example
- * ```typescript
- * // Default initialization
- * const client = await PlaycademyClient.init()
+ * @see {@link ConnectionMonitor} for usage
+ */
+interface ConnectionMonitorConfig {
+    /** Base URL for heartbeat pings (e.g., 'https://api.playcademy.com') */
+    baseUrl: string;
+    /** How often to send heartbeat pings in milliseconds (default: 10000) */
+    heartbeatInterval?: number;
+    /** How long to wait for heartbeat response in milliseconds (default: 5000) */
+    heartbeatTimeout?: number;
+    /** Number of consecutive failures before triggering disconnect (default: 2) */
+    failureThreshold?: number;
+    /** Enable periodic heartbeat monitoring (default: true) */
+    enableHeartbeat?: boolean;
+    /** Enable browser online/offline event listeners (default: true) */
+    enableOfflineEvents?: boolean;
+}
+/**
+ * Callback function signature for connection state changes.
  *
- * // With custom base URL
- * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
- * ```
+ * @param state - The new connection state
+ * @param reason - Human-readable reason for the state change
  */
-declare function init<T extends PlaycademyClient = PlaycademyClient>(this: new (...args: ConstructorParameters<typeof PlaycademyClient>) => T, options?: {
-    baseUrl?: string;
-    allowedParentOrigins?: string[];
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
-}): Promise<T>;
+type ConnectionChangeCallback = (state: ConnectionState, reason: string) => void;
 
 /**
- * Authenticates a user with email and password.
+ * Connection Monitor
  *
- * This is a standalone authentication method that doesn't require an initialized client.
- * Use this for login flows before creating a client instance.
+ * Monitors network connectivity using multiple signals:
+ * 1. navigator.onLine - Instant offline detection
+ * 2. Periodic heartbeat - Detects slow/degraded connections
+ * 3. Request failure tracking - Piggybacks on actual API calls
  *
- * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ * Designed for school WiFi environments where connections may be
+ * unstable or degraded without fully disconnecting.
+ */
+
+/**
+ * Monitors network connectivity using multiple signals and notifies callbacks of state changes.
  *
- * @param baseUrl - The base URL of the Playcademy API
- * @param email - User's email address
- * @param password - User's password
- * @returns Promise resolving to authentication response with token
- * @throws PlaycademyError if authentication fails or network error occurs
+ * The ConnectionMonitor uses a multi-signal approach to detect connection issues:
+ *
+ * 1. **navigator.onLine events** - Instant detection of hard disconnects
+ * 2. **Heartbeat pings** - Periodic checks to detect slow/degraded connections
+ * 3. **Request failure tracking** - Piggybacks on actual API calls
+ *
+ * This comprehensive approach ensures reliable detection across different network
+ * failure modes common in school WiFi environments (hard disconnect, slow connection,
+ * intermittent failures).
  *
  * @example
  * ```typescript
- * // Preferred approach:
- * const client = new PlaycademyClient({ baseUrl: '/api' })
- * const result = await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password'
+ * const monitor = new ConnectionMonitor({
+ *   baseUrl: 'https://api.playcademy.com',
+ *   heartbeatInterval: 10000,  // Check every 10s
+ *   failureThreshold: 2         // Trigger after 2 failures
  * })
  *
- * // Legacy approach (still works):
- * try {
- *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
- *   const client = new PlaycademyClient({ token: response.token })
- * } catch (error) {
- *   console.error('Login failed:', error.message)
- * }
+ * monitor.onChange((state, reason) => {
+ *   console.log(`Connection: ${state} - ${reason}`)
+ * })
+ *
+ * monitor.start()
  * ```
+ *
+ * @see {@link ConnectionManagerConfig} for configuration options
  */
-declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
-
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
-/**
- * Main Playcademy SDK client for interacting with the platform API.
- * Provides namespaced access to all platform features including games, users, inventory, and more.
- */
-declare class PlaycademyClient {
-    baseUrl: string;
-    gameUrl?: string;
-    private authStrategy;
-    private gameId?;
+declare class ConnectionMonitor {
+    private state;
+    private callbacks;
+    private heartbeatInterval?;
+    private consecutiveFailures;
+    private isMonitoring;
     private config;
-    private listeners;
-    private internalClientSessionId?;
-    private authContext?;
-    private initPayload?;
-    private connectionManager?;
-    /**
-     * Internal session manager for automatic session lifecycle.
-     *
-     * This manager handles starting and ending game sessions automatically.
-     * Game developers don't need to call these methods directly - they're managed
-     * by the SDK during initialization and cleanup.
-     *
-     * @private
-     * @internal
-     */
-    private _sessionManager;
-    /**
-     * Creates a new PlaycademyClient instance.
-     *
-     * @param config - Optional configuration object
-     * @param config.baseUrl - Base URL (e.g., 'https://hub.playcademy.net' or '/'). SDK automatically appends /api
-     * @param config.token - Authentication token
-     * @param config.tokenType - Optional token type (auto-detected if not provided)
-     * @param config.gameId - Game ID for automatic session management
-     * @param config.autoStartSession - Automatically start a game session?
-     */
-    constructor(config?: Partial<ClientConfig>);
     /**
-     * Gets the effective base URL for API requests.
-     * Converts relative URLs to absolute URLs in browser environments.
-     * Note: baseUrl already includes /api suffix from constructor.
+     * Creates a new ConnectionMonitor instance.
      *
-     * @returns The complete base URL for API requests (with /api suffix)
-     */
-    getBaseUrl(): string;
-    /**
-     * Gets the effective game backend URL for integration requests.
-     * Throws if gameUrl is not configured.
+     * The monitor starts in a stopped state. Call `start()` to begin monitoring.
      *
-     * @returns The complete game backend URL for API requests (with /api suffix)
-     * @throws PlaycademyError if gameUrl is not set
+     * @param config - Configuration options
+     * @param config.baseUrl - Base URL for heartbeat pings
+     * @param config.heartbeatInterval - How often to check (default: 10000ms)
+     * @param config.heartbeatTimeout - Request timeout (default: 5000ms)
+     * @param config.failureThreshold - Failures before triggering disconnect (default: 2)
+     * @param config.enableHeartbeat - Enable periodic checks (default: true)
+     * @param config.enableOfflineEvents - Listen to browser events (default: true)
      */
-    private getGameBackendUrl;
+    constructor(config: ConnectionMonitorConfig);
     /**
-     * Simple ping method for testing connectivity.
+     * Starts monitoring the connection state.
      *
-     * @returns 'pong' string response
+     * Sets up event listeners and begins heartbeat checks based on configuration.
+     * Idempotent - safe to call multiple times.
      */
-    ping(): string;
+    start(): void;
     /**
-     * Sets the authentication token for API requests.
-     * Emits an 'authChange' event when the token changes.
+     * Stops monitoring the connection state and cleans up resources.
      *
-     * @param token - The authentication token, or null to clear
-     * @param tokenType - Optional token type (auto-detected if not provided)
+     * Removes event listeners and clears heartbeat intervals.
+     * Idempotent - safe to call multiple times.
      */
-    setToken(token: string | null, tokenType?: TokenType): void;
+    stop(): void;
     /**
-     * Gets the current token type.
+     * Registers a callback to be notified of all connection state changes.
      *
-     * @returns The token type
-     */
-    getTokenType(): TokenType;
-    /**
-     * Gets the current authentication token.
+     * The callback fires for all state transitions: online → offline,
+     * offline → degraded, degraded → online, etc.
      *
-     * @returns The current token or null if not authenticated
+     * @param callback - Function called with (state, reason) when connection changes
+     * @returns Cleanup function to unregister the callback
      *
      * @example
      * ```typescript
-     * // Send token to your backend for verification
-     * const token = client.getToken()
-     * const response = await fetch('/api/auth/playcademy', {
-     *     method: 'POST',
-     *     body: JSON.stringify({ gameToken: token })
+     * const cleanup = monitor.onChange((state, reason) => {
+     *   console.log(`Connection: ${state}`)
+     *   if (state === 'offline') {
+     *     showReconnectingUI()
+     *   }
      * })
+     *
+     * // Later: cleanup() to unregister
      * ```
      */
-    getToken(): string | null;
+    onChange(callback: ConnectionChangeCallback): () => void;
     /**
-     * Checks if the client has a valid API token for making Playcademy API requests.
-     *
-     * For games (iframe context): Checks if we have a valid token from the parent.
-     * For Cademy (standalone): Checks if we have a token from better-auth.
-     *
-     * Note: This checks for API authentication, not whether a user has linked
-     * their identity via OAuth.
+     * Gets the current connection state.
      *
-     * @returns true if API token exists, false otherwise
+     * @returns The current state ('online', 'offline', or 'degraded')
+     */
+    getState(): ConnectionState;
+    /**
+     * Manually triggers an immediate connection check.
+     *
+     * Forces a heartbeat ping to verify connectivity right now, bypassing
+     * the normal interval. Useful before critical operations.
+     *
+     * @returns Promise resolving to the current connection state after the check
      *
      * @example
      * ```typescript
-     * if (client.isAuthenticated()) {
-     *     // Can make API calls
-     *     const games = await client.games.list()
-     * } else {
-     *     console.error('No API token available')
+     * const state = await monitor.checkNow()
+     * if (state !== 'online') {
+     *   alert('Please check your internet connection')
      * }
      * ```
      */
-    isAuthenticated(): boolean;
+    checkNow(): Promise<ConnectionState>;
     /**
-     * Registers a callback to be called when authentication state changes.
+     * Reports a request failure for tracking.
+     *
+     * This should be called from your request wrapper whenever an API call fails.
+     * Only network errors are tracked (TypeError, fetch failures) - HTTP error
+     * responses (4xx, 5xx) are ignored.
+     *
+     * After consecutive failures exceed the threshold, the monitor transitions
+     * to 'degraded' or 'offline' state.
      *
-     * @param callback - Function to call when auth state changes
+     * @param error - The error from the failed request
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await fetch('/api/data')
+     * } catch (error) {
+     *   monitor.reportRequestFailure(error)
+     *   throw error
+     * }
+     * ```
      */
-    onAuthChange(callback: (token: string | null) => void): void;
+    reportRequestFailure(error: unknown): void;
     /**
-     * Registers a callback to be called when connection issues are detected.
+     * Reports a successful request.
      *
-     * This is a convenience method that filters connection change events to only
-     * fire when the connection degrades (offline or degraded states). Use this
-     * when you want to handle disconnects without being notified of recoveries.
+     * This should be called from your request wrapper whenever an API call succeeds.
+     * Resets the consecutive failure counter and transitions from 'degraded' to
+     * 'online' if the connection has recovered.
      *
-     * For all connection state changes, use `client.on('connectionChange', ...)` instead.
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await fetch('/api/data')
+     *   monitor.reportRequestSuccess()
+     *   return result
+     * } catch (error) {
+     *   monitor.reportRequestFailure(error)
+     *   throw error
+     * }
+     * ```
+     */
+    reportRequestSuccess(): void;
+    private _detectInitialState;
+    private _handleOnline;
+    private _handleOffline;
+    private _startHeartbeat;
+    private _performHeartbeat;
+    private _handleHeartbeatFailure;
+    private _setState;
+}
+
+/**
+ * Connection Manager
+ *
+ * Manages connection monitoring and integrates it with the Playcademy client.
+ * Handles event wiring, state management, and disconnect callbacks.
+ *
+ * In iframe mode, disables local monitoring and listens to platform connection
+ * state broadcasts instead (avoids duplicate heartbeats).
+ */
+
+/**
+ * Configuration for the ConnectionManager.
+ */
+interface ConnectionManagerConfig {
+    /** Base URL for API requests (used for heartbeat pings) */
+    baseUrl: string;
+    /** Authentication context (iframe vs standalone) for alert routing */
+    authContext?: {
+        isInIframe: boolean;
+    };
+    /** Handler to call when connection issues are detected */
+    onDisconnect?: DisconnectHandler;
+    /** Callback to emit connection change events to the client */
+    onConnectionChange?: (state: ConnectionState, reason: string) => void;
+}
+/**
+ * Manages connection monitoring for the Playcademy client.
+ *
+ * The ConnectionManager serves as an integration layer between the low-level
+ * ConnectionMonitor and the PlaycademyClient. It handles:
+ * - Event wiring and coordination
+ * - Disconnect callbacks with context
+ * - Platform-level alert integration
+ * - Request success/failure tracking
+ *
+ * This class is used internally by PlaycademyClient and typically not
+ * instantiated directly by game developers.
+ *
+ * @see {@link ConnectionMonitor} for the underlying monitoring implementation
+ * @see {@link PlaycademyClient.onDisconnect} for the public API
+ */
+declare class ConnectionManager {
+    private monitor?;
+    private authContext?;
+    private disconnectHandler?;
+    private connectionChangeCallback?;
+    private currentState;
+    private additionalDisconnectHandlers;
+    /**
+     * Creates a new ConnectionManager instance.
      *
-     * @param callback - Function to call when connection state changes to offline or degraded
-     * @returns Cleanup function to unregister the callback
+     * @param config - Configuration options for the manager
      *
      * @example
      * ```typescript
-     * const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
-     *   console.log(`Connection ${state}: ${reason}`)
-     *
-     *   if (state === 'offline') {
-     *     // Save state and return to game lobby
-     *     displayAlert?.('Connection lost. Your progress has been saved.', { type: 'error' })
-     *     saveGameState()
-     *     returnToLobby()
-     *   } else if (state === 'degraded') {
-     *     displayAlert?.('Slow connection detected.', { type: 'warning' })
+     * const manager = new ConnectionManager({
+     *   baseUrl: 'https://api.playcademy.com',
+     *   authContext: { isInIframe: false },
+     *   onDisconnect: (context) => {
+     *     console.log(`Disconnected: ${context.state}`)
+     *   },
+     *   onConnectionChange: (state, reason) => {
+     *     console.log(`Connection changed: ${state}`)
      *   }
      * })
-     *
-     * // Later: cleanup() to unregister
      * ```
-     *
-     * @see Connection monitoring documentation in SDK Browser docs for detailed usage examples
-     * @see {@link ConnectionManager.onDisconnect} for the underlying implementation
      */
-    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    constructor(config: ConnectionManagerConfig);
     /**
      * Gets the current connection state.
      *
-     * Returns the last known connection state without triggering a new check.
-     * Use `checkConnection()` to force an immediate verification.
-     *
-     * @returns Current connection state ('online', 'offline', 'degraded') or 'unknown' if monitoring is disabled
+     * @returns The current connection state ('online', 'offline', or 'degraded')
      *
      * @example
      * ```typescript
-     * const state = client.getConnectionState()
+     * const state = manager.getState()
      * if (state === 'offline') {
-     *   console.log('No connection available')
+     *   console.log('No connection')
      * }
      * ```
-     *
-     * @see {@link checkConnection} to trigger an immediate connection check
-     * @see {@link ConnectionManager.getState} for the underlying implementation
      */
-    getConnectionState(): ConnectionState | 'unknown';
+    getState(): ConnectionState;
     /**
      * Manually triggers a connection check immediately.
      *
-     * Forces a heartbeat ping to verify connectivity right now, bypassing the normal
-     * interval. Useful when you need to verify connection status before a critical
-     * operation (e.g., saving important game state).
+     * Forces a heartbeat ping to verify the current connection status.
+     * Useful when you need to check connectivity before a critical operation.
+     *
+     * In iframe mode, this returns the last known state from platform.
      *
-     * @returns Promise resolving to the current connection state after verification
+     * @returns Promise resolving to the current connection state
      *
      * @example
      * ```typescript
-     * // Check before critical operation
-     * const state = await client.checkConnection()
-     * if (state !== 'online') {
-     *   alert('Please check your internet connection before saving')
-     *   return
+     * const state = await manager.checkNow()
+     * if (state === 'online') {
+     *   await performCriticalOperation()
      * }
-     *
-     * await client.games.saveState(importantData)
      * ```
-     *
-     * @see {@link getConnectionState} to get the last known state without checking
-     * @see {@link ConnectionManager.checkNow} for the underlying implementation
-     */
-    checkConnection(): Promise<ConnectionState | 'unknown'>;
-    /**
-     * Sets the authentication context for the client.
-     * This is called during initialization to store environment info.
-     * @internal
      */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
+    checkNow(): Promise<ConnectionState>;
     /**
-     * Registers an event listener for client events.
+     * Reports a successful API request to the connection monitor.
      *
-     * @param event - The event type to listen for
-     * @param callback - Function to call when the event is emitted
-     */
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
-    /**
-     * Emits an event to all registered listeners.
+     * This resets the consecutive failure counter and transitions from
+     * 'degraded' to 'online' state if applicable.
      *
-     * @param event - The event type to emit
-     * @param payload - The event payload
+     * Typically called automatically by the SDK's request wrapper.
+     * No-op in iframe mode (platform handles monitoring).
      */
-    private emit;
+    reportRequestSuccess(): void;
     /**
-     * Makes an authenticated HTTP request to the platform API.
+     * Reports a failed API request to the connection monitor.
      *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param options - Optional request configuration
-     * @param options.body - Request body
-     * @param options.headers - Additional headers
-     * @param options.raw - If true, returns raw Response instead of parsing
-     * @returns Promise resolving to the response data or raw Response
-     */
-    protected request<T>(path: string, method: Method, options?: {
-        body?: unknown;
-        headers?: Record<string, string>;
-        raw?: boolean;
-    }): Promise<T>;
-    /**
-     * Makes an authenticated HTTP request to the game's backend Worker.
-     * Uses gameUrl if set, otherwise falls back to platform API.
+     * Only network errors are tracked (not 4xx/5xx HTTP responses).
+     * After consecutive failures exceed the threshold, the state transitions
+     * to 'degraded' or 'offline'.
+     *
+     * Typically called automatically by the SDK's request wrapper.
+     * No-op in iframe mode (platform handles monitoring).
      *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param body - Request body (optional)
-     * @param headers - Additional headers (optional)
-     * @param raw - If true, returns raw Response instead of parsing (optional)
-     * @returns Promise resolving to the response data or raw Response
+     * @param error - The error from the failed request
      */
-    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, raw?: boolean): Promise<T>;
+    reportRequestFailure(error: unknown): void;
     /**
-     * Ensures a gameId is available, throwing an error if not.
+     * Registers a callback to be called when connection issues are detected.
+     *
+     * The callback only fires for 'offline' and 'degraded' states, not when
+     * recovering to 'online'. This provides a clean API for games to handle
+     * disconnect scenarios without being notified of every state change.
+     *
+     * Works in both iframe and standalone modes transparently.
+     *
+     * @param callback - Function to call when connection degrades
+     * @returns Cleanup function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
+     *   if (state === 'offline') {
+     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
+     *     saveGameState()
+     *   }
+     * })
      *
-     * @returns The gameId
-     * @throws PlaycademyError if no gameId is configured
+     * // Later: cleanup() to unregister
+     * ```
      */
-    private _ensureGameId;
+    onDisconnect(callback: DisconnectHandler): () => void;
     /**
-     * Detects and sets the authentication context (iframe vs standalone).
-     * Safe to call in any environment - isInIframe handles browser detection.
+     * Stops connection monitoring and performs cleanup.
+     *
+     * Removes event listeners and clears heartbeat intervals.
+     * Should be called when the client is being destroyed.
      */
-    private _detectAuthContext;
+    stop(): void;
     /**
-     * Initializes connection monitoring if enabled.
-     * Safe to call in any environment - only runs in browser.
+     * Sets up listener for platform connection state broadcasts (iframe mode only).
      */
-    private _initializeConnectionMonitor;
+    private _setupPlatformListener;
     /**
-     * Initializes an internal game session for automatic session management.
-     * Only starts a session if:
-     * 1. A gameId is configured
-     * 2. No session already exists
-     * 3. autoStartSession is enabled (defaults to false)
+     * Handles connection state changes from the monitor or platform.
+     *
+     * Coordinates between:
+     * 1. Emitting events to the client (for client.on('connectionChange'))
+     * 2. Calling the disconnect handler if configured
+     * 3. Calling any additional handlers registered via onDisconnect()
+     *
+     * @param state - The new connection state
+     * @param reason - Human-readable reason for the state change
      */
-    private _initializeInternalSession;
-    /** Identity provider connection methods (connect external accounts) */
-    identity: {
-        connect: (options: AuthOptions) => Promise<AuthResult>;
-        _getContext: () => {
-            isInIframe: boolean;
-        };
-    };
-    /** Runtime methods (getGameToken, exit) */
-    runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean;
-        }) => Promise<GameTokenResponse>;
-        exit: () => Promise<void>;
-        onInit: (handler: (context: GameContextPayload) => void) => void;
-        onTokenRefresh: (handler: (data: {
-            token: string;
-            exp: number;
-        }) => void) => void;
-        onPause: (handler: () => void) => void;
-        onResume: (handler: () => void) => void;
-        onForceExit: (handler: () => void) => void;
-        onOverlay: (handler: (isVisible: boolean) => void) => void;
-        ready: () => void;
-        sendTelemetry: (data: {
-            fps: number;
-            mem: number;
-        }) => void;
-        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
-            token: string;
-            exp: number;
-        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
-        removeAllListeners: () => void;
-        getListenerCounts: () => Record<string, number>;
-        assets: {
-            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit) => Promise<Response>;
-            json: <T = unknown>(path: string) => Promise<T>;
-            blob: (path: string) => Promise<Blob>;
-            text: (path: string) => Promise<string>;
-            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
-        };
-    };
-    /** User methods (me, inventory management) */
-    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>;
-        };
-    };
-    /** TimeBack XP methods (today, total, history) */
-    timeback: {
-        startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
-        pauseActivity: () => void;
-        resumeActivity: () => void;
-        endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
-    };
-    /** Credits methods (credits management) */
-    credits: {
-        balance: () => Promise<number>;
-        add: (amount: number) => Promise<number>;
-        spend: (amount: number) => Promise<number>;
-    };
-    /** Platform-wide scores methods (submit, getUserScores) */
-    scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
-    };
-    /** Realtime methods (token) */
-    realtime: {
-        token: {
-            get: () => Promise<RealtimeTokenResponse>;
-        };
-        open(channel?: string, url?: string): Promise<_playcademy_realtime_server_types.RealtimeChannel>;
-    };
-    /** Backend methods for calling custom game API routes */
-    backend: {
-        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
-        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-    };
-    /** Auto-initializes a PlaycademyClient with context from the environment */
-    static init: typeof init;
-    /** Authenticates a user with email and password */
-    static login: typeof login;
-    /** Static identity utilities for OAuth operations */
-    static identity: {
-        parseOAuthState: typeof parseOAuthState;
-    };
+    private _handleConnectionChange;
 }
 
 /**
- * Core client configuration and lifecycle types
- */
-type TokenType = 'session' | 'apiKey' | 'gameJwt';
-interface ClientConfig {
-    baseUrl: string;
-    gameUrl?: string;
-    token?: string;
-    tokenType?: TokenType;
-    gameId?: string;
-    autoStartSession?: boolean;
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
-}
-/**
- * Handler called when connection state changes to offline or degraded.
- * Games can implement this to handle disconnects gracefully.
+ * @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
  */
-type DisconnectHandler = (context: DisconnectContext) => void | Promise<void>;
+
 /**
- * Context provided to disconnect handlers
+ * Enumeration of all message types used in the Playcademy messaging system.
+ *
+ * **Message Flow Patterns**:
+ *
+ * **Parent → Game (Overworld → Game)**:
+ * - INIT: Provides game with authentication token and configuration
+ * - TOKEN_REFRESH: Updates game's authentication token before expiry
+ * - PAUSE/RESUME: Controls game execution state
+ * - FORCE_EXIT: Immediately terminates the game
+ * - OVERLAY: Shows/hides UI overlays over the game
+ *
+ * **Game → Parent (Game → Overworld)**:
+ * - READY: Game has loaded and is ready to receive messages
+ * - EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
+ * - TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)
  */
-interface DisconnectContext {
-    /** Current connection state */
-    state: 'offline' | 'degraded';
-    /** Reason for the disconnect */
-    reason: string;
-    /** Timestamp when disconnect was detected */
-    timestamp: number;
-    /** Utility to display a platform-level alert */
-    displayAlert: (message: string, options?: {
-        type?: 'info' | 'warning' | 'error';
-        duration?: number;
-    }) => void;
-}
-interface InitPayload {
-    /** Hub API base URL */
-    baseUrl: string;
-    /** Game deployment URL (serves both frontend assets and backend API) */
-    gameUrl?: string;
-    /** Short-lived game token */
-    token: string;
-    /** Game ID */
-    gameId: string;
-    /** Realtime WebSocket URL */
-    realtimeUrl?: string;
+declare enum MessageEvents {
+    /**
+     * Initializes the game with authentication context and configuration.
+     * Sent immediately after game iframe loads.
+     * Payload:
+     * - `baseUrl`: string
+     * - `token`: string
+     * - `gameId`: string
+     */
+    INIT = "PLAYCADEMY_INIT",
+    /**
+     * Updates the game's authentication token before it expires.
+     * Sent periodically to maintain valid authentication.
+     * Payload:
+     * - `token`: string
+     * - `exp`: number
+     */
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
+    /**
+     * Pauses game execution (e.g., when user switches tabs).
+     * Game should pause timers, animations, and user input.
+     * Payload: void
+     */
+    PAUSE = "PLAYCADEMY_PAUSE",
+    /**
+     * Resumes game execution after being paused.
+     * Game should restore timers, animations, and user input.
+     * Payload: void
+     */
+    RESUME = "PLAYCADEMY_RESUME",
+    /**
+     * Forces immediate game termination (emergency exit).
+     * Game should clean up resources and exit immediately.
+     * Payload: void
+     */
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
+    /**
+     * Shows or hides UI overlays over the game.
+     * Game may need to pause or adjust rendering accordingly.
+     * Payload: boolean (true = show overlay, false = hide overlay)
+     */
+    OVERLAY = "PLAYCADEMY_OVERLAY",
+    /**
+     * Broadcasts connection state changes to games.
+     * Sent by platform when network connectivity changes.
+     * Payload:
+     * - `state`: 'online' | 'offline' | 'degraded'
+     * - `reason`: string
+     */
+    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
+    /**
+     * Game has finished loading and is ready to receive messages.
+     * Sent once after game initialization is complete.
+     * Payload: void
+     */
+    READY = "PLAYCADEMY_READY",
+    /**
+     * Game requests to be closed/exited.
+     * Sent when user clicks exit button or game naturally ends.
+     * Payload: void
+     */
+    EXIT = "PLAYCADEMY_EXIT",
+    /**
+     * Game reports performance telemetry data.
+     * Sent periodically for monitoring and analytics.
+     * Payload:
+     * - `fps`: number
+     * - `mem`: number
+     */
+    TELEMETRY = "PLAYCADEMY_TELEMETRY",
+    /**
+     * Game reports key events to parent.
+     * Sent when certain keys are pressed within the game iframe.
+     * Payload:
+     * - `key`: string
+     * - `code?`: string
+     * - `type`: 'keydown' | 'keyup'
+     */
+    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
+    /**
+     * Game requests platform to display an alert.
+     * Sent when connection issues are detected or other important events occur.
+     * Payload:
+     * - `message`: string
+     * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
+     */
+    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
+    /**
+     * Notifies about authentication state changes.
+     * Can be sent in both directions depending on auth flow.
+     * Payload:
+     * - `authenticated`: boolean
+     * - `user`: UserInfo | null
+     * - `error`: Error | null
+     */
+    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
+    /**
+     * OAuth callback data from popup/new-tab windows.
+     * Sent from popup window back to parent after OAuth completes.
+     * Payload:
+     * - `code`: string (OAuth authorization code)
+     * - `state`: string (OAuth state for CSRF protection)
+     * - `error`: string | null (OAuth error if any)
+     */
+    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
 }
 /**
- * Simplified user data passed to games via InitPayload
- * This is a subset of AuthenticatedUser suitable for external game consumption
+ * Type definition for message handler functions.
+ * These functions are called when a specific message type is received.
+ *
+ * @template T - The type of payload data the handler expects
+ * @param payload - The data sent with the message
  */
-interface GameUser {
-    /** Playcademy user ID */
-    id: string;
-    /** Unique username */
-    username: string | null;
-    /** Display name */
-    name: string | null;
-    /** Email address */
-    email: string | null;
-    /** Profile image URL */
-    image: string | null;
-    /** Whether the user has a Timeback account */
-    hasTimebackAccount: boolean;
-}
-type GameContextPayload = {
-    token: string;
-    baseUrl: string;
-    realtimeUrl: string;
-    gameId: string;
-    forwardKeys?: string[];
-};
-type EventListeners = {
-    [E in keyof ClientEvents]?: Array<(payload: ClientEvents[E]) => void>;
-};
-interface ClientEvents {
-    authChange: {
-        token: string | null;
-    };
-    inventoryChange: {
-        itemId: string;
-        delta: number;
-        newTotal: number;
-    };
-    levelUp: {
-        oldLevel: number;
-        newLevel: number;
-        creditsAwarded: number;
-    };
-    xpGained: {
-        amount: number;
-        totalXP: number;
-        leveledUp: boolean;
-    };
-    connectionChange: {
-        state: 'online' | 'offline' | 'degraded';
-        reason: string;
-    };
-}
-
-/**
- * Event and message payload types for SDK messaging system
- */
-
-interface DisplayAlertPayload {
-    message: string;
-    options?: {
-        type?: 'info' | 'warning' | 'error';
-        duration?: number;
-    };
-}
-/**
- * Authentication state change event payload.
- * Used when authentication state changes in the application.
- */
-interface AuthStateChangePayload {
-    /** Whether the user is currently authenticated */
-    authenticated: boolean;
-    /** User information if authenticated, null otherwise */
-    user: UserInfo | null;
-    /** Error information if authentication failed */
-    error: Error | null;
-}
-/**
- * OAuth callback event payload.
- * Used when OAuth flow completes in popup/new-tab windows.
- */
-interface AuthCallbackPayload {
-    /** OAuth authorization code */
-    code: string;
-    /** OAuth state parameter for CSRF protection */
-    state: string;
-    /** Error message if OAuth flow failed */
-    error: string | null;
-}
-/**
- * Message sent from server callback to opener window.
- * This is the standardized format from our server-first architecture.
- */
-interface AuthServerMessage {
-    /** Type of the message */
-    type: 'PLAYCADEMY_AUTH_STATE_CHANGE';
-    /** Whether the user is currently authenticated */
-    authenticated: boolean;
-    /** Whether the authentication was successful */
-    success: boolean;
-    /** Timestamp of the message */
-    ts: number;
-    /** User information if authentication was successful */
-    user?: UserInfo;
-    /** Error message if authentication failed */
-    error?: string;
-}
-/**
- * Token refresh event payload.
- * Sent when authentication token is updated.
- */
-interface TokenRefreshPayload {
-    /** New authentication token */
-    token: string;
-    /** Token expiration timestamp */
-    exp: number;
-}
+type MessageHandler<T = unknown> = (payload: T) => void;
 /**
- * Telemetry event payload.
- * Performance metrics sent from the game.
+ * Type mapping that defines the payload structure for each message type.
+ * This ensures type safety when sending and receiving messages.
+ *
+ * **Usage Examples**:
+ * ```typescript
+ * // Type-safe message sending
+ * messaging.send(MessageEvents.INIT, { baseUrl: '/api', token: 'abc', gameId: '123' })
+ *
+ * // Type-safe message handling
+ * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+ *   console.log(`New token expires at: ${new Date(exp)}`)
+ * })
+ * ```
  */
-interface TelemetryPayload {
-    /** Frames per second */
-    fps: number;
-    /** Memory usage in MB */
-    mem: number;
-}
+type MessageEventMap = {
+    /** Game initialization context with API endpoint, auth token, and game ID */
+    [MessageEvents.INIT]: GameContextPayload;
+    /** Token refresh data with new token and expiration timestamp */
+    [MessageEvents.TOKEN_REFRESH]: TokenRefreshPayload;
+    /** Pause message has no payload data */
+    [MessageEvents.PAUSE]: void;
+    /** Resume message has no payload data */
+    [MessageEvents.RESUME]: void;
+    /** Force exit message has no payload data */
+    [MessageEvents.FORCE_EXIT]: void;
+    /** Overlay visibility state (true = show, false = hide) */
+    [MessageEvents.OVERLAY]: boolean;
+    /** Connection state change from platform */
+    [MessageEvents.CONNECTION_STATE]: ConnectionStatePayload;
+    /** Ready message has no payload data */
+    [MessageEvents.READY]: void;
+    /** Exit message has no payload data */
+    [MessageEvents.EXIT]: void;
+    /** Performance telemetry data */
+    [MessageEvents.TELEMETRY]: TelemetryPayload;
+    /** Key event data */
+    [MessageEvents.KEY_EVENT]: KeyEventPayload;
+    /** Display alert request from game */
+    [MessageEvents.DISPLAY_ALERT]: DisplayAlertPayload;
+    /** Authentication state change notification */
+    [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
+    /** OAuth callback data from popup/new-tab windows */
+    [MessageEvents.AUTH_CALLBACK]: AuthCallbackPayload;
+};
 /**
- * Keyboard event payload.
- * Key events forwarded from the game.
+ * **PlaycademyMessaging Class**
+ *
+ * This is the core messaging system that handles all communication in the Playcademy platform.
+ * It automatically detects the runtime environment and chooses the appropriate transport method.
+ *
+ * **Key Features**:
+ * 1. **Automatic Transport Selection**: Detects iframe vs local context and uses appropriate method
+ * 2. **Type Safety**: Full TypeScript support with payload type checking
+ * 3. **Bidirectional Communication**: Handles both parent→game and game→parent messages
+ * 4. **Event Cleanup**: Proper listener management to prevent memory leaks
+ *
+ * **Transport Methods**:
+ * - **postMessage**: Used for iframe-to-parent communication (production/development)
+ * - **CustomEvent**: Used for local same-context communication (local development)
+ *
+ * **Runtime Detection Logic**:
+ * - If `window.self !== window.top`: We're in an iframe, use postMessage
+ * - If `window.self === window.top`: We're in the same context, use CustomEvent
+ *
+ * **Example Usage**:
+ * ```typescript
+ * // Send a message (automatically chooses transport)
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for messages (handles both transports)
+ * messaging.listen(MessageEvents.INIT, (payload) => {
+ *   console.log('Game initialized with:', payload)
+ * })
+ *
+ * // Clean up listeners
+ * messaging.unlisten(MessageEvents.INIT, handler)
+ * ```
  */
-interface KeyEventPayload {
-    /** Key value (e.g., 'Escape', 'F1') */
-    key: string;
-    /** Key code (optional) */
-    code?: string;
-    /** Event type */
-    type: 'keydown' | 'keyup';
+declare class PlaycademyMessaging {
+    /**
+     * Internal storage for message listeners.
+     *
+     * **Structure Explanation**:
+     * - Outer Map: MessageEvents → Map of handlers for that event type
+     * - Inner Map: MessageHandler → Object containing both listener types
+     * - Object: { postMessage: EventListener, customEvent: EventListener }
+     *
+     * **Why Two Listeners Per Handler?**:
+     * Since we don't know at registration time which transport will be used,
+     * we register both a postMessage listener and a CustomEvent listener.
+     * The appropriate one will be triggered based on the runtime context.
+     */
+    private listeners;
+    /**
+     * **Send Message Method**
+     *
+     * Sends a message using the appropriate transport method based on the runtime context.
+     * This is the main public API for sending messages in the Playcademy system.
+     *
+     * **How It Works**:
+     * 1. Analyzes the message type and current runtime context
+     * 2. Determines if we're in an iframe and if this message should use postMessage
+     * 3. Routes to the appropriate transport method (postMessage or CustomEvent)
+     *
+     * **Transport Selection Logic**:
+     * - **postMessage**: Used when game is in iframe and sending to parent, OR when target window is specified
+     * - **CustomEvent**: Used for local/same-context communication
+     *
+     * **Type Safety**:
+     * The generic type parameter `K` ensures that the payload type matches
+     * the expected type for the given message event.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send
+     * @param payload - The data to send with the message (type-checked)
+     * @param options - Optional configuration for message sending
+     *
+     * @example
+     * ```typescript
+     * // Send game ready signal (no payload)
+     * messaging.send(MessageEvents.READY, undefined)
+     *
+     * // Send telemetry data (typed payload)
+     * messaging.send(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     *
+     * // Send to specific iframe window (parent to iframe communication)
+     * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId }, {
+     *   target: iframe.contentWindow,
+     *   origin: '*'
+     * })
+     *
+     * // TypeScript will error if payload type is wrong
+     * messaging.send(MessageEvents.INIT, "wrong type") // ❌ Error
+     * ```
+     */
+    send<K extends MessageEvents>(type: K, payload: MessageEventMap[K], options?: {
+        target?: Window;
+        origin?: string;
+    }): void;
+    /**
+     * **Listen for Messages Method**
+     *
+     * Registers a message listener that will be called when the specified message type is received.
+     * This method automatically handles both postMessage and CustomEvent sources.
+     *
+     * **Why Register Two Listeners?**:
+     * Since we don't know at registration time which transport method will be used to send
+     * messages, we register listeners for both possible sources:
+     * 1. **postMessage listener**: Handles messages from iframe-to-parent communication
+     * 2. **CustomEvent listener**: Handles messages from local same-context communication
+     *
+     * **Message Processing**:
+     * - **postMessage**: Extracts data from `event.data.payload` or `event.data`
+     * - **CustomEvent**: Extracts data from `event.detail`
+     *
+     * **Type Safety**:
+     * The handler function receives the correctly typed payload based on the message type.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to listen for
+     * @param handler - Function to call when the message is received
+     *
+     * @example
+     * ```typescript
+     * // Listen for game initialization
+     * messaging.listen(MessageEvents.INIT, (payload) => {
+     *   // payload is automatically typed as GameContextPayload
+     *   console.log(`Game ${payload.gameId} initialized`)
+     *   console.log(`API base URL: ${payload.baseUrl}`)
+     * })
+     *
+     * // Listen for token refresh
+     * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+     *   // payload is automatically typed as { token: string; exp: number }
+     *   updateAuthToken(token)
+     *   scheduleTokenRefresh(exp)
+     * })
+     * ```
+     */
+    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    /**
+     * **Remove Message Listener Method**
+     *
+     * Removes a previously registered message listener to prevent memory leaks and unwanted callbacks.
+     * This method cleans up both the postMessage and CustomEvent listeners that were registered.
+     *
+     * **Why Clean Up Both Listeners?**:
+     * When we registered the listener with `listen()`, we created two browser event listeners:
+     * 1. A 'message' event listener for postMessage communication
+     * 2. A custom event listener for local CustomEvent communication
+     *
+     * Both must be removed to prevent memory leaks and ensure the handler is completely unregistered.
+     *
+     * **Memory Management**:
+     * - Removes both event listeners from the browser
+     * - Cleans up internal tracking maps
+     * - If no more handlers exist for a message type, removes the entire type entry
+     *
+     * **Safe to Call Multiple Times**:
+     * This method is idempotent - calling it multiple times with the same handler is safe.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to stop listening for
+     * @param handler - The exact handler function that was passed to listen()
+     *
+     * @example
+     * ```typescript
+     * // Register a handler
+     * const handleInit = (payload) => console.log('Game initialized')
+     * messaging.listen(MessageEvents.INIT, handleInit)
+     *
+     * // Later, remove the handler
+     * messaging.unlisten(MessageEvents.INIT, handleInit)
+     *
+     * // Safe to call multiple times
+     * messaging.unlisten(MessageEvents.INIT, handleInit) // No error
+     * ```
+     */
+    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    /**
+     * **Get Messaging Context Method**
+     *
+     * Analyzes the current runtime environment and message type to determine the appropriate
+     * transport method and configuration for sending messages.
+     *
+     * **Runtime Environment Detection**:
+     * The method detects whether the code is running in an iframe by comparing:
+     * - `window.self`: Reference to the current window
+     * - `window.top`: Reference to the topmost window in the hierarchy
+     *
+     * If they're different, we're in an iframe. If they're the same, we're in the top-level window.
+     *
+     * **Message Direction Analysis**:
+     * Different message types flow in different directions:
+     * - **Game → Parent**: READY, EXIT, TELEMETRY (use postMessage when in iframe)
+     * - **Parent → Game**: INIT, TOKEN_REFRESH, PAUSE, etc. (use CustomEvent in local dev, or postMessage with target)
+     *
+     * **Cross-Context Communication**:
+     * The messaging system supports cross-context targeting through the optional `target` parameter.
+     * When a target window is specified, postMessage is used regardless of the current context.
+     * This enables parent-to-iframe communication through the unified messaging API.
+     *
+     * **Transport Selection Logic**:
+     * - **postMessage**: Used when game is in iframe AND sending to parent, OR when target window is specified
+     * - **CustomEvent**: Used for all other cases (local development, same-context communication)
+     *
+     * **Security Considerations**:
+     * The origin is currently set to '*' for development convenience, but should be
+     * configurable for production security.
+     *
+     * @param eventType - The message event type being sent
+     * @returns Configuration object with transport method and target information
+     *
+     * @example
+     * ```typescript
+     * // In iframe sending READY to parent
+     * const context = getMessagingContext(MessageEvents.READY)
+     * // Returns: { shouldUsePostMessage: true, target: window.parent, origin: '*' }
+     *
+     * // In same context sending INIT
+     * const context = getMessagingContext(MessageEvents.INIT)
+     * // Returns: { shouldUsePostMessage: false, target: undefined, origin: '*' }
+     * ```
+     */
+    private getMessagingContext;
+    /**
+     * **Send Via PostMessage Method**
+     *
+     * Sends a message using the browser's postMessage API for iframe-to-parent communication.
+     * This method is used when the game is running in an iframe and needs to communicate
+     * with the parent window (the Playcademy shell).
+     *
+     * **PostMessage Protocol**:
+     * The postMessage API is the standard way for iframes to communicate with their parent.
+     * It's secure, cross-origin capable, and designed specifically for this use case.
+     *
+     * **Message Structure**:
+     * The method creates a message object with the following structure:
+     * - `type`: The message event type (e.g., 'PLAYCADEMY_READY')
+     * - `payload`: The message data (if any)
+     *
+     * **Payload Handling**:
+     * - **All payloads**: Wrapped in a `payload` property for consistency (e.g., { type, payload: data })
+     * - **Undefined payloads**: Only the type is sent (e.g., { type })
+     *
+     * **Security**:
+     * The origin parameter controls which domains can receive the message.
+     * Currently set to '*' for development, but should be restricted in production.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send
+     * @param payload - The data to send with the message
+     * @param target - The target window (defaults to parent window)
+     * @param origin - The allowed origin for the message (defaults to '*')
+     *
+     * @example
+     * ```typescript
+     * // Send ready signal (no payload)
+     * sendViaPostMessage(MessageEvents.READY, undefined)
+     * // Sends: { type: 'PLAYCADEMY_READY' }
+     *
+     * // Send telemetry data (object payload)
+     * sendViaPostMessage(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', payload: { fps: 60, mem: 128 } }
+     *
+     * // Send overlay state (primitive payload)
+     * sendViaPostMessage(MessageEvents.OVERLAY, true)
+     * // Sends: { type: 'PLAYCADEMY_OVERLAY', payload: true }
+     * ```
+     */
+    private sendViaPostMessage;
+    /**
+     * **Send Via CustomEvent Method**
+     *
+     * Sends a message using the browser's CustomEvent API for local same-context communication.
+     * This method is used when both the sender and receiver are in the same window context,
+     * typically during local development or when the parent needs to send messages to the game.
+     *
+     * **CustomEvent Protocol**:
+     * CustomEvent is a browser API for creating and dispatching custom events within the same
+     * window context. It's simpler than postMessage but only works within the same origin/context.
+     *
+     * **Event Structure**:
+     * - **type**: The event name (e.g., 'PLAYCADEMY_INIT')
+     * - **detail**: The payload data attached to the event
+     *
+     * **When This Is Used**:
+     * - Local development when game and shell run in the same context
+     * - Parent-to-game communication (INIT, TOKEN_REFRESH, PAUSE, etc.)
+     * - Any scenario where postMessage isn't needed
+     *
+     * **Event Bubbling**:
+     * CustomEvents are dispatched on the window object and can be listened to by any
+     * code in the same context using `addEventListener(type, handler)`.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send (becomes the event name)
+     * @param payload - The data to send with the message (stored in event.detail)
+     *
+     * @example
+     * ```typescript
+     * // Send initialization data
+     * sendViaCustomEvent(MessageEvents.INIT, {
+     *   baseUrl: '/api',
+     *   token: 'abc123',
+     *   gameId: 'game-456'
+     * })
+     * // Creates: CustomEvent('PLAYCADEMY_INIT', { detail: { baseUrl, token, gameId } })
+     *
+     * // Send pause signal
+     * sendViaCustomEvent(MessageEvents.PAUSE, undefined)
+     * // Creates: CustomEvent('PLAYCADEMY_PAUSE', { detail: undefined })
+     *
+     * // Listeners can access the data via event.detail:
+     * window.addEventListener('PLAYCADEMY_INIT', (event) => {
+     *   console.log(event.detail.gameId) // 'game-456'
+     * })
+     * ```
+     */
+    private sendViaCustomEvent;
 }
 /**
- * Connection state payload.
- * Broadcast from platform to games when connection changes.
+ * **Playcademy Messaging Singleton**
+ *
+ * This is the main messaging instance used throughout the Playcademy platform.
+ * It's exported as a singleton to ensure consistent communication across all parts
+ * of the application.
+ *
+ * **Why a Singleton?**:
+ * - Ensures all parts of the app use the same messaging instance
+ * - Prevents conflicts between multiple messaging systems
+ * - Simplifies the API - no need to pass instances around
+ * - Maintains consistent event listener management
+ *
+ * **Usage in Different Contexts**:
+ *
+ * **In Games**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Tell parent we're ready
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for pause/resume
+ * messaging.listen(MessageEvents.PAUSE, () => game.pause())
+ * messaging.listen(MessageEvents.RESUME, () => game.resume())
+ * ```
+ *
+ * **In Parent Shell**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Send initialization data to game
+ * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId })
+ *
+ * // Listen for game events
+ * messaging.listen(MessageEvents.EXIT, () => closeGame())
+ * messaging.listen(MessageEvents.READY, () => showGame())
+ * ```
+ *
+ * **Automatic Transport Selection**:
+ * The messaging system automatically chooses the right transport method:
+ * - Uses postMessage when game is in iframe sending to parent
+ * - Uses CustomEvent for local development and parent-to-game communication
+ *
+ * **Type Safety**:
+ * All message sending and receiving is fully type-safe with TypeScript.
  */
-interface ConnectionStatePayload {
-    state: 'online' | 'offline' | 'degraded';
-    reason: string;
-}
+declare const messaging: PlaycademyMessaging;
 
 /**
- * SDK-specific API response types
+ * Auto-initializes a PlaycademyClient with context from the environment.
+ * Works in both iframe mode (production/development) and standalone mode (local dev).
+ *
+ * This is the recommended way to initialize the SDK as it automatically:
+ * - Detects the runtime environment (iframe vs standalone)
+ * - Configures the client with the appropriate context
+ * - Sets up event listeners for token refresh
+ * - Exposes the client for debugging in development mode
+ *
+ * @param options - Optional configuration overrides
+ * @param options.baseUrl - Override the base URL for API requests
+ * @returns Promise resolving to a fully initialized PlaycademyClient
+ * @throws Error if not running in a browser context
+ *
+ * @example
+ * ```typescript
+ * // Default initialization
+ * const client = await PlaycademyClient.init()
+ *
+ * // With custom base URL
+ * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
+ * ```
  */
-type LoginResponse = {
-    token: string;
-};
-type GameTokenResponse = {
-    token: string;
-    exp: number;
-};
-type StartSessionResponse = {
-    sessionId: string;
-};
-type InventoryMutationResponse = {
-    newTotal: number;
-};
+declare function init<T extends PlaycademyClient = PlaycademyClient>(this: new (...args: ConstructorParameters<typeof PlaycademyClient>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}): Promise<T>;
 
 /**
- * Realtime namespace types
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @param baseUrl - The base URL of the Playcademy API
+ * @param email - User's email address
+ * @param password - User's password
+ * @returns Promise resolving to authentication response with token
+ * @throws PlaycademyError if authentication fails or network error occurs
+ *
+ * @example
+ * ```typescript
+ * // Preferred approach:
+ * const client = new PlaycademyClient({ baseUrl: '/api' })
+ * const result = await client.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * })
+ *
+ * // Legacy approach (still works):
+ * try {
+ *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
+ *   const client = new PlaycademyClient({ token: response.token })
+ * } catch (error) {
+ *   console.error('Login failed:', error.message)
+ * }
+ * ```
  */
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+
 /**
- * Response type for the realtime token API
+ * @fileoverview Authentication Strategy Pattern
+ *
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
  */
-interface RealtimeTokenResponse {
-    token: string;
-}
 
 /**
- * Scores namespace types
+ * Base interface for authentication strategies
  */
-interface ScoreSubmission {
-    id: string;
-    score: number;
-    achievedAt: Date;
+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>;
 }
 
 /**
- * Users namespace types
+ * 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).
  */
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+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;
+    /**
+     * 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;
+    /**
+     * 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;
+    }): 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>, raw?: boolean): 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;
+    /**
+     * Initializes an internal game session for automatic session management.
+     */
+    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>;
+        };
+    };
 }
 
 /**
- * Authentication namespace types
+ * Playcademy SDK client for game developers.
+ * Provides namespaced access to platform features for games running inside Cademy.
  */
-
-type AuthProviderType = (typeof AUTH_PROVIDER_IDS)[keyof typeof AUTH_PROVIDER_IDS];
-interface AuthOptions {
-    /** The identity provider to use for authentication */
-    provider: AuthProviderType;
-    /** The OAuth callback URL where your server handles the callback */
-    callbackUrl: string;
-    /** Authentication mode - auto detects best option based on context */
-    mode?: 'auto' | 'popup' | 'redirect';
-    /** Callback for authentication state changes */
-    onStateChange?: (state: AuthStateUpdate) => void;
-    /** Custom OAuth configuration (for users embedding the SDK outside of the Playcademy platform) */
-    oauth?: {
-        clientId: string;
-        authorizationEndpoint?: string;
-        tokenEndpoint?: string;
-        scope?: string;
+declare class PlaycademyClient extends PlaycademyBaseClient {
+    /**
+     * Connect external identity providers to the user's Playcademy account.
+     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
+     */
+    identity: {
+        connect: (options: AuthOptions) => Promise<AuthResult>;
+        _getContext: () => {
+            isInIframe: boolean;
+        };
     };
     /**
-     * Optional custom data to encode in OAuth state parameter.
-     * By default, the SDK automatically includes playcademy_user_id and game_id.
-     * Use this to add additional custom data if needed.
+     * Game runtime lifecycle and asset loading.
+     * - `exit()` - Return to Cademy hub
+     * - `getGameToken()` - Get short-lived auth token
+     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
+     * - `on('pause')`, `on('resume')` - Handle visibility changes
      */
-    stateData?: Record<string, string>;
-}
-interface AuthStateUpdate {
-    /** Current status of the authentication flow */
-    status: 'opening_popup' | 'exchanging_token' | 'complete' | 'error';
-    /** Human-readable message about the current state */
-    message: string;
-    /** Error details if status is 'error' */
-    error?: Error;
-}
-interface AuthResult {
-    /** Whether authentication was successful */
-    success: boolean;
-    /** User information if authentication was successful */
-    user?: UserInfo;
-    /** Error if authentication failed */
-    error?: Error;
-}
-/**
- * Better-auth sign-in response
- */
-interface BetterAuthSignInResponse {
-    token: string;
-    user: {
-        id: string;
-        email: string;
+    runtime: {
+        getGameToken: (gameId: string, options?: {
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
+        exit: () => Promise<void>;
+        onInit: (handler: (context: GameContextPayload) => void) => void;
+        onTokenRefresh: (handler: (data: {
+            token: string;
+            exp: number;
+        }) => void) => void;
+        onPause: (handler: () => void) => void;
+        onResume: (handler: () => void) => void;
+        onForceExit: (handler: () => void) => void;
+        onOverlay: (handler: (isVisible: boolean) => void) => void;
+        ready: () => void;
+        sendTelemetry: (data: {
+            fps: number;
+            mem: number;
+        }) => void;
+        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
+            token: string;
+            exp: number;
+        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
+        removeAllListeners: () => void;
+        getListenerCounts: () => Record<string, number>;
+        assets: {
+            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+            fetch: (path: string, options?: RequestInit) => Promise<Response>;
+            json: <T = unknown>(path: string) => Promise<T>;
+            blob: (path: string) => Promise<Blob>;
+            text: (path: string) => Promise<string>;
+            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
+        };
     };
-    expiresAt: string;
-}
-/**
- * Better-auth API key creation response
- */
-interface BetterAuthApiKeyResponse {
-    apiKey: string;
-    key: {
-        id: string;
-        name: string | null;
-        expiresAt: string | null;
-        createdAt: string;
+    /**
+     * TimeBack integration for activity tracking and user context.
+     *
+     * User context (cached from init, refreshable):
+     * - `user.role` - User's role (student, parent, teacher, etc.)
+     * - `user.enrollments` - Courses the player is enrolled in for this game
+     * - `user.organizations` - Schools/districts the player belongs to
+     * - `user.fetch()` - Refresh user context from server
+     *
+     * Activity tracking:
+     * - `startActivity(metadata)` - Begin tracking an activity
+     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
+     * - `endActivity(scoreData)` - Submit activity results to TimeBack
+     */
+    timeback: {
+        readonly user: TimebackUser;
+        startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
+        pauseActivity: () => void;
+        resumeActivity: () => void;
+        endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
     };
-}
-/**
- * Better-auth API key list item
- */
-interface BetterAuthApiKey {
-    id: string;
-    name: string | null;
-    start: string;
-    enabled: boolean;
-    expiresAt: string | null;
-    createdAt: string;
-    updatedAt: string;
-    lastRequest: string | null;
-    requestCount: number;
-}
-
-/**
- * Character namespace types
- */
-interface CharacterComponentsOptions {
     /**
-     * Optional level filter for components
-     * When provided, only components available at this level or below are returned
+     * Playcademy Credits (platform currency) management.
+     * - `get()` - Get user's credit balance
+     * - `add(amount)` - Award credits to user
      */
-    level?: number;
+    credits: {
+        balance: () => Promise<number>;
+        add: (amount: number) => Promise<number>;
+        spend: (amount: number) => Promise<number>;
+    };
     /**
-     * Whether to bypass the cache and force a fresh API request
-     * Default: false (use cache when available)
+     * Game score submission and leaderboards.
+     * - `submit(gameId, score, metadata?)` - Record a game score
      */
-    skipCache?: boolean;
-}
-interface CreateCharacterData {
-    bodyComponentId: string;
-    eyesComponentId: string;
-    hairstyleComponentId: string;
-    outfitComponentId: string;
-}
-interface UpdateCharacterData {
-    bodyComponentId?: string;
-    eyesComponentId?: string;
-    hairstyleComponentId?: string;
-    outfitComponentId?: string;
+    scores: {
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
+    };
+    /**
+     * Realtime multiplayer authentication.
+     * - `getToken()` - Get token for WebSocket/realtime connections
+     */
+    realtime: {
+        token: {
+            get: () => Promise<RealtimeTokenResponse>;
+        };
+    };
+    /**
+     * Make requests to your game's custom backend API routes.
+     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
+     * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
+     */
+    backend: {
+        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
+        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+    };
+    /** Auto-initializes a PlaycademyClient with context from the environment */
+    static init: typeof init;
+    /** Authenticates a user with email and password */
+    static login: typeof login;
+    /** Static identity utilities for OAuth operations */
+    static identity: {
+        parseOAuthState: typeof parseOAuthState;
+    };
 }
 
 /**
- * Developer namespace types
+ * Type definitions for the game timeback namespace.
+ *
+ * Re-exports core types from @playcademy/data for SDK consumers,
+ * plus SDK-specific types like TimebackInitContext.
  */
+
 /**
- * Bucket file metadata
+ * A TimeBack enrollment for the current game session.
+ * Alias for UserEnrollment without the optional gameId.
  */
-interface BucketFile {
-    key: string;
-    size: number;
-    uploaded: string;
-    contentType?: string;
-}
-type DevUploadEvent = {
-    type: 'init';
-} | {
-    type: 's3Progress';
-    loaded: number;
-    total: number;
-    percent: number;
-} | {
-    type: 'finalizeStart';
-} | {
-    type: 'finalizeProgress';
-    percent: number;
-    currentFileLabel?: string;
-} | {
-    type: 'finalizeStatus';
-    message: string;
-} | {
-    type: 'close';
-};
-type DevUploadHooks = {
-    onEvent?: (e: DevUploadEvent) => void;
-    onClose?: () => void;
-};
-
+type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
- * Platform TimeBack Types
- *
- * Types for TimeBack enrollment and student data on the platform side.
- * These are used by the cademy hub to determine which games users have access to.
+ * A TimeBack organization (school/district) for the current user.
+ * Alias for UserOrganization.
  */
-
+type TimebackOrganization = UserOrganization;
 /**
- * Enrollment data for a student in a specific game/course.
- * Represents the mapping between a TimeBack course and a Playcademy game.
+ * TimeBack context passed during game initialization.
+ * This is sent from the platform (cademy) to the game iframe via postMessage.
  */
-interface StudentEnrollment {
-    /** The Playcademy game ID the student is enrolled in */
-    gameId: string;
-    /** The grade level for this enrollment */
-    grade: number;
-    /** The subject area (e.g., 'Math', 'Science') */
-    subject: string;
-    /** The TimeBack course ID */
-    courseId: string;
+interface TimebackInitContext {
+    /** User's TimeBack ID */
+    id: string;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's enrollments for this game (one per grade/subject combo) */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
 }
 /**
- * Response from the enrollments endpoint
+ * TimeBack user context with current data (may be stale from init).
+ * Use `fetch()` to get fresh data from the server.
  */
-interface EnrollmentsResponse {
-    enrollments: StudentEnrollment[];
+interface TimebackUserContext {
+    /** User's TimeBack ID */
+    id: string | undefined;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole | undefined;
+    /** User's enrollments for this game */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
 }
 /**
- * Combined response type for xp.summary() method
+ * TimeBack user object with both cached getters and fetch method.
  */
-interface XpSummaryResponse {
-    today: TodayXpResponse;
-    total: TotalXpResponse;
+interface TimebackUser extends TimebackUserContext {
+    /**
+     * Fetch TimeBack data from the server (cached for 5 min).
+     * Updates the cached values so subsequent property access returns fresh data.
+     * @param options - Cache options (pass { force: true } to bypass cache)
+     * @returns Promise resolving to fresh user context
+     */
+    fetch(options?: {
+        force?: boolean;
+    }): Promise<TimebackUserContext>;
+}
+
+/**
+ * Core client configuration and lifecycle types
+ */
+
+type TokenType = 'session' | 'apiKey' | 'gameJwt';
+interface ClientConfig {
+    baseUrl: string;
+    gameUrl?: string;
+    token?: string;
+    tokenType?: TokenType;
+    gameId?: string;
+    autoStartSession?: boolean;
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
 }
-
 /**
- * @fileoverview Server SDK Type Definitions
- *
- * TypeScript type definitions for the server-side Playcademy SDK.
- * Includes configuration types, client state, and re-exported TimeBack types.
+ * Handler called when connection state changes to offline or degraded.
+ * Games can implement this to handle disconnects gracefully.
  */
-
+type DisconnectHandler = (context: DisconnectContext) => void | Promise<void>;
 /**
- * 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}
+ * Context provided to disconnect handlers
  */
-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>;
+interface DisconnectContext {
+    /** Current connection state */
+    state: 'offline' | 'degraded';
+    /** Reason for the disconnect */
+    reason: string;
+    /** Timestamp when disconnect was detected */
+    timestamp: number;
+    /** Utility to display a platform-level alert */
+    displayAlert: (message: string, options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    }) => void;
 }
-/**
- * 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;
+interface InitPayload {
+    /** Hub API base URL */
+    baseUrl: string;
+    /** Game deployment URL (serves both frontend assets and backend API) */
+    gameUrl?: string;
+    /** Short-lived game token */
+    token: string;
+    /** Game ID */
+    gameId: string;
+    /** Realtime WebSocket URL */
+    realtimeUrl?: string;
+    /** Timeback context (if user has a Timeback account) */
+    timeback?: TimebackInitContext;
 }
 /**
- * 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.
+ * Simplified user data passed to games via InitPayload
+ * This is a subset of AuthenticatedUser suitable for external game consumption
  */
-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;
+interface GameUser {
+    /** Playcademy user ID */
+    id: string;
+    /** Unique username */
+    username: string | null;
+    /** Display name */
+    name: string | null;
+    /** Email address */
+    email: string | null;
+    /** Profile image URL */
+    image: string | null;
+    /** Whether the user has a Timeback account */
+    hasTimebackAccount: boolean;
 }
-/**
- * Custom API routes integration
- */
-interface CustomRoutesIntegration {
-    /** Directory for custom API routes (defaults to 'server/api') */
-    directory?: string;
+type GameContextPayload = {
+    token: string;
+    baseUrl: string;
+    realtimeUrl: string;
+    gameId: string;
+    forwardKeys?: string[];
+};
+type EventListeners = {
+    [E in keyof ClientEvents]?: Array<(payload: ClientEvents[E]) => void>;
+};
+interface ClientEvents {
+    authChange: {
+        token: string | null;
+    };
+    inventoryChange: {
+        itemId: string;
+        delta: number;
+        newTotal: number;
+    };
+    levelUp: {
+        oldLevel: number;
+        newLevel: number;
+        creditsAwarded: number;
+    };
+    xpGained: {
+        amount: number;
+        totalXP: number;
+        leveledUp: boolean;
+    };
+    connectionChange: {
+        state: 'online' | 'offline' | 'degraded';
+        reason: string;
+    };
 }
+
 /**
- * Database integration
+ * Event and message payload types for SDK messaging system
  */
-interface DatabaseIntegration {
-    /** Database directory (defaults to 'db') */
-    directory?: string;
+
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
 }
 /**
- * Integrations configuration
- * All backend features (database, custom routes, external services) are configured here
+ * Authentication state change event payload.
+ * Used when authentication state changes in the application.
  */
-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;
+interface AuthStateChangePayload {
+    /** Whether the user is currently authenticated */
+    authenticated: boolean;
+    /** User information if authenticated, null otherwise */
+    user: UserInfo | null;
+    /** Error information if authentication failed */
+    error: Error | null;
 }
 /**
- * Unified Playcademy configuration
- * Used for playcademy.config.{js,json}
+ * OAuth callback event payload.
+ * Used when OAuth flow completes in popup/new-tab windows.
  */
-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;
+interface AuthCallbackPayload {
+    /** OAuth authorization code */
+    code: string;
+    /** OAuth state parameter for CSRF protection */
+    state: string;
+    /** Error message if OAuth flow failed */
+    error: string | null;
 }
-
 /**
- * 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'
- * }
- * ```
+ * Message sent from server callback to opener window.
+ * This is the standardized format from our server-first architecture.
  */
-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;
+interface AuthServerMessage {
+    /** Type of the message */
+    type: 'PLAYCADEMY_AUTH_STATE_CHANGE';
+    /** Whether the user is currently authenticated */
+    authenticated: boolean;
+    /** Whether the authentication was successful */
+    success: boolean;
+    /** Timestamp of the message */
+    ts: number;
+    /** User information if authentication was successful */
+    user?: UserInfo;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Token refresh event payload.
+ * Sent when authentication token is updated.
+ */
+interface TokenRefreshPayload {
+    /** New authentication token */
+    token: string;
+    /** Token expiration timestamp */
+    exp: number;
 }
 /**
- * Internal state maintained by the PlaycademyClient instance.
- *
- * @internal
+ * Telemetry event payload.
+ * Performance metrics sent from the game.
  */
-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;
+interface TelemetryPayload {
+    /** Frames per second */
+    fps: number;
+    /** Memory usage in MB */
+    mem: number;
 }
-
 /**
- * Resource bindings for backend deployment
- * Provider-agnostic abstraction for cloud resources
+ * Keyboard event payload.
+ * Key events forwarded from the game.
  */
-interface BackendResourceBindings {
-    /** SQL database instances to create and bind (maps to D1 on Cloudflare) */
-    database?: string[];
-    /** Key-value store namespaces to create and bind (maps to KV on Cloudflare) */
-    keyValue?: string[];
-    /** Object storage buckets to bind (maps to R2 on Cloudflare) */
-    bucket?: string[];
+interface KeyEventPayload {
+    /** Key value (e.g., 'Escape', 'F1') */
+    key: string;
+    /** Key code (optional) */
+    code?: string;
+    /** Event type */
+    type: 'keydown' | 'keyup';
 }
 /**
- * Backend deployment bundle for uploading to Playcademy platform
+ * Connection state payload.
+ * Broadcast from platform to games when connection changes.
  */
-interface BackendDeploymentBundle {
-    /** Bundled JavaScript code ready for deployment */
-    code: string;
-    /** Game configuration */
-    config: PlaycademyConfig;
-    /** Optional resource bindings (database, storage, etc.) */
-    bindings?: BackendResourceBindings;
-    /** Optional schema information for database setup */
-    schema?: SchemaInfo;
-    /** Optional game secrets */
-    secrets?: Record<string, string>;
+interface ConnectionStatePayload {
+    state: 'online' | 'offline' | 'degraded';
+    reason: string;
 }
 
 /**
- * Connection Manager
- *
- * Manages connection monitoring and integrates it with the Playcademy client.
- * Handles event wiring, state management, and disconnect callbacks.
- *
- * In iframe mode, disables local monitoring and listens to platform connection
- * state broadcasts instead (avoids duplicate heartbeats).
+ * SDK-specific API response types
  */
+type LoginResponse = {
+    token: string;
+};
+type GameTokenResponse = {
+    token: string;
+    exp: number;
+};
+type StartSessionResponse = {
+    sessionId: string;
+};
+type InventoryMutationResponse = {
+    newTotal: number;
+};
 
 /**
- * Configuration for the ConnectionManager.
+ * Realtime namespace types
  */
-interface ConnectionManagerConfig {
-    /** Base URL for API requests (used for heartbeat pings) */
-    baseUrl: string;
-    /** Authentication context (iframe vs standalone) for alert routing */
-    authContext?: {
-        isInIframe: boolean;
-    };
-    /** Handler to call when connection issues are detected */
-    onDisconnect?: DisconnectHandler;
-    /** Callback to emit connection change events to the client */
-    onConnectionChange?: (state: ConnectionState, reason: string) => void;
+/**
+ * Response type for the realtime token API
+ */
+interface RealtimeTokenResponse {
+    token: string;
 }
+
 /**
- * Manages connection monitoring for the Playcademy client.
- *
- * The ConnectionManager serves as an integration layer between the low-level
- * ConnectionMonitor and the PlaycademyClient. It handles:
- * - Event wiring and coordination
- * - Disconnect callbacks with context
- * - Platform-level alert integration
- * - Request success/failure tracking
- *
- * This class is used internally by PlaycademyClient and typically not
- * instantiated directly by game developers.
- *
- * @see {@link ConnectionMonitor} for the underlying monitoring implementation
- * @see {@link PlaycademyClient.onDisconnect} for the public API
+ * Scores namespace types
  */
-declare class ConnectionManager {
-    private monitor?;
-    private authContext?;
-    private disconnectHandler?;
-    private connectionChangeCallback?;
-    private currentState;
-    private additionalDisconnectHandlers;
-    /**
-     * Creates a new ConnectionManager instance.
-     *
-     * @param config - Configuration options for the manager
-     *
-     * @example
-     * ```typescript
-     * const manager = new ConnectionManager({
-     *   baseUrl: 'https://api.playcademy.com',
-     *   authContext: { isInIframe: false },
-     *   onDisconnect: (context) => {
-     *     console.log(`Disconnected: ${context.state}`)
-     *   },
-     *   onConnectionChange: (state, reason) => {
-     *     console.log(`Connection changed: ${state}`)
-     *   }
-     * })
-     * ```
-     */
-    constructor(config: ConnectionManagerConfig);
-    /**
-     * Gets the current connection state.
-     *
-     * @returns The current connection state ('online', 'offline', or 'degraded')
-     *
-     * @example
-     * ```typescript
-     * const state = manager.getState()
-     * if (state === 'offline') {
-     *   console.log('No connection')
-     * }
-     * ```
-     */
-    getState(): ConnectionState;
-    /**
-     * Manually triggers a connection check immediately.
-     *
-     * Forces a heartbeat ping to verify the current connection status.
-     * Useful when you need to check connectivity before a critical operation.
-     *
-     * In iframe mode, this returns the last known state from platform.
-     *
-     * @returns Promise resolving to the current connection state
-     *
-     * @example
-     * ```typescript
-     * const state = await manager.checkNow()
-     * if (state === 'online') {
-     *   await performCriticalOperation()
-     * }
-     * ```
-     */
-    checkNow(): Promise<ConnectionState>;
-    /**
-     * Reports a successful API request to the connection monitor.
-     *
-     * This resets the consecutive failure counter and transitions from
-     * 'degraded' to 'online' state if applicable.
-     *
-     * Typically called automatically by the SDK's request wrapper.
-     * No-op in iframe mode (platform handles monitoring).
-     */
-    reportRequestSuccess(): void;
-    /**
-     * Reports a failed API request to the connection monitor.
-     *
-     * Only network errors are tracked (not 4xx/5xx HTTP responses).
-     * After consecutive failures exceed the threshold, the state transitions
-     * to 'degraded' or 'offline'.
-     *
-     * Typically called automatically by the SDK's request wrapper.
-     * No-op in iframe mode (platform handles monitoring).
-     *
-     * @param error - The error from the failed request
-     */
-    reportRequestFailure(error: unknown): void;
-    /**
-     * Registers a callback to be called when connection issues are detected.
-     *
-     * The callback only fires for 'offline' and 'degraded' states, not when
-     * recovering to 'online'. This provides a clean API for games to handle
-     * disconnect scenarios without being notified of every state change.
-     *
-     * Works in both iframe and standalone modes transparently.
-     *
-     * @param callback - Function to call when connection degrades
-     * @returns Cleanup function to unregister the callback
-     *
-     * @example
-     * ```typescript
-     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
-     *   if (state === 'offline') {
-     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
-     *     saveGameState()
-     *   }
-     * })
-     *
-     * // Later: cleanup() to unregister
-     * ```
-     */
-    onDisconnect(callback: DisconnectHandler): () => void;
-    /**
-     * Stops connection monitoring and performs cleanup.
-     *
-     * Removes event listeners and clears heartbeat intervals.
-     * Should be called when the client is being destroyed.
-     */
-    stop(): void;
-    /**
-     * Sets up listener for platform connection state broadcasts (iframe mode only).
-     */
-    private _setupPlatformListener;
-    /**
-     * Handles connection state changes from the monitor or platform.
-     *
-     * Coordinates between:
-     * 1. Emitting events to the client (for client.on('connectionChange'))
-     * 2. Calling the disconnect handler if configured
-     * 3. Calling any additional handlers registered via onDisconnect()
-     *
-     * @param state - The new connection state
-     * @param reason - Human-readable reason for the state change
-     */
-    private _handleConnectionChange;
+interface ScoreSubmission {
+    id: string;
+    score: number;
+    achievedAt: Date;
 }
 
 /**
- * @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
+ * Users namespace types
  */
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
 
 /**
- * Enumeration of all message types used in the Playcademy messaging system.
- *
- * **Message Flow Patterns**:
- *
- * **Parent → Game (Overworld → Game)**:
- * - INIT: Provides game with authentication token and configuration
- * - TOKEN_REFRESH: Updates game's authentication token before expiry
- * - PAUSE/RESUME: Controls game execution state
- * - FORCE_EXIT: Immediately terminates the game
- * - OVERLAY: Shows/hides UI overlays over the game
- *
- * **Game → Parent (Game → Overworld)**:
- * - READY: Game has loaded and is ready to receive messages
- * - EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
- * - TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)
+ * Authentication namespace types
  */
-declare enum MessageEvents {
-    /**
-     * Initializes the game with authentication context and configuration.
-     * Sent immediately after game iframe loads.
-     * Payload:
-     * - `baseUrl`: string
-     * - `token`: string
-     * - `gameId`: string
-     */
-    INIT = "PLAYCADEMY_INIT",
-    /**
-     * Updates the game's authentication token before it expires.
-     * Sent periodically to maintain valid authentication.
-     * Payload:
-     * - `token`: string
-     * - `exp`: number
-     */
-    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
-    /**
-     * Pauses game execution (e.g., when user switches tabs).
-     * Game should pause timers, animations, and user input.
-     * Payload: void
-     */
-    PAUSE = "PLAYCADEMY_PAUSE",
-    /**
-     * Resumes game execution after being paused.
-     * Game should restore timers, animations, and user input.
-     * Payload: void
-     */
-    RESUME = "PLAYCADEMY_RESUME",
-    /**
-     * Forces immediate game termination (emergency exit).
-     * Game should clean up resources and exit immediately.
-     * Payload: void
-     */
-    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
-    /**
-     * Shows or hides UI overlays over the game.
-     * Game may need to pause or adjust rendering accordingly.
-     * Payload: boolean (true = show overlay, false = hide overlay)
-     */
-    OVERLAY = "PLAYCADEMY_OVERLAY",
-    /**
-     * Broadcasts connection state changes to games.
-     * Sent by platform when network connectivity changes.
-     * Payload:
-     * - `state`: 'online' | 'offline' | 'degraded'
-     * - `reason`: string
-     */
-    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
-    /**
-     * Game has finished loading and is ready to receive messages.
-     * Sent once after game initialization is complete.
-     * Payload: void
-     */
-    READY = "PLAYCADEMY_READY",
-    /**
-     * Game requests to be closed/exited.
-     * Sent when user clicks exit button or game naturally ends.
-     * Payload: void
-     */
-    EXIT = "PLAYCADEMY_EXIT",
-    /**
-     * Game reports performance telemetry data.
-     * Sent periodically for monitoring and analytics.
-     * Payload:
-     * - `fps`: number
-     * - `mem`: number
-     */
-    TELEMETRY = "PLAYCADEMY_TELEMETRY",
+
+type AuthProviderType = (typeof AUTH_PROVIDER_IDS)[keyof typeof AUTH_PROVIDER_IDS];
+interface AuthOptions {
+    /** The identity provider to use for authentication */
+    provider: AuthProviderType;
+    /** The OAuth callback URL where your server handles the callback */
+    callbackUrl: string;
+    /** Authentication mode - auto detects best option based on context */
+    mode?: 'auto' | 'popup' | 'redirect';
+    /** Callback for authentication state changes */
+    onStateChange?: (state: AuthStateUpdate) => void;
+    /** Custom OAuth configuration (for users embedding the SDK outside of the Playcademy platform) */
+    oauth?: {
+        clientId: string;
+        authorizationEndpoint?: string;
+        tokenEndpoint?: string;
+        scope?: string;
+    };
     /**
-     * Game reports key events to parent.
-     * Sent when certain keys are pressed within the game iframe.
-     * Payload:
-     * - `key`: string
-     * - `code?`: string
-     * - `type`: 'keydown' | 'keyup'
+     * Optional custom data to encode in OAuth state parameter.
+     * By default, the SDK automatically includes playcademy_user_id and game_id.
+     * Use this to add additional custom data if needed.
      */
-    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
+    stateData?: Record<string, string>;
+}
+interface AuthStateUpdate {
+    /** Current status of the authentication flow */
+    status: 'opening_popup' | 'exchanging_token' | 'complete' | 'error';
+    /** Human-readable message about the current state */
+    message: string;
+    /** Error details if status is 'error' */
+    error?: Error;
+}
+interface AuthResult {
+    /** Whether authentication was successful */
+    success: boolean;
+    /** User information if authentication was successful */
+    user?: UserInfo;
+    /** Error if authentication failed */
+    error?: Error;
+}
+/**
+ * Better-auth sign-in response
+ */
+interface BetterAuthSignInResponse {
+    token: string;
+    user: {
+        id: string;
+        email: string;
+    };
+    expiresAt: string;
+}
+/**
+ * Better-auth API key creation response
+ */
+interface BetterAuthApiKeyResponse {
+    apiKey: string;
+    key: {
+        id: string;
+        name: string | null;
+        expiresAt: string | null;
+        createdAt: string;
+    };
+}
+/**
+ * Better-auth API key list item
+ */
+interface BetterAuthApiKey {
+    id: string;
+    name: string | null;
+    start: string;
+    enabled: boolean;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastRequest: string | null;
+    requestCount: number;
+}
+
+/**
+ * Character namespace types
+ */
+interface CharacterComponentsOptions {
     /**
-     * Game requests platform to display an alert.
-     * Sent when connection issues are detected or other important events occur.
-     * Payload:
-     * - `message`: string
-     * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
+     * Optional level filter for components
+     * When provided, only components available at this level or below are returned
      */
-    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
+    level?: number;
     /**
-     * Notifies about authentication state changes.
-     * Can be sent in both directions depending on auth flow.
-     * Payload:
-     * - `authenticated`: boolean
-     * - `user`: UserInfo | null
-     * - `error`: Error | null
+     * Whether to bypass the cache and force a fresh API request
+     * Default: false (use cache when available)
      */
-    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
+    skipCache?: boolean;
+}
+interface CreateCharacterData {
+    bodyComponentId: string;
+    eyesComponentId: string;
+    hairstyleComponentId: string;
+    outfitComponentId: string;
+}
+interface UpdateCharacterData {
+    bodyComponentId?: string;
+    eyesComponentId?: string;
+    hairstyleComponentId?: string;
+    outfitComponentId?: string;
+}
+
+/**
+ * Developer namespace types
+ */
+/**
+ * Bucket file metadata
+ */
+interface BucketFile {
+    key: string;
+    size: number;
+    uploaded: string;
+    contentType?: string;
+}
+type DevUploadEvent = {
+    type: 'init';
+} | {
+    type: 's3Progress';
+    loaded: number;
+    total: number;
+    percent: number;
+} | {
+    type: 'finalizeStart';
+} | {
+    type: 'finalizeProgress';
+    percent: number;
+    currentFileLabel?: string;
+} | {
+    type: 'finalizeStatus';
+    message: string;
+} | {
+    type: 'close';
+};
+type DevUploadHooks = {
+    onEvent?: (e: DevUploadEvent) => void;
+    onClose?: () => void;
+};
+
+/**
+ * Platform TimeBack Types
+ *
+ * Types for TimeBack data on the platform side.
+ * Unlike game types, these include gameId for cross-game enrollment views.
+ */
+
+/**
+ * Platform TimeBack user context.
+ * Unlike game context, enrollments include gameId for cross-game views.
+ */
+interface PlatformTimebackUserContext {
+    /** User's TimeBack ID */
+    id: string | undefined;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole | undefined;
+    /** User's enrollments across ALL games (includes gameId) */
+    enrollments: UserEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: UserOrganization[];
+}
+/**
+ * Platform TimeBack user object with both cached getters and fetch method.
+ */
+interface PlatformTimebackUser extends PlatformTimebackUserContext {
     /**
-     * OAuth callback data from popup/new-tab windows.
-     * Sent from popup window back to parent after OAuth completes.
-     * Payload:
-     * - `code`: string (OAuth authorization code)
-     * - `state`: string (OAuth state for CSRF protection)
-     * - `error`: string | null (OAuth error if any)
+     * Fetch TimeBack data from the server (cached for 5 min).
+     * Updates the cached values so subsequent property access returns fresh data.
+     * @param options - Cache options (pass { force: true } to bypass cache)
+     * @returns Promise resolving to user context with full enrollment data
      */
-    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
+    fetch(options?: {
+        force?: boolean;
+    }): Promise<PlatformTimebackUserContext>;
 }
 /**
- * Type definition for message handler functions.
- * These functions are called when a specific message type is received.
- *
- * @template T - The type of payload data the handler expects
- * @param payload - The data sent with the message
+ * Combined response type for xp.summary() method
  */
-type MessageHandler<T = unknown> = (payload: T) => void;
+interface XpSummaryResponse {
+    today: TodayXpResponse;
+    total: TotalXpResponse;
+}
+
 /**
- * Type mapping that defines the payload structure for each message type.
- * This ensures type safety when sending and receiving messages.
- *
- * **Usage Examples**:
- * ```typescript
- * // Type-safe message sending
- * messaging.send(MessageEvents.INIT, { baseUrl: '/api', token: 'abc', gameId: '123' })
+ * @fileoverview Server SDK Type Definitions
  *
- * // Type-safe message handling
- * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
- *   console.log(`New token expires at: ${new Date(exp)}`)
- * })
- * ```
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
  */
-type MessageEventMap = {
-    /** Game initialization context with API endpoint, auth token, and game ID */
-    [MessageEvents.INIT]: GameContextPayload;
-    /** Token refresh data with new token and expiration timestamp */
-    [MessageEvents.TOKEN_REFRESH]: TokenRefreshPayload;
-    /** Pause message has no payload data */
-    [MessageEvents.PAUSE]: void;
-    /** Resume message has no payload data */
-    [MessageEvents.RESUME]: void;
-    /** Force exit message has no payload data */
-    [MessageEvents.FORCE_EXIT]: void;
-    /** Overlay visibility state (true = show, false = hide) */
-    [MessageEvents.OVERLAY]: boolean;
-    /** Connection state change from platform */
-    [MessageEvents.CONNECTION_STATE]: ConnectionStatePayload;
-    /** Ready message has no payload data */
-    [MessageEvents.READY]: void;
-    /** Exit message has no payload data */
-    [MessageEvents.EXIT]: void;
-    /** Performance telemetry data */
-    [MessageEvents.TELEMETRY]: TelemetryPayload;
-    /** Key event data */
-    [MessageEvents.KEY_EVENT]: KeyEventPayload;
-    /** Display alert request from game */
-    [MessageEvents.DISPLAY_ALERT]: DisplayAlertPayload;
-    /** Authentication state change notification */
-    [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
-    /** OAuth callback data from popup/new-tab windows */
-    [MessageEvents.AUTH_CALLBACK]: AuthCallbackPayload;
-};
+
 /**
- * **PlaycademyMessaging Class**
- *
- * This is the core messaging system that handles all communication in the Playcademy platform.
- * It automatically detects the runtime environment and chooses the appropriate transport method.
- *
- * **Key Features**:
- * 1. **Automatic Transport Selection**: Detects iframe vs local context and uses appropriate method
- * 2. **Type Safety**: Full TypeScript support with payload type checking
- * 3. **Bidirectional Communication**: Handles both parent→game and game→parent messages
- * 4. **Event Cleanup**: Proper listener management to prevent memory leaks
- *
- * **Transport Methods**:
- * - **postMessage**: Used for iframe-to-parent communication (production/development)
- * - **CustomEvent**: Used for local same-context communication (local development)
- *
- * **Runtime Detection Logic**:
- * - If `window.self !== window.top`: We're in an iframe, use postMessage
- * - If `window.self === window.top`: We're in the same context, use CustomEvent
+ * Base configuration for TimeBack integration (shared across all courses).
+ * References upstream TimeBack types from @playcademy/timeback.
  *
- * **Example Usage**:
- * ```typescript
- * // Send a message (automatically chooses transport)
- * messaging.send(MessageEvents.READY, undefined)
+ * 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.
  *
- * // Listen for messages (handles both transports)
- * messaging.listen(MessageEvents.INIT, (payload) => {
- *   console.log('Game initialized with:', payload)
- * })
+ * 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)
  *
- * // Clean up listeners
- * messaging.unlisten(MessageEvents.INIT, handler)
- * ```
+ * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
  */
-declare class PlaycademyMessaging {
-    /**
-     * Internal storage for message listeners.
-     *
-     * **Structure Explanation**:
-     * - Outer Map: MessageEvents → Map of handlers for that event type
-     * - Inner Map: MessageHandler → Object containing both listener types
-     * - Object: { postMessage: EventListener, customEvent: EventListener }
-     *
-     * **Why Two Listeners Per Handler?**:
-     * Since we don't know at registration time which transport will be used,
-     * we register both a postMessage listener and a CustomEvent listener.
-     * The appropriate one will be triggered based on the runtime context.
-     */
-    private listeners;
-    /**
-     * **Send Message Method**
-     *
-     * Sends a message using the appropriate transport method based on the runtime context.
-     * This is the main public API for sending messages in the Playcademy system.
-     *
-     * **How It Works**:
-     * 1. Analyzes the message type and current runtime context
-     * 2. Determines if we're in an iframe and if this message should use postMessage
-     * 3. Routes to the appropriate transport method (postMessage or CustomEvent)
-     *
-     * **Transport Selection Logic**:
-     * - **postMessage**: Used when game is in iframe and sending to parent, OR when target window is specified
-     * - **CustomEvent**: Used for local/same-context communication
-     *
-     * **Type Safety**:
-     * The generic type parameter `K` ensures that the payload type matches
-     * the expected type for the given message event.
-     *
-     * @template K - The message event type (ensures type safety)
-     * @param type - The message event type to send
-     * @param payload - The data to send with the message (type-checked)
-     * @param options - Optional configuration for message sending
-     *
-     * @example
-     * ```typescript
-     * // Send game ready signal (no payload)
-     * messaging.send(MessageEvents.READY, undefined)
-     *
-     * // Send telemetry data (typed payload)
-     * messaging.send(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
-     *
-     * // Send to specific iframe window (parent to iframe communication)
-     * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId }, {
-     *   target: iframe.contentWindow,
-     *   origin: '*'
-     * })
-     *
-     * // TypeScript will error if payload type is wrong
-     * messaging.send(MessageEvents.INIT, "wrong type") // ❌ Error
-     * ```
-     */
-    send<K extends MessageEvents>(type: K, payload: MessageEventMap[K], options?: {
-        target?: Window;
-        origin?: string;
-    }): void;
+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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 {
     /**
-     * **Listen for Messages Method**
-     *
-     * Registers a message listener that will be called when the specified message type is received.
-     * This method automatically handles both postMessage and CustomEvent sources.
-     *
-     * **Why Register Two Listeners?**:
-     * Since we don't know at registration time which transport method will be used to send
-     * messages, we register listeners for both possible sources:
-     * 1. **postMessage listener**: Handles messages from iframe-to-parent communication
-     * 2. **CustomEvent listener**: Handles messages from local same-context communication
-     *
-     * **Message Processing**:
-     * - **postMessage**: Extracts data from `event.data.payload` or `event.data`
-     * - **CustomEvent**: Extracts data from `event.detail`
-     *
-     * **Type Safety**:
-     * The handler function receives the correctly typed payload based on the message type.
-     *
-     * @template K - The message event type (ensures type safety)
-     * @param type - The message event type to listen for
-     * @param handler - Function to call when the message is received
-     *
-     * @example
-     * ```typescript
-     * // Listen for game initialization
-     * messaging.listen(MessageEvents.INIT, (payload) => {
-     *   // payload is automatically typed as GameContextPayload
-     *   console.log(`Game ${payload.gameId} initialized`)
-     *   console.log(`API base URL: ${payload.baseUrl}`)
-     * })
-     *
-     * // Listen for token refresh
-     * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
-     *   // payload is automatically typed as { token: string; exp: number }
-     *   updateAuthToken(token)
-     *   scheduleTokenRefresh(exp)
-     * })
-     * ```
+     * Playcademy API key for server-to-server authentication.
+     * Obtain from the Playcademy developer dashboard.
      */
-    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    apiKey: string;
     /**
-     * **Remove Message Listener Method**
-     *
-     * Removes a previously registered message listener to prevent memory leaks and unwanted callbacks.
-     * This method cleans up both the postMessage and CustomEvent listeners that were registered.
-     *
-     * **Why Clean Up Both Listeners?**:
-     * When we registered the listener with `listen()`, we created two browser event listeners:
-     * 1. A 'message' event listener for postMessage communication
-     * 2. A custom event listener for local CustomEvent communication
-     *
-     * Both must be removed to prevent memory leaks and ensure the handler is completely unregistered.
-     *
-     * **Memory Management**:
-     * - Removes both event listeners from the browser
-     * - Cleans up internal tracking maps
-     * - If no more handlers exist for a message type, removes the entire type entry
-     *
-     * **Safe to Call Multiple Times**:
-     * This method is idempotent - calling it multiple times with the same handler is safe.
-     *
-     * @template K - The message event type (ensures type safety)
-     * @param type - The message event type to stop listening for
-     * @param handler - The exact handler function that was passed to listen()
-     *
-     * @example
-     * ```typescript
-     * // Register a handler
-     * const handleInit = (payload) => console.log('Game initialized')
-     * messaging.listen(MessageEvents.INIT, handleInit)
-     *
-     * // Later, remove the handler
-     * messaging.unlisten(MessageEvents.INIT, handleInit)
+     * 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.
      *
-     * // Safe to call multiple times
-     * messaging.unlisten(MessageEvents.INIT, handleInit) // No error
-     * ```
+     * @example './config/playcademy.config.js'
      */
-    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    configPath?: string;
     /**
-     * **Get Messaging Context Method**
-     *
-     * Analyzes the current runtime environment and message type to determine the appropriate
-     * transport method and configuration for sending messages.
-     *
-     * **Runtime Environment Detection**:
-     * The method detects whether the code is running in an iframe by comparing:
-     * - `window.self`: Reference to the current window
-     * - `window.top`: Reference to the topmost window in the hierarchy
-     *
-     * If they're different, we're in an iframe. If they're the same, we're in the top-level window.
-     *
-     * **Message Direction Analysis**:
-     * Different message types flow in different directions:
-     * - **Game → Parent**: READY, EXIT, TELEMETRY (use postMessage when in iframe)
-     * - **Parent → Game**: INIT, TOKEN_REFRESH, PAUSE, etc. (use CustomEvent in local dev, or postMessage with target)
-     *
-     * **Cross-Context Communication**:
-     * The messaging system supports cross-context targeting through the optional `target` parameter.
-     * When a target window is specified, postMessage is used regardless of the current context.
-     * This enables parent-to-iframe communication through the unified messaging API.
-     *
-     * **Transport Selection Logic**:
-     * - **postMessage**: Used when game is in iframe AND sending to parent, OR when target window is specified
-     * - **CustomEvent**: Used for all other cases (local development, same-context communication)
-     *
-     * **Security Considerations**:
-     * The origin is currently set to '*' for development convenience, but should be
-     * configurable for production security.
-     *
-     * @param eventType - The message event type being sent
-     * @returns Configuration object with transport method and target information
-     *
-     * @example
-     * ```typescript
-     * // In iframe sending READY to parent
-     * const context = getMessagingContext(MessageEvents.READY)
-     * // Returns: { shouldUsePostMessage: true, target: window.parent, origin: '*' }
+     * Optional config object (for edge environments without filesystem).
+     * If provided, skips filesystem-based config loading.
      *
-     * // In same context sending INIT
-     * const context = getMessagingContext(MessageEvents.INIT)
-     * // Returns: { shouldUsePostMessage: false, target: undefined, origin: '*' }
-     * ```
+     * @example { name: 'My Game', integrations: { timeback: {...} } }
      */
-    private getMessagingContext;
+    config?: PlaycademyConfig;
     /**
-     * **Send Via PostMessage Method**
-     *
-     * Sends a message using the browser's postMessage API for iframe-to-parent communication.
-     * This method is used when the game is running in an iframe and needs to communicate
-     * with the parent window (the Playcademy shell).
-     *
-     * **PostMessage Protocol**:
-     * The postMessage API is the standard way for iframes to communicate with their parent.
-     * It's secure, cross-origin capable, and designed specifically for this use case.
-     *
-     * **Message Structure**:
-     * The method creates a message object with the following structure:
-     * - `type`: The message event type (e.g., 'PLAYCADEMY_READY')
-     * - `payload`: The message data (if any)
-     *
-     * **Payload Handling**:
-     * - **All payloads**: Wrapped in a `payload` property for consistency (e.g., { type, payload: data })
-     * - **Undefined payloads**: Only the type is sent (e.g., { type })
-     *
-     * **Security**:
-     * The origin parameter controls which domains can receive the message.
-     * Currently set to '*' for development, but should be restricted in production.
-     *
-     * @template K - The message event type (ensures type safety)
-     * @param type - The message event type to send
-     * @param payload - The data to send with the message
-     * @param target - The target window (defaults to parent window)
-     * @param origin - The allowed origin for the message (defaults to '*')
-     *
-     * @example
-     * ```typescript
-     * // Send ready signal (no payload)
-     * sendViaPostMessage(MessageEvents.READY, undefined)
-     * // Sends: { type: 'PLAYCADEMY_READY' }
-     *
-     * // Send telemetry data (object payload)
-     * sendViaPostMessage(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
-     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', payload: { fps: 60, mem: 128 } }
+     * Optional base URL for Playcademy API.
+     * Defaults to environment variables or 'https://hub.playcademy.net'.
      *
-     * // Send overlay state (primitive payload)
-     * sendViaPostMessage(MessageEvents.OVERLAY, true)
-     * // Sends: { type: 'PLAYCADEMY_OVERLAY', payload: true }
-     * ```
+     * @example 'http://localhost:3000' for local development
      */
-    private sendViaPostMessage;
+    baseUrl?: string;
     /**
-     * **Send Via CustomEvent Method**
-     *
-     * Sends a message using the browser's CustomEvent API for local same-context communication.
-     * This method is used when both the sender and receiver are in the same window context,
-     * typically during local development or when the parent needs to send messages to the game.
-     *
-     * **CustomEvent Protocol**:
-     * CustomEvent is a browser API for creating and dispatching custom events within the same
-     * window context. It's simpler than postMessage but only works within the same origin/context.
-     *
-     * **Event Structure**:
-     * - **type**: The event name (e.g., 'PLAYCADEMY_INIT')
-     * - **detail**: The payload data attached to the event
-     *
-     * **When This Is Used**:
-     * - Local development when game and shell run in the same context
-     * - Parent-to-game communication (INIT, TOKEN_REFRESH, PAUSE, etc.)
-     * - Any scenario where postMessage isn't needed
-     *
-     * **Event Bubbling**:
-     * CustomEvents are dispatched on the window object and can be listened to by any
-     * code in the same context using `addEventListener(type, handler)`.
-     *
-     * @template K - The message event type (ensures type safety)
-     * @param type - The message event type to send (becomes the event name)
-     * @param payload - The data to send with the message (stored in event.detail)
-     *
-     * @example
-     * ```typescript
-     * // Send initialization data
-     * sendViaCustomEvent(MessageEvents.INIT, {
-     *   baseUrl: '/api',
-     *   token: 'abc123',
-     *   gameId: 'game-456'
-     * })
-     * // Creates: CustomEvent('PLAYCADEMY_INIT', { detail: { baseUrl, token, gameId } })
-     *
-     * // Send pause signal
-     * sendViaCustomEvent(MessageEvents.PAUSE, undefined)
-     * // Creates: CustomEvent('PLAYCADEMY_PAUSE', { detail: undefined })
+     * Optional game ID.
+     * If not provided, will attempt to fetch from API using the API token.
      *
-     * // Listeners can access the data via event.detail:
-     * window.addEventListener('PLAYCADEMY_INIT', (event) => {
-     *   console.log(event.detail.gameId) // 'game-456'
-     * })
-     * ```
+     * @example 'my-math-game'
      */
-    private sendViaCustomEvent;
+    gameId?: string;
 }
 /**
- * **Playcademy Messaging Singleton**
- *
- * This is the main messaging instance used throughout the Playcademy platform.
- * It's exported as a singleton to ensure consistent communication across all parts
- * of the application.
- *
- * **Why a Singleton?**:
- * - Ensures all parts of the app use the same messaging instance
- * - Prevents conflicts between multiple messaging systems
- * - Simplifies the API - no need to pass instances around
- * - Maintains consistent event listener management
- *
- * **Usage in Different Contexts**:
- *
- * **In Games**:
- * ```typescript
- * import { messaging, MessageEvents } from '@playcademy/sdk'
- *
- * // Tell parent we're ready
- * messaging.send(MessageEvents.READY, undefined)
- *
- * // Listen for pause/resume
- * messaging.listen(MessageEvents.PAUSE, () => game.pause())
- * messaging.listen(MessageEvents.RESUME, () => game.resume())
- * ```
- *
- * **In Parent Shell**:
- * ```typescript
- * import { messaging, MessageEvents } from '@playcademy/sdk'
- *
- * // Send initialization data to game
- * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId })
- *
- * // Listen for game events
- * messaging.listen(MessageEvents.EXIT, () => closeGame())
- * messaging.listen(MessageEvents.READY, () => showGame())
- * ```
+ * Internal state maintained by the PlaycademyClient instance.
  *
- * **Automatic Transport Selection**:
- * The messaging system automatically chooses the right transport method:
- * - Uses postMessage when game is in iframe sending to parent
- * - Uses CustomEvent for local development and parent-to-game communication
+ * @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;
+}
+
+/**
+ * Resource bindings for backend deployment
+ * Provider-agnostic abstraction for cloud resources
+ */
+interface BackendResourceBindings {
+    /** SQL database instances to create and bind (maps to D1 on Cloudflare) */
+    database?: string[];
+    /** Key-value store namespaces to create and bind (maps to KV on Cloudflare) */
+    keyValue?: string[];
+    /** Object storage buckets to bind (maps to R2 on Cloudflare) */
+    bucket?: string[];
+}
+/**
+ * Backend deployment bundle for uploading to Playcademy platform
+ */
+interface BackendDeploymentBundle {
+    /** Bundled JavaScript code ready for deployment */
+    code: string;
+    /** Game configuration */
+    config: PlaycademyConfig;
+    /** Optional resource bindings (database, storage, etc.) */
+    bindings?: BackendResourceBindings;
+    /** Optional schema information for database setup */
+    schema?: SchemaInfo;
+    /** Optional game secrets */
+    secrets?: Record<string, string>;
+}
+
+/**
+ * OAuth 2.0 implementation for the Playcademy SDK
+ */
+
+/**
+ * Parses an OAuth state parameter to extract CSRF token and any encoded data.
  *
- * **Type Safety**:
- * All message sending and receiving is fully type-safe with TypeScript.
+ * @param state - The OAuth state parameter to parse
+ * @returns Object containing CSRF token and optional decoded data
  */
-declare const messaging: PlaycademyMessaging;
+declare function parseOAuthState(state: string): {
+    csrfToken: string;
+    data?: Record<string, string>;
+};
+
+/**
+ * Cache configuration types for runtime customization
+ */
+/**
+ * Runtime configuration for TTL cache behavior
+ */
+interface TTLCacheConfig {
+    /** Time-to-live in milliseconds. Set to 0 to disable caching for this call. */
+    ttl?: number;
+    /** Force refresh, bypassing cache */
+    force?: boolean;
+    /** Skip cache and fetch fresh data (alias for force) */
+    skipCache?: boolean;
+}
+/**
+ * Runtime configuration for cooldown cache behavior
+ */
+interface CooldownCacheConfig {
+    /** Cooldown period in milliseconds. Set to 0 to disable cooldown for this call. */
+    cooldown?: number;
+    /** Force refresh, bypassing cooldown */
+    force?: boolean;
+}
 
 /**
  * Internal Playcademy SDK client with all namespaces.
- * For use by CLI, platform, and admin tools.
+ * For use by Cademy platform, CLI, and admin tools.
  *
- * Extends the public client (8 namespaces) with 13 additional internal namespaces.
+ * Extends PlaycademyBaseClient directly (not PlaycademyClient) to allow
+ * independent namespace implementations without type conflicts.
  */
-declare class PlaycademyInternalClient extends PlaycademyClient {
-    /** Platform API authentication methods (login, logout, API keys) */
+declare class PlaycademyInternalClient extends PlaycademyBaseClient {
+    /**
+     * Connect external identity providers to the user's Playcademy account.
+     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
+     */
+    identity: {
+        connect: (options: AuthOptions) => Promise<AuthResult>;
+        _getContext: () => {
+            isInIframe: boolean;
+        };
+    };
+    /**
+     * Game runtime lifecycle and asset loading.
+     * - `exit()` - Return to Cademy hub
+     * - `getGameToken()` - Get short-lived auth token
+     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
+     */
+    runtime: {
+        getGameToken: (gameId: string, options?: {
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
+        exit: () => Promise<void>;
+        onInit: (handler: (context: GameContextPayload) => void) => void;
+        onTokenRefresh: (handler: (data: {
+            token: string;
+            exp: number;
+        }) => void) => void;
+        onPause: (handler: () => void) => void;
+        onResume: (handler: () => void) => void;
+        onForceExit: (handler: () => void) => void;
+        onOverlay: (handler: (isVisible: boolean) => void) => void;
+        ready: () => void;
+        sendTelemetry: (data: {
+            fps: number;
+            mem: number;
+        }) => void;
+        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
+            token: string;
+            exp: number;
+        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
+        removeAllListeners: () => void;
+        getListenerCounts: () => Record<string, number>;
+        assets: {
+            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+            fetch: (path: string, options?: RequestInit) => Promise<Response>;
+            json: <T = unknown>(path: string) => Promise<T>;
+            blob: (path: string) => Promise<Blob>;
+            text: (path: string) => Promise<string>;
+            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
+        };
+    };
+    /**
+     * Playcademy Credits (platform currency) management.
+     * - `get()` - Get user's credit balance
+     * - `add(amount)` - Award credits to user
+     */
+    credits: {
+        balance: () => Promise<number>;
+        add: (amount: number) => Promise<number>;
+        spend: (amount: number) => Promise<number>;
+    };
+    /**
+     * Realtime multiplayer authentication.
+     * - `getToken()` - Get token for WebSocket/realtime connections
+     */
+    realtime: {
+        token: {
+            get: () => Promise<RealtimeTokenResponse>;
+        };
+    };
+    /**
+     * Make requests to your game's custom backend API routes.
+     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
+     */
+    backend: {
+        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
+        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+    };
+    /**
+     * Platform authentication (better-auth integration).
+     * - `login(email, password)` - Authenticate user
+     * - `logout()` - End session
+     * - `getSession()` - Get current session
+     */
     auth: {
         login: (credentials: {
             email: string;
@@ -6217,14 +6344,26 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
         apiKeys: {
             create: (options?: {
                 name?: string;
-                expiresIn?: number | null;
+                expiresIn
+                /**
+                 * Platform-wide achievements system.
+                 * - `list()` - Get all achievements
+                 * - `getUserAchievements()` - Get user's earned achievements
+                 * - `award(achievementId)` - Grant achievement to user
+                 */
+                ?: number | null;
                 permissions?: Record<string, string[]>;
             }) => Promise<BetterAuthApiKeyResponse>;
             list: () => Promise<BetterAuthApiKey[]>;
             revoke: (keyId: string) => Promise<void>;
         };
     };
-    /** Administrative operations (pause games, manage items/currencies) */
+    /**
+     * Administrative operations for platform management.
+     * - `items.list()`, `items.create()` - Manage item catalog
+     * - `currencies.list()` - Manage currencies
+     * - `games.pause()`, `games.unpause()` - Control game availability
+     */
     admin: {
         games: {
             pauseGame: (gameId: string) => Promise<void>;
@@ -6234,7 +6373,6 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             create: (props: InsertItemInput) => Promise<{
                 gameId: string | null;
                 id: string;
-                createdAt: Date;
                 slug: string;
                 displayName: string;
                 description: string | null;
@@ -6242,11 +6380,11 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
                 isPlaceable: boolean;
                 imageUrl: string | null;
                 metadata: unknown;
+                createdAt: Date;
             }>;
             get: (itemId: string) => Promise<{
                 gameId: string | null;
                 id: string;
-                createdAt: Date;
                 slug: string;
                 displayName: string;
                 description: string | null;
@@ -6254,11 +6392,11 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
                 isPlaceable: boolean;
                 imageUrl: string | null;
                 metadata: unknown;
+                createdAt: Date;
             }>;
             list: () => Promise<{
                 gameId: string | null;
                 id: string;
-                createdAt: Date;
                 slug: string;
                 displayName: string;
                 description: string | null;
@@ -6266,11 +6404,11 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
                 isPlaceable: boolean;
                 imageUrl: string | null;
                 metadata: unknown;
+                createdAt: Date;
             }[]>;
             update: (itemId: string, props: UpdateItemInput) => Promise<{
                 gameId: string | null;
                 id: string;
-                createdAt: Date;
                 slug: string;
                 displayName: string;
                 description: string | null;
@@ -6278,6 +6416,7 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
                 isPlaceable: boolean;
                 imageUrl: string | null;
                 metadata: unknown;
+                createdAt: Date;
             }>;
             delete: (itemId: string) => Promise<void>;
         };
@@ -6372,7 +6511,12 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             delete: (listingId: string) => Promise<void>;
         };
     };
-    /** Developer operations (publish games, uploads, API keys) */
+    /**
+     * Developer operations for game publishing.
+     * - `publish(gameId)` - Deploy game to production
+     * - `uploads.getSignedUrl()` - Get upload URLs for assets
+     * - `apiKeys.create()`, `apiKeys.list()` - Manage API keys
+     */
     dev: {
         status: {
             apply: () => Promise<void>;
@@ -6439,7 +6583,13 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             };
         };
     };
-    /** Game directory, session management, tokens */
+    /**
+     * Game directory and session management.
+     * - `list()` - Get all games
+     * - `fetch(id)` - Get game by ID
+     * - `sessions.start()`, `sessions.end()` - Manage play sessions
+     * - `getGameToken(gameId)` - Get short-lived game auth token
+     */
     games: {
         fetch: (gameIdOrSlug: string, options?: TTLCacheConfig) => Promise<FetchedGame>;
         list: (options?: TTLCacheConfig) => Promise<Array<Game>>;
@@ -6459,7 +6609,11 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             }) => Promise<LeaderboardEntry[]>;
         };
     };
-    /** Avatar customization (overworld) */
+    /**
+     * Avatar customization for the overworld.
+     * - `get()` - Get user's avatar configuration
+     * - `update(config)` - Update avatar appearance
+     */
     character: {
         get: (userId?: string) => Promise<PlayerCharacter | null>;
         create: (characterData: CreateCharacterData) => Promise<PlayerCharacter>;
@@ -6477,7 +6631,12 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             list: () => Promise<PlayerCharacterAccessory[]>;
         };
     };
-    /** Platform-wide achievements (overworld) */
+    /**
+     * Platform-wide achievements system.
+     * - `list()` - Get all achievements
+     * - `getUserAchievements()` - Get user's earned achievements
+     * - `award(achievementId)` - Grant achievement to user
+     */
     achievements: {
         list: (options?: TTLCacheConfig) => Promise<AchievementCurrent[]>;
         history: {
@@ -6489,12 +6648,20 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             submit: (achievementId: string) => Promise<AchievementProgressResponse>;
         };
     };
-    /** Cross-game leaderboards (overworld) */
+    /**
+     * Cross-game leaderboards for the overworld.
+     * - `get(leaderboardId)` - Fetch leaderboard rankings
+     * - `submit(leaderboardId, score)` - Submit score to leaderboard
+     */
     leaderboard: {
         fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
         getUserRank: (gameId: string, userId: string) => Promise<UserRankResponse>;
     };
-    /** Platform-wide XP/level system (overworld) */
+    /**
+     * Platform-wide XP and leveling system.
+     * - `get()` - Get user's current level and XP
+     * - `addXp(amount)` - Award XP to user
+     */
     levels: {
         get: () => Promise<UserLevel>;
         progress: (options?: CooldownCacheConfig) => Promise<{
@@ -6508,11 +6675,19 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             get: (level: number) => Promise<LevelConfig | null>;
         };
     };
-    /** Shop listings and purchases (overworld) */
+    /**
+     * Shop listings and in-game purchases.
+     * - `list()` - Get available shop items
+     * - `purchase(itemId)` - Buy an item with credits
+     */
     shop: {
         view: () => Promise<ShopViewResponse>;
     };
-    /** System notifications (overworld) */
+    /**
+     * System notifications for the platform.
+     * - `list()` - Get user's notifications
+     * - `markRead(notificationId)` - Mark notification as read
+     */
     notifications: {
         list: (queryOptions?: {
             status?: NotificationStatus;
@@ -6530,7 +6705,11 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             }, cacheOptions?: TTLCacheConfig) => Promise<NotificationStats>;
         };
     };
-    /** Overworld map management */
+    /**
+     * Overworld map management.
+     * - `get()` - Get map data and unlocked areas
+     * - `unlock(areaId)` - Unlock a new map area
+     */
     maps: {
         get: (identifier: string, options?: TTLCacheConfig) => Promise<MapData>;
         elements: (mapId: string, options?: TTLCacheConfig) => Promise<MapElementWithGame[]>;
@@ -6540,27 +6719,53 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
             delete: (mapId: string, objectId: string) => Promise<void>;
         };
     };
-    /** Asset/sprite management */
+    /**
+     * Asset and sprite management for the overworld.
+     * - `list()` - Get available sprites
+     * - `upload(file)` - Upload new sprite asset
+     */
     sprites: {
         templates: {
             get: (slug: string) => Promise<SpriteTemplateData>;
         };
     };
-    /** Analytics and metrics */
+    /**
+     * Analytics and metrics tracking.
+     * - `track(event, properties)` - Record analytics event
+     * - `getMetrics()` - Fetch platform metrics
+     */
     telemetry: {
         pushMetrics: (metrics: Record<string, number>) => Promise<void>;
     };
-    /** Scores methods */
+    /**
+     * Score submission and user score queries.
+     * - `submit(gameId, score, metadata?)` - Record a game score
+     * - `getByUser(userId)` - Get all scores for a user
+     */
     scores: {
         getByUser: (gameId: string, userId: string, options?: {
-            limit
-            /** Cross-game leaderboards (overworld) */
-            ?: number;
+            limit?: number;
         }) => Promise<UserScore$1[]>;
         submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
     };
-    /** TimeBack (platform version with enrollments, game methods throw) */
+    /**
+     * TimeBack integration for user context, XP tracking, and course management.
+     *
+     * User context:
+     * - `user.role`, `user.enrollments`, `user.organizations` - Cached data
+     * - `user.fetch()` - Refresh from server
+     *
+     * XP tracking:
+     * - `xp.today()`, `xp.total()`, `xp.history()`, `xp.summary()` - Query XP data
+     *
+     * Student lookup (platform-only):
+     * - `students.get(timebackId)` - Fetch any student's full timeback data
+     *
+     * Management (CLI/admin):
+     * - `management.setup()`, `management.verify()`, `management.get()` - Configure integrations
+     */
     timeback: {
+        readonly user: PlatformTimebackUser;
         startActivity: (_metadata: _playcademy_timeback_types.ActivityData) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
@@ -6587,12 +6792,20 @@ declare class PlaycademyInternalClient extends PlaycademyClient {
                 timezone?: string;
             }) => Promise<XpSummaryResponse>;
         };
-        enrollments: {
-            get: (timebackId: string, options?: TTLCacheConfig) => Promise<StudentEnrollment[]>;
+        students: {
+            get: (timebackId: string, options?: TTLCacheConfig) => Promise<PlatformTimebackUserContext>;
             clearCache: (timebackId?: string) => void;
         };
     };
+    /** Auto-initializes a PlaycademyInternalClient with context from the environment */
+    static init: typeof init;
+    /** Authenticates a user with email and password */
+    static login: typeof login;
+    /** Static identity utilities for OAuth operations */
+    static identity: {
+        parseOAuthState: typeof parseOAuthState;
+    };
 }
 
 export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { Achievement, AchievementCurrent, AchievementProgressResponse, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CreateCharacterData, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EnrollmentsResponse, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, StudentEnrollment, TelemetryPayload, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, User, UserInfo, UserLevel, UserLevelWithConfig, UserRank, UserRankResponse, UserRoleEnumType, UserScore, XpHistoryResponse, XpSummaryResponse };
+export type { Achievement, AchievementCurrent, AchievementProgressResponse, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CreateCharacterData, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserRole, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, User, UserEnrollment, UserInfo, UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XpHistoryResponse, XpSummaryResponse };