@playcademy/sdk 0.9.0 → 0.9.1-beta.2

package/dist/index.d.ts

@@ -1,5 +1,5 @@
+import { UserRole, AUTH_PROVIDER_IDS } from '@playcademy/constants';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
  * Base error class for Cademy SDK specific errors.
@@ -384,6 +384,125 @@ interface RetryPolicy {
     retryableMethods?: readonly Method[];
 }
 
+/**
+ * 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;
+}
+
 /**
  * TimeBack Enums & Literal Types
  *
@@ -499,117 +618,18 @@ interface AdvanceCourseResponse {
 }
 
 /**
- * User Types
- *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
- *
- * @module types/user
- */
-type UserRoleEnumType = 'admin' | 'player' | 'developer' | 'teacher';
-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;
-    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
+ * Cache configuration types for runtime customization
  */
-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.
+ * Runtime configuration for TTL cache behavior
  */
-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;
+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;
 }
 
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
@@ -889,40 +909,211 @@ type InventoryItemWithItem = InventoryItemRow & {
 };
 
 /**
- * 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()
+ * @fileoverview Authentication Strategy Pattern
  *
- * // With custom base URL
- * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
- * ```
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
  */
-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.
+ * 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>;
+        };
+    };
+}
+
+/**
+ * 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
@@ -1538,225 +1729,6 @@ declare class PlaycademyMessaging {
  */
 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.
-     *
-     * Pass the same `runId` across multiple `startActivity()` calls (for
-     * example, after the player closes and reopens a resumable activity) so
-     * downstream systems can correlate related sessions into a single run.
-     *
-     * Must be a UUID (the backend validates it as such) and unique per
-     * logical run. If omitted, the SDK generates a new UUID on each call,
-     * which means every session is treated as its own run.
-     */
-    runId?: string;
-}
-
 /**
  * Playcademy SDK client for game developers.
  * Provides namespaced access to platform features for games running inside Cademy.
@@ -1819,19 +1791,22 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * 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.refresh({ only: ['enrollments'] })` - Refresh enrollments from server
      * - `user.organizations` - Schools/districts the player belongs to
      * - `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: ActivityData, options?: StartActivityOptions) => StartActivityResult;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
@@ -1911,6 +1886,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.
  *
@@ -1920,7 +1946,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
 
 /**
  * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId.
+ * Alias for UserEnrollment without the optional gameId. Active enrollment IDs
+ * are available at `enrollment.enrollmentIds?.active` when supplied by the
+ * platform.
  */
 type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
@@ -1956,6 +1984,14 @@ interface TimebackUserContext {
     /** User's organizations (schools/districts) */
     organizations: TimebackOrganization[];
 }
+/**
+ * Slice options for refreshing the cached TimeBack user context.
+ */
+type TimebackUserRefreshField = 'enrollments';
+interface TimebackUserRefreshOptions extends TTLCacheConfig {
+    /** Refresh only these user data fields */
+    only: readonly TimebackUserRefreshField[];
+}
 /**
  * XP data access for the current user.
  * Results are cached for 5 seconds to avoid redundant network requests.
@@ -1996,7 +2032,7 @@ interface TimebackUserXp {
     fetch(options?: GetXpOptions): Promise<XpResponse>;
 }
 /**
- * TimeBack user object with both cached getters and fetch method.
+ * TimeBack user object with cached getters, fetch, and targeted refresh methods.
  */
 interface TimebackUser extends TimebackUserContext {
     /**
@@ -2005,9 +2041,14 @@ interface TimebackUser extends TimebackUserContext {
      * @param options - Cache options (pass { force: true } to bypass cache)
      * @returns Promise resolving to fresh user context
      */
-    fetch(options?: {
-        force?: boolean;
-    }): Promise<TimebackUserContext>;
+    fetch(options?: TTLCacheConfig): Promise<TimebackUserContext>;
+    /**
+     * Refresh selected TimeBack user data from the server.
+     * Updates the cached user snapshot used by the synchronous getters.
+     * @param options - Refresh fields and cache options
+     * @returns Promise resolving to the updated user context
+     */
+    refresh(options: TimebackUserRefreshOptions): Promise<TimebackUserContext>;
     /**
      * XP data for the current user.
      * Call `xp.fetch()` to get XP from the server.