@playcademy/sdk 0.2.1 → 0.2.2

package/dist/types.d.ts

@@ -1,8 +1,7 @@
-import * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
-import * as _playcademy_timeback_types from '@playcademy/timeback/types';
-import { CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { z } from 'zod';
+import * as _playcademy_timeback_types from '@playcademy/timeback/types';
+import { CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
@@ -2453,13 +2452,66 @@ type MapObject = typeof mapObjects.$inferSelect;
 type User = typeof users.$inferSelect;
 type UserRoleEnumType = (typeof userRoleEnum.enumValues)[number];
 type DeveloperStatusResponse = z.infer<typeof DeveloperStatusResponseSchema>;
+/**
+ * TimeBack enrollment information for a game.
+ */
+type UserEnrollment = {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+};
+/**
+ * TimeBack user role (matches OneRoster spec).
+ */
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+/**
+ * Organization type (matches OneRoster spec).
+ */
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * TimeBack organization data for a user.
+ * Represents schools, districts, or other educational organizations.
+ */
+type UserOrganization = {
+    /** Organization ID (OneRoster sourcedId) */
+    id: string;
+    /** Organization name */
+    name: string | null;
+    /** Organization type (school, district, etc.) */
+    type: TimebackOrgType | string;
+    /** Whether this is the user's primary organization */
+    isPrimary: boolean;
+};
+/**
+ * TimeBack student profile (role + organizations).
+ * Subset of UserTimebackData returned by OneRoster API.
+ */
+type TimebackStudentProfile = {
+    /** User's primary role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's organizations (schools/districts) */
+    organizations: UserOrganization[];
+};
+/**
+ * TimeBack-related data for a user.
+ */
+type UserTimebackData = TimebackStudentProfile & {
+    /** User's TimeBack ID (sourcedId) */
+    id: string;
+    /** Course enrollments */
+    enrollments: UserEnrollment[];
+};
 /**
  * User data with authentication provider information.
  * Returned by the /users/me endpoint with additional auth context.
  */
-type AuthenticatedUser = User & {
+type AuthenticatedUser = Omit<User, 'timebackId'> & {
     /** Whether the user authenticated via Timeback SSO */
     hasTimebackAccount: boolean;
+    /** TimeBack data (id, role, enrollments, organizations) - only present if user has a timeback account */
+    timeback?: UserTimebackData;
 };
 
 /**
@@ -2706,6 +2758,9 @@ type EndActivityResponse = {
     inProgress?: string;
 };
 
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
 /**
  * Connection monitoring types
  *
@@ -2720,6 +2775,180 @@ type EndActivityResponse = {
  */
 type ConnectionState = 'online' | 'offline' | 'degraded';
 
+/**
+ * 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;
+}
+
 /**
  * @fileoverview Playcademy Messaging System
  *
@@ -2931,208 +3160,103 @@ declare function init<T extends PlaycademyClient = PlaycademyClient>(this: new (
  */
 declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
 
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * @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>;
+}
 
 /**
- * Main Playcademy SDK client for interacting with the platform API.
- * Provides namespaced access to all platform features including games, users, inventory, and more.
+ * 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 class PlaycademyClient {
+declare abstract class PlaycademyBaseClient {
     baseUrl: string;
     gameUrl?: string;
-    private authStrategy;
-    private gameId?;
-    private config;
-    private listeners;
-    private internalClientSessionId?;
-    private authContext?;
-    private initPayload?;
-    private connectionManager?;
+    protected authStrategy: AuthStrategy;
+    protected gameId?: string;
+    protected config: Partial<ClientConfig>;
+    protected listeners: EventListeners;
+    protected internalClientSessionId?: string;
+    protected authContext?: {
+        isInIframe: boolean;
+    };
+    protected initPayload?: InitPayload;
+    protected connectionManager?: ConnectionManager;
     /**
      * Internal session manager for automatic session lifecycle.
-     *
-     * This manager handles starting and ending game sessions automatically.
-     * Game developers don't need to call these methods directly - they're managed
-     * by the SDK during initialization and cleanup.
-     *
      * @private
      * @internal
      */
-    private _sessionManager;
-    /**
-     * Creates a new PlaycademyClient instance.
-     *
-     * @param config - Optional configuration object
-     * @param config.baseUrl - Base URL (e.g., 'https://hub.playcademy.net' or '/'). SDK automatically appends /api
-     * @param config.token - Authentication token
-     * @param config.tokenType - Optional token type (auto-detected if not provided)
-     * @param config.gameId - Game ID for automatic session management
-     * @param config.autoStartSession - Automatically start a game session?
-     */
+    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.
-     * Converts relative URLs to absolute URLs in browser environments.
-     * Note: baseUrl already includes /api suffix from constructor.
-     *
-     * @returns The complete base URL for API requests (with /api suffix)
      */
     getBaseUrl(): string;
     /**
      * Gets the effective game backend URL for integration requests.
-     * Throws if gameUrl is not configured.
-     *
-     * @returns The complete game backend URL for API requests (with /api suffix)
-     * @throws PlaycademyError if gameUrl is not set
      */
-    private getGameBackendUrl;
+    protected getGameBackendUrl(): string;
     /**
      * Simple ping method for testing connectivity.
-     *
-     * @returns 'pong' string response
      */
     ping(): string;
     /**
      * Sets the authentication token for API requests.
-     * Emits an 'authChange' event when the token changes.
-     *
-     * @param token - The authentication token, or null to clear
-     * @param tokenType - Optional token type (auto-detected if not provided)
      */
     setToken(token: string | null, tokenType?: TokenType): void;
     /**
      * Gets the current token type.
-     *
-     * @returns The token type
      */
     getTokenType(): TokenType;
     /**
      * Gets the current authentication token.
-     *
-     * @returns The current token or null if not authenticated
-     *
-     * @example
-     * ```typescript
-     * // Send token to your backend for verification
-     * const token = client.getToken()
-     * const response = await fetch('/api/auth/playcademy', {
-     *     method: 'POST',
-     *     body: JSON.stringify({ gameToken: token })
-     * })
-     * ```
      */
     getToken(): string | null;
     /**
-     * Checks if the client has a valid API token for making Playcademy API requests.
-     *
-     * For games (iframe context): Checks if we have a valid token from the parent.
-     * For Cademy (standalone): Checks if we have a token from better-auth.
-     *
-     * Note: This checks for API authentication, not whether a user has linked
-     * their identity via OAuth.
-     *
-     * @returns true if API token exists, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (client.isAuthenticated()) {
-     *     // Can make API calls
-     *     const games = await client.games.list()
-     * } else {
-     *     console.error('No API token available')
-     * }
-     * ```
+     * Checks if the client has a valid API token.
      */
     isAuthenticated(): boolean;
     /**
      * Registers a callback to be called when authentication state changes.
-     *
-     * @param callback - Function to call when auth state changes
      */
     onAuthChange(callback: (token: string | null) => void): 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 Connection monitoring documentation in SDK Browser docs for detailed usage examples
-     * @see {@link ConnectionManager.onDisconnect} for the underlying implementation
      */
     onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
     /**
      * 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: {
@@ -3140,28 +3264,14 @@ declare class PlaycademyClient {
     }): void;
     /**
      * Registers an event listener for client events.
-     *
-     * @param event - The event type to listen for
-     * @param callback - Function to call when the event is emitted
      */
     on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
     /**
      * Emits an event to all registered listeners.
-     *
-     * @param event - The event type to emit
-     * @param payload - The event payload
      */
-    private emit;
+    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
     /**
      * Makes an authenticated HTTP request to the platform API.
-     *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param options - Optional request configuration
-     * @param options.body - Request body
-     * @param options.headers - Additional headers
-     * @param options.raw - If true, returns raw Response instead of parsing
-     * @returns Promise resolving to the response data or raw Response
      */
     protected request<T>(path: string, method: Method, options?: {
         body?: unknown;
@@ -3170,49 +3280,64 @@ declare class PlaycademyClient {
     }): Promise<T>;
     /**
      * Makes an authenticated HTTP request to the game's backend Worker.
-     * Uses gameUrl if set, otherwise falls back to platform API.
-     *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param body - Request body (optional)
-     * @param headers - Additional headers (optional)
-     * @param raw - If true, returns raw Response instead of parsing (optional)
-     * @returns Promise resolving to the response data or raw Response
      */
     protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, raw?: boolean): Promise<T>;
     /**
      * Ensures a gameId is available, throwing an error if not.
-     *
-     * @returns The gameId
-     * @throws PlaycademyError if no gameId is configured
      */
-    private _ensureGameId;
+    protected _ensureGameId(): string;
     /**
      * Detects and sets the authentication context (iframe vs standalone).
-     * 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:
-     * 1. A gameId is configured
-     * 2. No session already exists
-     * 3. autoStartSession is enabled (defaults to false)
      */
     private _initializeInternalSession;
-    /** Identity provider connection methods (connect external accounts) */
+    /**
+     * 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>;
+        };
+    };
+}
+
+/**
+ * Playcademy SDK client for game developers.
+ * Provides namespaced access to platform features for games running inside Cademy.
+ */
+declare class PlaycademyClient extends PlaycademyBaseClient {
+    /**
+     * Connect external identity providers to the user's Playcademy account.
+     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
+     */
     identity: {
         connect: (options: AuthOptions) => Promise<AuthResult>;
         _getContext: () => {
             isInIframe: boolean;
         };
     };
-    /** Runtime methods (getGameToken, exit) */
+    /**
+     * Game runtime lifecycle and asset loading.
+     * - `exit()` - Return to Cademy hub
+     * - `getGameToken()` - Get short-lived auth token
+     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
+     * - `on('pause')`, `on('resume')` - Handle visibility changes
+     */
     runtime: {
         getGameToken: (gameId: string, options?: {
             apply?: boolean;
@@ -3247,42 +3372,58 @@ declare class PlaycademyClient {
             arrayBuffer: (path: string) => Promise<ArrayBuffer>;
         };
     };
-    /** User methods (me, inventory management) */
-    users: {
-        me: () => Promise<AuthenticatedUser>;
-        inventory: {
-            get: () => Promise<InventoryItemWithItem[]>;
-            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            quantity: (identifier: string) => Promise<number>;
-            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-        };
-    };
-    /** TimeBack XP methods (today, total, history) */
+    /**
+     * TimeBack integration for activity tracking and user context.
+     *
+     * User context (cached from init, refreshable):
+     * - `user.role` - User's role (student, parent, teacher, etc.)
+     * - `user.enrollments` - Courses the player is enrolled in for this game
+     * - `user.organizations` - Schools/districts the player belongs to
+     * - `user.fetch()` - Refresh user context from server
+     *
+     * Activity tracking:
+     * - `startActivity(metadata)` - Begin tracking an activity
+     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
+     * - `endActivity(scoreData)` - Submit activity results to TimeBack
+     */
     timeback: {
+        readonly user: TimebackUser;
         startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
     };
-    /** Credits methods (credits management) */
+    /**
+     * 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>;
     };
-    /** Platform-wide scores methods (submit, getUserScores) */
+    /**
+     * Game score submission and leaderboards.
+     * - `submit(gameId, score, metadata?)` - Record a game score
+     */
     scores: {
         submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
     };
-    /** Realtime methods (token) */
+    /**
+     * Realtime multiplayer authentication.
+     * - `getToken()` - Get token for WebSocket/realtime connections
+     */
     realtime: {
         token: {
             get: () => Promise<RealtimeTokenResponse>;
         };
-        open(channel?: string, url?: string): Promise<_playcademy_realtime_server_types.RealtimeChannel>;
     };
-    /** Backend methods for calling custom game API routes */
+    /**
+     * Make requests to your game's custom backend API routes.
+     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
+     * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
+     */
     backend: {
         get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
         post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
@@ -3303,9 +3444,70 @@ declare class PlaycademyClient {
     };
 }
 
+/**
+ * Type definitions for the game timeback namespace.
+ *
+ * Re-exports core types from @playcademy/data for SDK consumers,
+ * plus SDK-specific types like TimebackInitContext.
+ */
+
+/**
+ * A TimeBack enrollment for the current game session.
+ * Alias for UserEnrollment without the optional gameId.
+ */
+type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
+/**
+ * A TimeBack organization (school/district) for the current user.
+ * Alias for UserOrganization.
+ */
+type TimebackOrganization = UserOrganization;
+/**
+ * TimeBack context passed during game initialization.
+ * This is sent from the platform (cademy) to the game iframe via postMessage.
+ */
+interface TimebackInitContext {
+    /** User's TimeBack ID */
+    id: string;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's enrollments for this game (one per grade/subject combo) */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
+}
+/**
+ * TimeBack user context with current data (may be stale from init).
+ * Use `fetch()` to get fresh data from the server.
+ */
+interface TimebackUserContext {
+    /** User's TimeBack ID */
+    id: string | undefined;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole | undefined;
+    /** User's enrollments for this game */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
+}
+/**
+ * TimeBack user object with both cached getters and fetch method.
+ */
+interface TimebackUser extends TimebackUserContext {
+    /**
+     * Fetch TimeBack data from the server (cached for 5 min).
+     * Updates the cached values so subsequent property access returns fresh data.
+     * @param options - Cache options (pass { force: true } to bypass cache)
+     * @returns Promise resolving to fresh user context
+     */
+    fetch(options?: {
+        force?: boolean;
+    }): Promise<TimebackUserContext>;
+}
+
 /**
  * Core client configuration and lifecycle types
  */
+
 type TokenType = 'session' | 'apiKey' | 'gameJwt';
 interface ClientConfig {
     baseUrl: string;
@@ -3349,6 +3551,8 @@ interface InitPayload {
     gameId: string;
     /** Realtime WebSocket URL */
     realtimeUrl?: string;
+    /** Timeback context (if user has a Timeback account) */
+    timeback?: TimebackInitContext;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -3695,29 +3899,37 @@ type DevUploadHooks = {
 /**
  * Platform TimeBack Types
  *
- * Types for TimeBack enrollment and student data on the platform side.
- * These are used by the cademy hub to determine which games users have access to.
+ * Types for TimeBack data on the platform side.
+ * Unlike game types, these include gameId for cross-game enrollment views.
  */
 
 /**
- * Enrollment data for a student in a specific game/course.
- * Represents the mapping between a TimeBack course and a Playcademy game.
+ * Platform TimeBack user context.
+ * Unlike game context, enrollments include gameId for cross-game views.
  */
-interface StudentEnrollment {
-    /** The Playcademy game ID the student is enrolled in */
-    gameId: string;
-    /** The grade level for this enrollment */
-    grade: number;
-    /** The subject area (e.g., 'Math', 'Science') */
-    subject: string;
-    /** The TimeBack course ID */
-    courseId: string;
+interface PlatformTimebackUserContext {
+    /** User's TimeBack ID */
+    id: string | undefined;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole | undefined;
+    /** User's enrollments across ALL games (includes gameId) */
+    enrollments: UserEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: UserOrganization[];
 }
 /**
- * Response from the enrollments endpoint
+ * Platform TimeBack user object with both cached getters and fetch method.
  */
-interface EnrollmentsResponse {
-    enrollments: StudentEnrollment[];
+interface PlatformTimebackUser extends PlatformTimebackUserContext {
+    /**
+     * Fetch TimeBack data from the server (cached for 5 min).
+     * Updates the cached values so subsequent property access returns fresh data.
+     * @param options - Cache options (pass { force: true } to bypass cache)
+     * @returns Promise resolving to user context with full enrollment data
+     */
+    fetch(options?: {
+        force?: boolean;
+    }): Promise<PlatformTimebackUserContext>;
 }
 /**
  * Combined response type for xp.summary() method
@@ -3906,4 +4118,4 @@ interface PlaycademyServerClientState {
 }
 
 export { PlaycademyClient };
-export type { Achievement, AchievementCurrent, AchievementProgressResponse, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CreateCharacterData, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EnrollmentsResponse, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, StudentEnrollment, TelemetryPayload, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, User, UserInfo, UserLevel, UserLevelWithConfig, UserRank, UserRankResponse, UserRoleEnumType, UserScore, XpHistoryResponse, XpSummaryResponse };
+export type { Achievement, AchievementCurrent, AchievementProgressResponse, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CreateCharacterData, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserRole, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, User, UserEnrollment, UserInfo, UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XpHistoryResponse, XpSummaryResponse };