@playcademy/sdk 0.9.1-beta.1 → 0.9.1-beta.3

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { UserRole, AUTH_PROVIDER_IDS } from '@playcademy/constants';
-import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import * as _playcademy_types from '@playcademy/types';
+import { TimebackGrade, TimebackSubject } from '@playcademy/types/timeback';
+import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
+import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
  * Base error class for Cademy SDK specific errors.
@@ -138,11 +140,11 @@ interface ApiErrorInfo {
  * @example
  * ```typescript
  * try {
- *   await client.shop.purchase(itemId)
+ *   await client.scores.submit(100)
  * } catch (error) {
  *   const info = extractApiErrorInfo(error)
  *   if (info) {
- *     showToast(`Error: ${info.message}`)
+ *     console.error(`Error: ${info.message}`)
  *   }
  * }
  * ```
@@ -150,828 +152,235 @@ interface ApiErrorInfo {
 declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
 
 /**
- * Connection monitoring types
- *
- * Type definitions for connection state, configuration, and callbacks.
+ * OAuth 2.0 implementation for the Playcademy SDK
  */
+
 /**
- * Possible connection states.
+ * Parses an OAuth state parameter to extract CSRF token and any encoded data.
  *
- * - **online**: Connection is stable and healthy
- * - **offline**: Complete loss of network connectivity
- * - **degraded**: Connection is slow or experiencing intermittent issues
+ * @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>;
+};
+
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface RetryPolicy {
+    retryableMethods?: readonly Method[];
+}
+
+/**
+ * Cache configuration types for runtime customization
  */
-type ConnectionState = 'online' | 'offline' | 'degraded';
 /**
- * Configuration options for ConnectionMonitor.
- *
- * @see {@link ConnectionMonitor} for usage
+ * Runtime configuration for TTL cache behavior
  */
-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;
+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;
 }
+
 /**
- * Callback function signature for connection state changes.
+ * @fileoverview Authentication Strategy Pattern
  *
- * @param state - The new connection state
- * @param reason - Human-readable reason for the state change
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
  */
-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.
+ * Base interface for authentication strategies
  */
+interface AuthStrategy {
+    /** Get the token value */
+    getToken(): string | null;
+    /** Get the token type */
+    getType(): TokenType;
+    /** Get authentication headers for a request */
+    getHeaders(): Record<string, string>;
+}
 
 /**
- * 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()
- * ```
+ * Base Playcademy SDK client with shared infrastructure.
+ * Provides authentication, HTTP requests, events,
+ * and fundamental namespaces used by all clients.
  *
- * @see {@link ConnectionManagerConfig} for configuration options
+ * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
  */
-declare class ConnectionMonitor {
-    private state;
-    private callbacks;
-    private heartbeatInterval?;
-    private consecutiveFailures;
-    private isMonitoring;
-    private config;
+declare abstract class PlaycademyBaseClient {
+    baseUrl: string;
+    gameUrl?: string;
+    mode: PlaycademyMode;
+    protected authStrategy: AuthStrategy;
+    protected gameId?: string;
+    protected config: Partial<ClientConfig>;
+    protected listeners: EventListeners;
+    protected authContext?: {
+        isInIframe: boolean;
+    };
+    protected initPayload?: InitPayload;
+    protected launchId?: string;
+    constructor(config?: Partial<ClientConfig>);
     /**
-     * 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)
+     * Gets the effective base URL for API requests.
      */
-    constructor(config: ConnectionMonitorConfig);
+    getBaseUrl(): string;
     /**
-     * Starts monitoring the connection state.
-     *
-     * Sets up event listeners and begins heartbeat checks based on configuration.
-     * Idempotent - safe to call multiple times.
+     * Gets the effective game backend URL for integration requests.
      */
-    start(): void;
+    protected getGameBackendUrl(): string;
     /**
-     * Stops monitoring the connection state and cleans up resources.
-     *
-     * Removes event listeners and clears heartbeat intervals.
-     * Idempotent - safe to call multiple times.
+     * Simple ping method for testing connectivity.
      */
-    stop(): void;
+    ping(): string;
     /**
-     * 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
-     * ```
+     * Sets the authentication token for API requests.
      */
-    onChange(callback: ConnectionChangeCallback): () => void;
+    setToken(token: string | null, tokenType?: TokenType): void;
+    setLaunchId(launchId: string | null | undefined): void;
     /**
-     * Gets the current connection state.
-     *
-     * @returns The current state ('online', 'offline', or 'degraded')
+     * Gets the current token type.
      */
-    getState(): ConnectionState;
+    getTokenType(): TokenType;
     /**
-     * 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')
-     * }
-     * ```
+     * Gets the current authentication token.
      */
-    checkNow(): Promise<ConnectionState>;
+    getToken(): string | null;
     /**
-     * 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
-     * }
-     * ```
+     * 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;
+    /**
+     * Sets the authentication context for the client.
+     * @internal
      */
-    reportRequestFailure(error: unknown): void;
+    _setAuthContext(context: {
+        isInIframe: boolean;
+    }): void;
     /**
-     * Reports a successful request.
+     * Registers an event listener for client events.
      *
-     * 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.
+     * @param event - The event name to listen for.
+     * @param callback - The handler invoked when the event fires.
+     * @returns A cleanup function that removes this specific listener.
+     */
+    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): () => void;
+    /**
+     * Removes a previously registered event listener.
      *
-     * @example
-     * ```typescript
-     * try {
-     *   const result = await fetch('/api/data')
-     *   monitor.reportRequestSuccess()
-     *   return result
-     * } catch (error) {
-     *   monitor.reportRequestFailure(error)
-     *   throw error
-     * }
-     * ```
+     * @param event - The event name to stop listening for.
+     * @param callback - The exact function reference passed to {@link on}.
+     */
+    off<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
+    /**
+     * Emits an event to all registered listeners.
+     */
+    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
+    /**
+     * Makes an authenticated HTTP request to the platform API.
+     */
+    protected request<T>(path: string, method: Method, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        raw?: boolean;
+        retryPolicy?: RetryPolicy;
+    }): Promise<T>;
+    /**
+     * Makes an authenticated HTTP request to the game's backend Worker.
+     */
+    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, options?: {
+        raw?: boolean;
+        retryPolicy?: RetryPolicy;
+    }): Promise<T>;
+    /**
+     * Ensures a gameId is available, throwing an error if not.
+     */
+    protected _ensureGameId(): string;
+    /**
+     * Detects and sets the authentication context (iframe vs standalone).
+     */
+    private _detectAuthContext;
+    /**
+     * Current user data.
+     * - `me()` - Get authenticated user profile
      */
-    reportRequestSuccess(): void;
-    private _detectInitialState;
-    private _handleOnline;
-    private _handleOffline;
-    private _startHeartbeat;
-    private _performHeartbeat;
-    private _handleHeartbeatFailure;
-    private _setState;
+    users: {
+        me: () => Promise<_playcademy_types.AuthenticatedUser>;
+    };
 }
 
 /**
- * OAuth 2.0 implementation for the Playcademy SDK
- */
-
-/**
- * Parses an OAuth state parameter to extract CSRF token and any encoded data.
+ * Auto-initializes a PlaycademyClient with context from the environment.
+ * Works in both iframe mode (production/development) and standalone mode (local dev).
  *
- * @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>;
-};
-
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-interface RetryPolicy {
-    retryableMethods?: readonly Method[];
-}
-
-/**
- * TimeBack Enums & Literal 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
  *
- * Basic type definitions used throughout the TimeBack integration.
+ * @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
  *
- * @module types/timeback/types
- */
-/**
- * Valid TimeBack subject values for course configuration.
- * These are the supported subject values for OneRoster courses.
- */
-type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
-/**
- * Grade levels per AE OneRoster GradeEnum.
- * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
- */
-type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
-/**
- * Valid Caliper subject values.
- * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ * @example
+ * ```typescript
+ * // Default initialization
+ * const client = await PlaycademyClient.init()
+ *
+ * // With custom base URL
+ * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
+ * ```
  */
-type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+}): Promise<T>;
 
 /**
- * TimeBack Client SDK DTOs
+ * 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.
  *
- * Data transfer objects for the TimeBack client SDK including
- * progress tracking, session management, and activity completion.
+ * @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
  *
- * Note: TimebackClientConfig lives in @playcademy/timeback as it's
- * SDK configuration, not a DTO.
+ * @example
+ * ```typescript
+ * // Preferred approach:
+ * const client = new PlaycademyClient({ baseUrl: '/api' })
+ * const result = await client.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * })
  *
- * @module types/timeback/client
+ * // 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)
+ * }
+ * ```
  */
-
-/**
- * Known extensions for TimeBack Activity Metrics Collection
- */
-interface TimebackActivityExtensions {
-    /** Percentage complete (0-100) for the app course */
-    pctCompleteApp?: number;
-    /** Allow other arbitrary extensions */
-    [key: string]: unknown;
-}
-/**
- * Activity data for ending an activity
- */
-interface ActivityData {
-    /** Unique activity identifier (required) */
-    activityId: string;
-    /** Grade level for this activity (required for multi-grade course routing) */
-    grade: number;
-    /** Subject area (required for multi-grade course routing) */
-    subject: CaliperSubject;
-    /** Activity display name (optional) */
-    activityName?: string;
-    /** Course identifier (auto-filled from config if not provided) */
-    courseId?: string;
-    /** Course display name (auto-filled from config if not provided) */
-    courseName?: string;
-    /** Student email address (optional) */
-    studentEmail?: string;
-    /** Application name for Caliper events (defaults to 'Game') */
-    appName?: string;
-    /** Sensor URL for Caliper events (defaults to baseUrl) */
-    sensorUrl?: string;
-}
-/**
- * Score data with optional XP override for ending an activity
- */
-interface EndActivityScoreData {
-    /** Number of questions answered correctly */
-    correctQuestions: number;
-    /** Total number of questions */
-    totalQuestions: number;
-    /** Optional XP override - bypasses automatic XP calculation */
-    xpAwarded?: number;
-    /** Number of learning units mastered */
-    masteredUnits?: number;
-    /** Optional arbitrary extensions to include in the Caliper event */
-    extensions?: TimebackActivityExtensions;
-}
-
-/**
- * TimeBack API Request/Response Types
- *
- * Types for TimeBack API endpoints including XP tracking,
- * setup, verification, and activity completion.
- *
- * @module types/timeback/api
- */
-
-type TimebackPromotionStatus = 'promoted' | 'no-next-course' | 'already-promoted' | 'not-enrolled' | 'not-mastered';
-interface TimebackPromotionResult {
-    status: TimebackPromotionStatus;
-    currentCourseId: string;
-    nextCourseId?: string;
-    masteredUnits?: number;
-    masterableUnits?: number;
-}
-interface EndActivityResponse {
-    status: 'ok';
-    courseId: string;
-    xpAwarded: number;
-    masteredUnits?: number;
-    pctCompleteApp?: number;
-    scoreStatus?: string;
-    inProgress?: string;
-}
-interface AdvanceCourseResponse {
-    status: 'ok';
-    promotion: TimebackPromotionResult;
-}
-
-/**
- * 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;
-}
-
-/**
- * User Types
- *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
- *
- * @module types/user
- */
-
-type UserRoleEnumType = UserRole;
-type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
-type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
-type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-interface UserEnrollment {
-    gameId?: string;
-    courseId: string;
-    enrollmentIds?: {
-        active: string;
-        inactive?: string[];
-    };
-    grade: number;
-    subject: string;
-    orgId?: string;
-}
-interface UserOrganization {
-    id: string;
-    name: string | null;
-    type: TimebackOrgType | string;
-    isPrimary: boolean;
-}
-interface TimebackStudentProfile {
-    role: TimebackUserRole;
-    organizations: UserOrganization[];
-}
-interface UserTimebackData extends TimebackStudentProfile {
-    id: string;
-    enrollments: UserEnrollment[];
-}
-/**
- * OpenID Connect UserInfo claims (NOT a database row).
- */
-interface UserInfo {
-    sub: string;
-    email: string;
-    name: string | null;
-    email_verified?: boolean;
-    given_name?: string;
-    family_name?: string;
-    issuer?: string;
-    lti_roles?: unknown;
-    lti_context?: unknown;
-    lti_resource_link?: unknown;
-    timeback_id?: string;
-}
-interface DemoProfile {
-    displayName: string;
-    isDefault: boolean;
-}
-/**
- * Update shape for `client.demo.profile.update(...)`.
- *
- * Kept as a named type so callers typed against it pick up new fields
- * automatically, but `displayName` is the only updatable field today and
- * the server's `DemoProfileSchema` requires it — a no-field payload would
- * 400 at runtime, so we model that at the type level too. When additional
- * fields land, make them required/optional individually based on server
- * validation, rather than blanket-optional.
- */
-interface DemoProfileUpdate {
-    displayName: string;
-}
-/**
- * Authenticated user for API responses.
- * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
- */
-interface AuthenticatedUser {
-    id: string;
-    email: string;
-    emailVerified: boolean;
-    name: string | null;
-    image: string | null;
-    username: string | null;
-    role: UserRoleEnumType;
-    developerStatus: DeveloperStatusEnumType;
-    characterCreated: boolean;
-    createdAt: Date;
-    updatedAt: Date;
-    hasTimebackAccount: boolean;
-    timeback?: UserTimebackData;
-}
-
-/**
- * Leaderboard Types
- *
- * @module types/leaderboard
- */
-type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
-interface LeaderboardOptions {
-    timeframe?: LeaderboardTimeframe;
-    limit?: number;
-    offset?: number;
-    gameId?: string;
-}
-/**
- * Leaderboard entry with required game context.
- * Used when fetching leaderboards for a specific game.
- */
-interface GameLeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
-}
-
-declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "items";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "items";
-            dataType: "string";
-            columnType: "PgUUID";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        slug: drizzle_orm_pg_core.PgColumn<{
-            name: "slug";
-            tableName: "items";
-            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;
-        }, {}, {}>;
-        gameId: drizzle_orm_pg_core.PgColumn<{
-            name: "game_id";
-            tableName: "items";
-            dataType: "string";
-            columnType: "PgUUID";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        displayName: drizzle_orm_pg_core.PgColumn<{
-            name: "display_name";
-            tableName: "items";
-            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;
-        }, {}, {}>;
-        description: drizzle_orm_pg_core.PgColumn<{
-            name: "description";
-            tableName: "items";
-            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;
-        }, {}, {}>;
-        type: drizzle_orm_pg_core.PgColumn<{
-            name: "type";
-            tableName: "items";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["currency", "badge", "trophy", "collectible", "consumable", "unlock", "upgrade", "accessory", "other"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        isPlaceable: drizzle_orm_pg_core.PgColumn<{
-            name: "is_placeable";
-            tableName: "items";
-            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;
-        }, {}, {}>;
-        imageUrl: drizzle_orm_pg_core.PgColumn<{
-            name: "image_url";
-            tableName: "items";
-            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;
-        }, {}, {}>;
-        metadata: drizzle_orm_pg_core.PgColumn<{
-            name: "metadata";
-            tableName: "items";
-            dataType: "json";
-            columnType: "PgJsonb";
-            data: unknown;
-            driverParam: unknown;
-            notNull: false;
-            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: "items";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: 'pg';
-}>;
-declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "inventory_items";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "inventory_items";
-            dataType: "string";
-            columnType: "PgUUID";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        userId: drizzle_orm_pg_core.PgColumn<{
-            name: "user_id";
-            tableName: "inventory_items";
-            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;
-        }, {}, {}>;
-        itemId: drizzle_orm_pg_core.PgColumn<{
-            name: "item_id";
-            tableName: "inventory_items";
-            dataType: "string";
-            columnType: "PgUUID";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        quantity: drizzle_orm_pg_core.PgColumn<{
-            name: "quantity";
-            tableName: "inventory_items";
-            dataType: "number";
-            columnType: "PgInteger";
-            data: number;
-            driverParam: string | number;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
-            tableName: "inventory_items";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: false;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: 'pg';
-}>;
-
-type ItemRow = typeof items.$inferSelect;
-type InventoryItemRow = typeof inventoryItems.$inferSelect;
-type InventoryItemWithItem = InventoryItemRow & {
-    item: ItemRow;
-};
-
-/**
- * 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' })
- * ```
- */
-declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
-    baseUrl?: string;
-    allowedParentOrigins?: string[];
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
-}): Promise<T>;
-
-/**
- * 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>;
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
 
 /**
  * @fileoverview Playcademy Messaging System
@@ -1054,14 +463,6 @@ declare enum MessageEvents {
      * 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.
@@ -1099,14 +500,6 @@ declare enum MessageEvents {
      * - `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",
     /**
      * Game signals that demo mode has ended.
      * Sent when a demo experience reaches its CTA/upgrade boundary.
@@ -1171,8 +564,6 @@ interface MessageEventMap {
     [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;
     /** SDK init error data */
@@ -1183,8 +574,6 @@ interface MessageEventMap {
     [MessageEvents.TELEMETRY]: TelemetryPayload;
     /** Key event data */
     [MessageEvents.KEY_EVENT]: KeyEventPayload;
-    /** Display alert request from game */
-    [MessageEvents.DISPLAY_ALERT]: DisplayAlertPayload;
     /** Demo end signal from game */
     [MessageEvents.DEMO_END]: DemoEndPayload;
     /** Authentication state change notification */
@@ -1460,322 +849,103 @@ declare class PlaycademyMessaging {
      */
     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;
-}
-/**
- * **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.
- */
-declare const messaging: PlaycademyMessaging;
-
-/**
- * @fileoverview Authentication Strategy Pattern
- *
- * Provides different authentication strategies for the Playcademy SDK.
- * Each strategy knows how to add its authentication headers to requests.
- */
-
-/**
- * Base interface for authentication strategies
- */
-interface AuthStrategy {
-    /** Get the token value */
-    getToken(): string | null;
-    /** Get the token type */
-    getType(): TokenType;
-    /** Get authentication headers for a request */
-    getHeaders(): Record<string, string>;
-}
-
-/**
- * Base Playcademy SDK client with shared infrastructure.
- * Provides authentication, HTTP requests, events, connection monitoring,
- * and fundamental namespaces used by all clients.
- *
- * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
- */
-declare abstract class PlaycademyBaseClient {
-    baseUrl: string;
-    gameUrl?: string;
-    mode: PlaycademyMode;
-    protected authStrategy: AuthStrategy;
-    protected gameId?: string;
-    protected config: Partial<ClientConfig>;
-    protected listeners: EventListeners;
-    protected internalClientSessionId?: string;
-    protected authContext?: {
-        isInIframe: boolean;
-    };
-    protected initPayload?: InitPayload;
-    protected connectionManager?: ConnectionManager;
-    protected launchId?: string;
-    /**
-     * Internal session manager for automatic session lifecycle.
-     * @private
-     * @internal
-     */
-    protected _sessionManager: {
-        startSession: (gameId: string) => Promise<{
-            sessionId: string;
-        }>;
-        endSession: (sessionId: string, gameId: string) => Promise<void>;
-    };
-    constructor(config?: Partial<ClientConfig>);
-    /**
-     * Gets the effective base URL for API requests.
-     */
-    getBaseUrl(): string;
-    /**
-     * Gets the effective game backend URL for integration requests.
-     */
-    protected getGameBackendUrl(): string;
-    /**
-     * Simple ping method for testing connectivity.
-     */
-    ping(): string;
-    /**
-     * Sets the authentication token for API requests.
-     */
-    setToken(token: string | null, tokenType?: TokenType): void;
-    setLaunchId(launchId: string | null | undefined): void;
-    /**
-     * Gets the current token type.
-     */
-    getTokenType(): TokenType;
-    /**
-     * Gets the current authentication token.
-     */
-    getToken(): string | null;
-    /**
-     * Checks if the client has a valid API token.
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Registers a callback to be called when authentication state changes.
-     */
-    onAuthChange(callback: (token: string | null) => void): void;
-    /**
-     * Registers a callback to be called when connection issues are detected.
-     */
-    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
-    /**
-     * Gets the current connection state.
-     */
-    getConnectionState(): ConnectionState | 'unknown';
-    /**
-     * Manually triggers a connection check immediately.
-     */
-    checkConnection(): Promise<ConnectionState | 'unknown'>;
-    /**
-     * Sets the authentication context for the client.
-     * @internal
-     */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
-    /**
-     * Registers an event listener for client events.
-     *
-     * @param event - The event name to listen for.
-     * @param callback - The handler invoked when the event fires.
-     * @returns A cleanup function that removes this specific listener.
-     */
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): () => void;
-    /**
-     * Removes a previously registered event listener.
-     *
-     * @param event - The event name to stop listening for.
-     * @param callback - The exact function reference passed to {@link on}.
-     */
-    off<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
-    /**
-     * Emits an event to all registered listeners.
-     */
-    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
-    /**
-     * Makes an authenticated HTTP request to the platform API.
-     */
-    protected request<T>(path: string, method: Method, options?: {
-        body?: unknown;
-        headers?: Record<string, string>;
-        raw?: boolean;
-        retryPolicy?: RetryPolicy;
-    }): Promise<T>;
-    /**
-     * Makes an authenticated HTTP request to the game's backend Worker.
-     */
-    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, options?: {
-        raw?: boolean;
-        retryPolicy?: RetryPolicy;
-    }): Promise<T>;
-    /**
-     * Ensures a gameId is available, throwing an error if not.
-     */
-    protected _ensureGameId(): string;
-    /**
-     * Detects and sets the authentication context (iframe vs standalone).
-     */
-    private _detectAuthContext;
-    /**
-     * Initializes connection monitoring if enabled.
-     */
-    private _initializeConnectionMonitor;
-    private _initializeInternalSession;
-    /**
-     * Current user data and inventory management.
-     * - `me()` - Get authenticated user profile
-     * - `inventory.get()` - List user's items
-     * - `inventory.add(slug, qty)` - Award items to user
-     */
-    users: {
-        me: () => Promise<AuthenticatedUser>;
-        inventory: {
-            get: () => Promise<InventoryItemWithItem[]>;
-            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            quantity: (identifier: string) => Promise<number>;
-            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-        };
-    };
-}
-
-/**
- * Options for configuring activity tracking behavior.
- */
-interface StartActivityOptions {
-    /**
-     * How long heartbeats continue after the activity is automatically paused
-     * because the tab is hidden or the player is inactive while visible.
-     * Defaults to 10 minutes. Set to `Infinity` to keep heartbeats running
-     * indefinitely during automatic pauses. Invalid values fall back to the
-     * 10-minute default.
-     */
-    pausedHeartbeatTimeoutMs?: number;
-    /**
-     * @deprecated Use `pausedHeartbeatTimeoutMs` instead.
-     *
-     * Backward-compatible alias for callers that still use the old option
-     * name from earlier SDK releases.
-     */
-    hiddenTimeoutMs?: number;
-    /**
-     * How often to flush periodic heartbeats with accumulated time data.
-     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
-     * final unload/endActivity flushes still run. Values must be greater than
-     * 0 or `Infinity`; invalid values fall back to the 15-second default.
-     */
-    heartbeatIntervalMs?: number;
-    /**
-     * How long the tab can remain visible without keyboard or mouse activity
-     * before the activity is marked inactive. Defaults to 10 minutes. Set to
-     * `Infinity` to disable keyboard/mouse inactivity tracking. Invalid values
-     * fall back to the 10-minute default.
-     */
-    inactivityTimeoutMs?: number;
-    /**
-     * Stable identifier for this activity run. When provided, it is used on
-     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     * **Send Via CustomEvent Method**
      *
-     * Pass the same `runId` across multiple `startActivity()` calls (for
-     * example, after the player closes and reopens a resumable activity) so
-     * downstream systems can correlate related sessions into a single run.
+     * 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.
      *
-     * Must be a UUID (the backend validates it as such) and unique per
-     * logical run. If omitted, the SDK generates a new UUID on each call,
-     * which means every session is treated as its own run.
+     * **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'
+     * })
+     * ```
      */
-    runId?: string;
+    private sendViaCustomEvent;
 }
+/**
+ * **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.
+ */
+declare const messaging: PlaycademyMessaging;
 
 /**
  * Playcademy SDK client for game developers.
@@ -1803,7 +973,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
         getGameToken: (gameId: string, options?: {
             apply?: boolean;
         }) => Promise<GameTokenResponse>;
-        exit: () => Promise<void>;
+        exit: () => void;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
             token: string;
@@ -1844,31 +1014,23 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `user.fetch()` - Refresh user context from server
      *
      * Activity tracking:
-     * - `startActivity(metadata)` - Begin tracking an activity with automatic
-     *   hidden-tab and visible-tab inactivity handling, plus configurable
-     *   paused-heartbeat timeout behavior
+     * - `currentRunId` - Current activity run ID, or undefined when inactive
+     * - `startActivity(metadata)` - Begin tracking an activity, return its run
+     *   ID, and automatically handle hidden-tab and visible-tab inactivity
+     *   with configurable paused-heartbeat timeout behavior
      * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
      * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData, options?: StartActivityOptions) => void;
+        readonly currentRunId: string | undefined;
+        startActivity: (metadata: _playcademy_types.ActivityData, options?: StartActivityOptions) => StartActivityResult;
         pauseActivity: () => void;
         resumeActivity: () => void;
-        endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
+        endActivity: (data: _playcademy_types.EndActivityScoreData) => Promise<_playcademy_types.EndActivityResponse>;
         advanceCourse: (options?: {
-            subject?: TimebackSubject;
-        }) => Promise<AdvanceCourseResponse>;
-    };
-    /**
-     * 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>;
+            subject?: _playcademy_types.TimebackSubject;
+        }) => Promise<_playcademy_types.AdvanceCourseResponse>;
     };
     /**
      * Game score submission and leaderboards.
@@ -1882,7 +1044,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `fetch(options?)` - Fetch leaderboard entries
      */
     leaderboard: {
-        fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
+        fetch: (options?: _playcademy_types.LeaderboardOptions) => Promise<_playcademy_types.GameLeaderboardEntry[]>;
     };
     /**
      * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
@@ -1893,20 +1055,11 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     demo: {
         profile: {
-            get: () => Promise<DemoProfile>;
-            update: (updates: DemoProfileUpdate) => Promise<DemoProfile>;
+            get: () => Promise<_playcademy_types.DemoProfile>;
+            update: (updates: _playcademy_types.DemoProfileUpdate) => Promise<_playcademy_types.DemoProfile>;
         };
         end: (score: number, options?: DemoEndOptions) => void;
     };
-    /**
-     * 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
@@ -1932,6 +1085,57 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
     };
 }
 
+/**
+ * Options for configuring activity tracking behavior.
+ */
+interface StartActivityOptions {
+    /**
+     * How long heartbeats continue after the activity is automatically paused
+     * because the tab is hidden or the player is inactive while visible.
+     * Defaults to 10 minutes. Set to `Infinity` to keep heartbeats running
+     * indefinitely during automatic pauses. Invalid values fall back to the
+     * 10-minute default.
+     */
+    pausedHeartbeatTimeoutMs?: number;
+    /**
+     * @deprecated Use `pausedHeartbeatTimeoutMs` instead.
+     *
+     * Backward-compatible alias for callers that still use the old option
+     * name from earlier SDK releases.
+     */
+    hiddenTimeoutMs?: number;
+    /**
+     * How often to flush periodic heartbeats with accumulated time data.
+     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
+     * final unload/endActivity flushes still run. Values must be greater than
+     * 0 or `Infinity`; invalid values fall back to the 15-second default.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * How long the tab can remain visible without keyboard or mouse activity
+     * before the activity is marked inactive. Defaults to 10 minutes. Set to
+     * `Infinity` to disable keyboard/mouse inactivity tracking. Invalid values
+     * fall back to the 10-minute default.
+     */
+    inactivityTimeoutMs?: number;
+    /**
+     * Stable identifier for this activity run. When provided, it is used on
+     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     *
+     * Pass the same `runId` across multiple `startActivity()` calls (for
+     * example, after the player closes and reopens a resumable activity) so
+     * downstream systems can correlate related sessions into a single run.
+     *
+     * Must be a UUID (the backend validates it as such) and unique per
+     * logical run. If omitted, the SDK generates a new UUID on each call,
+     * which means every session is treated as its own run.
+     */
+    runId?: string;
+}
+interface StartActivityResult {
+    runId: string;
+}
+
 /**
  * Type definitions for the game timeback namespace.
  *
@@ -2108,32 +1312,8 @@ interface ClientConfig {
     tokenType?: TokenType;
     gameId?: string;
     launchId?: string;
-    autoStartSession?: boolean;
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
     mode?: PlaycademyMode;
 }
-/**
- * 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>;
-/**
- * Context provided to disconnect handlers
- */
-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;
@@ -2143,8 +1323,6 @@ interface InitPayload {
     token: string;
     /** Game ID */
     gameId: string;
-    /** Realtime WebSocket URL */
-    realtimeUrl?: string;
     /** Timeback context (if user has a Timeback account) */
     timeback?: TimebackInitContext;
     /** Runtime mode for the game client */
@@ -2153,7 +1331,6 @@ interface InitPayload {
 interface GameContextPayload {
     token: string;
     baseUrl: string;
-    realtimeUrl: string;
     gameId: string;
     forwardKeys?: string[];
     mode?: PlaycademyMode;
@@ -2165,38 +1342,12 @@ 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.
@@ -2253,14 +1404,6 @@ interface KeyEventPayload {
     /** Event type */
     type: 'keydown' | 'keyup';
 }
-/**
- * Connection state payload.
- * Broadcast from platform to games when connection changes.
- */
-interface ConnectionStatePayload {
-    state: 'online' | 'offline' | 'degraded';
-    reason: string;
-}
 /**
  * Init error payload.
  * Sent from game iframe to parent when SDK initialization fails
@@ -2301,19 +1444,6 @@ interface GameTokenResponse {
     exp: number;
     baseUrl?: string;
 }
-interface InventoryMutationResponse {
-    newTotal: number;
-}
-
-/**
- * Realtime namespace types
- */
-/**
- * Response type for the realtime token API
- */
-interface RealtimeTokenResponse {
-    token: string;
-}
 
 /**
  * Scores namespace types
@@ -2395,179 +1525,5 @@ interface DevUploadHooks {
     onClose?: () => void;
 }
 
-/**
- * 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 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;
-}
-
-export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, PlaycademyMode };
+export { ApiError, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
+export type { ApiErrorCode, ApiErrorInfo, DevUploadEvent, DevUploadHooks, ErrorResponseBody, PlaycademyMode };