@playcademy/sdk 0.1.14 → 0.1.15

package/dist/index.d.ts

@@ -1,12 +1,250 @@
-import * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
+import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 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 * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
 import * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
 import { SchemaInfo } from '@playcademy/cloudflare';
-import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
+
+/**
+ * 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);
+}
+/**
+ * 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;
+}
 
 declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "user";
@@ -3289,6 +3527,91 @@ type EndActivityResponse = {
     xpAwarded: number;
 };
 
+/**
+ * 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>;
+};
+
+/**
+ * Response type for the realtime token API
+ */
+interface RealtimeTokenResponse {
+    token: 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;
+}
+
+interface CharacterComponentsOptions {
+    /**
+     * Optional level filter for components
+     * When provided, only components available at this level or below are returned
+     */
+    level?: number;
+    /**
+     * Whether to bypass the cache and force a fresh API request
+     * Default: false (use cache when available)
+     */
+    skipCache?: boolean;
+}
+interface CreateCharacterData {
+    bodyComponentId: string;
+    eyesComponentId: string;
+    hairstyleComponentId: string;
+    outfitComponentId: string;
+}
+interface UpdateCharacterData {
+    bodyComponentId?: string;
+    eyesComponentId?: string;
+    hairstyleComponentId?: string;
+    outfitComponentId?: string;
+}
+
+interface ScoreSubmission {
+    id: string;
+    score: number;
+    achievedAt: Date;
+}
+
+/**
+ * Combined response type for summary method
+ */
+type XpSummaryResponse = {
+    today: TodayXpResponse;
+    total: TotalXpResponse;
+};
+
 /**
  * @fileoverview Server SDK Type Definitions
  *
@@ -3396,303 +3719,14 @@ interface BackendDeploymentBundle {
     secrets?: Record<string, string>;
 }
 
-type TokenType = 'session' | 'apiKey' | 'gameJwt';
-interface ClientConfig {
-    baseUrl: string;
-    gameUrl?: string;
-    token?: string;
-    tokenType?: TokenType;
-    gameId?: string;
-    autoStartSession?: boolean;
-}
-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;
-    };
-    /**
-     * 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.
-     */
-    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;
-}
-/**
- * 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;
-}
-/**
- * Token refresh event payload.
- * Sent when authentication token is updated.
- */
-interface TokenRefreshPayload {
-    /** New authentication token */
-    token: string;
-    /** Token expiration timestamp */
-    exp: number;
-}
-/**
- * Telemetry event payload.
- * Performance metrics sent from the game.
- */
-interface TelemetryPayload {
-    /** Frames per second */
-    fps: number;
-    /** Memory usage in MB */
-    mem: number;
-}
-/**
- * Keyboard event payload.
- * Key events forwarded from the game.
- */
-interface KeyEventPayload {
-    /** Key value (e.g., 'Escape', 'F1') */
-    key: string;
-    /** Key code (optional) */
-    code?: string;
-    /** Event type */
-    type: 'keydown' | 'keyup';
-}
-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;
-    };
-}
-type GameContextPayload = {
-    token: string;
-    baseUrl: string;
-    realtimeUrl: string;
-    gameId: string;
-    forwardKeys?: string[];
-};
-type LoginResponse = {
-    token: string;
-};
-type GameTokenResponse = {
-    token: string;
-    exp: number;
-};
-type StartSessionResponse = {
-    sessionId: string;
-};
-type InventoryMutationResponse = {
-    newTotal: number;
-};
-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;
-};
-/**
- * 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;
-}
-/**
- * Bucket file metadata
- */
-interface BucketFile {
-    key: string;
-    size: number;
-    uploaded: string;
-    contentType?: string;
-}
-
-/**
- * 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>;
-};
-
-/**
- * Response type for the realtime token API
- */
-interface RealtimeTokenResponse {
-    token: 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;
-}
-
-interface CharacterComponentsOptions {
-    /**
-     * Optional level filter for components
-     * When provided, only components available at this level or below are returned
-     */
-    level?: number;
-    /**
-     * Whether to bypass the cache and force a fresh API request
-     * Default: false (use cache when available)
-     */
-    skipCache?: boolean;
-}
-interface CreateCharacterData {
-    bodyComponentId: string;
-    eyesComponentId: string;
-    hairstyleComponentId: string;
-    outfitComponentId: string;
-}
-interface UpdateCharacterData {
-    bodyComponentId?: string;
-    eyesComponentId?: string;
-    hairstyleComponentId?: string;
-    outfitComponentId?: string;
-}
-
-interface ScoreSubmission {
-    id: string;
-    score: number;
-    achievedAt: Date;
-}
-
-/**
- * Combined response type for summary method
- */
-type XpSummaryResponse = {
-    today: TodayXpResponse;
-    total: TotalXpResponse;
-};
-
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
 }
 
 /**
@@ -3722,6 +3756,8 @@ interface UserScore {
 declare function init(options?: {
     baseUrl?: string;
     allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
 }): Promise<PlaycademyClient>;
 
 /**
@@ -3775,6 +3811,7 @@ declare class PlaycademyClient {
     private internalClientSessionId?;
     private authContext?;
     private initPayload?;
+    private connectionManager?;
     /**
      * Creates a new PlaycademyClient instance.
      *
@@ -3867,13 +3904,92 @@ declare class PlaycademyClient {
      */
     onAuthChange(callback: (token: string | null) => void): void;
     /**
-     * Sets the authentication context for the client.
-     * This is called during initialization to store environment info.
-     * @internal
-     */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
+     * Registers a callback to be called when connection issues are detected.
+     *
+     * 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.
+     *
+     * For all connection state changes, use `client.on('connectionChange', ...)` instead.
+     *
+     * @param callback - Function to call when connection state changes to offline or degraded
+     * @returns Cleanup function to unregister the callback
+     *
+     * @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' })
+     *   }
+     * })
+     *
+     * // Later: cleanup() to unregister
+     * ```
+     *
+     * @see {@link DISCONNECT_HANDLING.md} for detailed usage examples
+     * @see {@link ConnectionManager.onDisconnect} for the underlying implementation
+     */
+    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const state = client.getConnectionState()
+     * if (state === 'offline') {
+     *   console.log('No connection available')
+     * }
+     * ```
+     *
+     * @see {@link checkConnection} to trigger an immediate connection check
+     * @see {@link ConnectionManager.getState} for the underlying implementation
+     */
+    getConnectionState(): ConnectionState | 'unknown';
+    /**
+     * 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).
+     *
+     * @returns Promise resolving to the current connection state after verification
+     *
+     * @example
+     * ```typescript
+     * // Check before critical operation
+     * const state = await client.checkConnection()
+     * if (state !== 'online') {
+     *   alert('Please check your internet connection before saving')
+     *   return
+     * }
+     *
+     * 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;
     /**
      * Registers an event listener for client events.
      *
@@ -3928,6 +4044,11 @@ declare class PlaycademyClient {
      * Safe to call in any environment - isInIframe handles browser detection.
      */
     private _detectAuthContext;
+    /**
+     * Initializes connection monitoring if enabled.
+     * Safe to call in any environment - only runs in browser.
+     */
+    private _initializeConnectionMonitor;
     /**
      * Initializes an internal game session for automatic session management.
      * Only starts a session if:
@@ -4129,50 +4250,50 @@ declare class PlaycademyClient {
         };
         items: {
             create: (props: InsertItemInput) => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             get: (itemId: string) => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             list: () => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }[]>;
             update: (itemId: string, props: UpdateItemInput) => Promise<{
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 id: string;
-                metadata: unknown;
-                slug: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
@@ -4307,9 +4428,7 @@ declare class PlaycademyClient {
             }) => Promise<TodayXpResponse>;
             total: () => Promise<TotalXpResponse>;
             history: (options?: {
-                startDate
-                /** Auto-initializes a PlaycademyClient with context from the environment */
-                ?: string;
+                startDate?: string;
                 endDate?: string;
             }) => Promise<XpHistoryResponse>;
             summary: (options?: {
@@ -4422,29 +4541,436 @@ declare class PlaycademyClient {
     };
 }
 
+type TokenType = 'session' | 'apiKey' | 'gameJwt';
+interface ClientConfig {
+    baseUrl: string;
+    gameUrl?: string;
+    token?: string;
+    tokenType?: TokenType;
+    gameId?: string;
+    autoStartSession?: boolean;
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}
 /**
- * Base error class for Cademy SDK specific errors.
+ * Handler called when connection state changes to offline or degraded.
+ * Games can implement this to handle disconnects gracefully.
  */
-declare class PlaycademyError extends Error {
-    constructor(message: string);
+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;
 }
-declare class ApiError extends Error {
-    status: number;
-    details: unknown;
-    constructor(status: number, message: string, details: unknown);
+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;
+    };
+    /**
+     * 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.
+     */
+    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;
 }
 /**
- * Extract useful error information from an API error
- * Useful for displaying errors to users in a friendly way
+ * Authentication state change event payload.
+ * Used when authentication state changes in the application.
  */
-interface ApiErrorInfo {
-    status: number;
-    statusText: string;
-    error?: string;
-    message?: string;
-    details?: unknown;
+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;
+}
+/**
+ * Token refresh event payload.
+ * Sent when authentication token is updated.
+ */
+interface TokenRefreshPayload {
+    /** New authentication token */
+    token: string;
+    /** Token expiration timestamp */
+    exp: number;
+}
+/**
+ * Telemetry event payload.
+ * Performance metrics sent from the game.
+ */
+interface TelemetryPayload {
+    /** Frames per second */
+    fps: number;
+    /** Memory usage in MB */
+    mem: number;
+}
+/**
+ * Keyboard event payload.
+ * Key events forwarded from the game.
+ */
+interface KeyEventPayload {
+    /** Key value (e.g., 'Escape', 'F1') */
+    key: string;
+    /** Key code (optional) */
+    code?: string;
+    /** Event type */
+    type: 'keydown' | 'keyup';
+}
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Display alert payload.
+ * Request from game to show platform-level alert.
+ */
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Connection state payload.
+ * Broadcast from platform to games when connection changes.
+ */
+interface ConnectionStatePayload {
+    state: 'online' | 'offline' | 'degraded';
+    reason: string;
+}
+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;
+    };
+}
+type GameContextPayload = {
+    token: string;
+    baseUrl: string;
+    realtimeUrl: string;
+    gameId: string;
+    forwardKeys?: string[];
+};
+type LoginResponse = {
+    token: string;
+};
+type GameTokenResponse = {
+    token: string;
+    exp: number;
+};
+type StartSessionResponse = {
+    sessionId: string;
+};
+type InventoryMutationResponse = {
+    newTotal: number;
+};
+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;
+};
+/**
+ * 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;
+}
+/**
+ * Bucket file metadata
+ */
+interface BucketFile {
+    key: string;
+    size: number;
+    uploaded: string;
+    contentType?: 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).
+ */
+
+/**
+ * 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;
 }
-declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
 
 /**
  * @fileoverview Playcademy Messaging System
@@ -4527,6 +5053,14 @@ 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.
@@ -4556,6 +5090,14 @@ 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",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -4611,6 +5153,8 @@ type 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;
     /** Exit message has no payload data */
@@ -4619,6 +5163,8 @@ type MessageEventMap = {
     [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 */
@@ -4990,5 +5536,5 @@ declare class PlaycademyMessaging {
  */
 declare const messaging: PlaycademyMessaging;
 
-export { ApiError, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorInfo, DevUploadEvent, DevUploadHooks };
+export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
+export type { ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload };