@playcademy/sdk 0.14.0 → 0.14.1-beta.1

package/dist/internal.d.ts

@@ -2,8 +2,8 @@ import { SchemaInfo } from '@playcademy/cloudflare';
 import { TimebackGrade, TimebackSubject, HeartbeatRequest, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
 export { QtiTestQuestionRef, QtiTestQuestionsResponse } from '@playcademy/types/timeback';
 import * as _playcademy_types from '@playcademy/types';
-import { GameManifest } from '@playcademy/types';
-export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
+import { GameManifest, LocalDayContext } from '@playcademy/types';
+export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { z } from 'zod';
 import { DomainValidationRecords } from '@playcademy/types/game';
@@ -756,951 +756,273 @@ interface AuthStrategy {
     getHeaders(): Record<string, string>;
 }
 
+declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "user";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: drizzle_orm_pg_core.PgColumn<{
+            name: "name";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        username: drizzle_orm_pg_core.PgColumn<{
+            name: "username";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        email: drizzle_orm_pg_core.PgColumn<{
+            name: "email";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        isAnonymous: drizzle_orm_pg_core.PgColumn<{
+            name: "is_anonymous";
+            tableName: "user";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timebackId: drizzle_orm_pg_core.PgColumn<{
+            name: "timeback_id";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        learningTimeZone: drizzle_orm_pg_core.PgColumn<{
+            name: "learning_time_zone";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        learningTimeZoneUpdatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "learning_time_zone_updated_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        emailVerified: drizzle_orm_pg_core.PgColumn<{
+            name: "email_verified";
+            tableName: "user";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        image: drizzle_orm_pg_core.PgColumn<{
+            name: "image";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        role: drizzle_orm_pg_core.PgColumn<{
+            name: "role";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "admin" | "developer" | "player" | "teacher";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["admin", "player", "developer", "teacher"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        developerStatus: drizzle_orm_pg_core.PgColumn<{
+            name: "developer_status";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "approved" | "none" | "pending";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["none", "pending", "approved"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>;
+
+interface GameMetadata {
+    description?: string;
+    emoji?: string;
+    [key: string]: unknown;
+}
 /**
- * Base Playcademy SDK client with shared infrastructure.
- * Provides authentication, HTTP requests, events,
- * and fundamental namespaces used by all clients.
- *
- * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
+ * DNS validation records for custom hostname
+ * Structure for the validationRecords JSON field in game_custom_hostnames table
  */
-declare abstract class PlaycademyBaseClient {
-    baseUrl: string;
-    gameUrl?: string;
-    mode: PlaycademyMode;
-    protected authStrategy: AuthStrategy;
-    protected gameId?: string;
-    protected config: Partial<ClientConfig>;
-    protected listeners: EventListeners;
-    protected authContext?: {
-        isInIframe: boolean;
-    };
-    protected initPayload?: InitPayload;
-    protected launchId?: string;
-    protected gameOrigin?: string;
-    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;
-    /**
-     * 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;
-    private _parseOrigin;
-    /**
-     * Detects and sets the authentication context (iframe vs standalone).
-     */
-    private _detectAuthContext;
-    /**
-     * Current user data.
-     * - `me()` - Get authenticated user profile
-     */
-    users: {
-        me: () => Promise<_playcademy_types.AuthenticatedUser>;
+interface CustomHostnameValidationRecords {
+    /** TXT record for ownership verification */
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
     };
-}
-
-/**
- * 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[];
-}): Promise<T>;
-
-/**
- * Authenticates a user with email and password.
- *
- * This is a standalone authentication method that doesn't require an initialized client.
- * Use this for login flows before creating a client instance.
- *
- * @deprecated Use client.auth.login() instead for better error handling and automatic token management
- *
- * @param baseUrl - The base URL of the Playcademy API
- * @param email - User's email address
- * @param password - User's password
- * @returns Promise resolving to authentication response with token
- * @throws PlaycademyError if authentication fails or network error occurs
- *
- * @example
- * ```typescript
- * // Preferred approach:
- * const client = new PlaycademyClient({ baseUrl: '/api' })
- * const result = await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password'
- * })
- *
- * // Legacy approach (still works):
- * try {
- *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
- *   const client = new PlaycademyClient({ token: response.token })
- * } catch (error) {
- *   console.error('Login failed:', error.message)
- * }
- * ```
- */
-declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
-
-/**
- * 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;
-}
-
-/**
- * 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.
- *
- * SDK-specific types like TimebackInitContext that wrap the core types
- * from @playcademy/types/user (which are re-exported via types/data.ts).
- */
-
-/**
- * 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[];
-}
-/**
- * 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.
- */
-interface TimebackUserXp {
-    /**
-     * Fetch XP data from the server.
-     * Returns XP for all courses in this game, or filter by grade/subject.
-     * Results are cached for 5 seconds (use `force: true` to bypass).
-     *
-     * @param options - Query options
-     * @param options.grade - Grade level to filter (must be used with subject)
-     * @param options.subject - Subject to filter (must be used with grade)
-     * @param options.include - Additional data to include: 'perCourse', 'today'
-     * @param options.force - Bypass cache and fetch fresh data (default: false)
-     * @returns Promise resolving to XP data
-     *
-     * @example
-     * ```typescript
-     * // Get total XP for all game courses
-     * const xp = await client.timeback.user.xp.fetch()
-     *
-     * // Get XP for a specific grade/subject
-     * const xp = await client.timeback.user.xp.fetch({
-     *   grade: 3,
-     *   subject: 'Math'
-     * })
-     *
-     * // Get XP with per-course breakdown
-     * const xp = await client.timeback.user.xp.fetch({
-     *   include: ['perCourse', 'today']
-     * })
-     *
-     * // Force fresh data
-     * const xp = await client.timeback.user.xp.fetch({ force: true })
-     * ```
-     */
-    fetch(options?: GetXpOptions): Promise<XpResponse>;
-}
-/**
- * TimeBack user object with cached getters, fetch, and targeted refresh methods.
- */
-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?: 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.
-     */
-    xp: TimebackUserXp;
-    /**
-     * Mastery data for the current user.
-     * Call `mastery.fetch()` to get mastery progress from the server.
-     */
-    mastery: TimebackUserMastery;
-    /**
-     * Highest-grade-mastered data for the current user.
-     * Call `highestGradeMastered.fetch({ subject })` to get the student's
-     * highest mastered grade for a subject.
-     */
-    highestGradeMastered: TimebackUserHighestGradeMastered;
-}
-/**
- * Mastery data access for the current user.
- * Results are cached for 5 seconds to avoid redundant network requests.
- */
-interface TimebackUserMastery {
-    /**
-     * Fetch mastery data from the server.
-     * Returns mastery for all courses in this game, or filter by grade/subject.
-     * Returned masteredUnits values are true analytics values and may exceed
-     * the course masterableUnits maximum when historical data violates the
-     * expected invariant.
-     * Results are cached for 5 seconds (use `force: true` to bypass).
-     *
-     * @param options - Query options
-     * @param options.grade - Grade level to filter (must be used with subject)
-     * @param options.subject - Subject to filter (must be used with grade)
-     * @param options.include - Additional data to include: 'perCourse'
-     * @param options.force - Bypass cache and fetch fresh data (default: false)
-     * @returns Promise resolving to mastery data
-     *
-     * @example
-     * ```typescript
-     * // Get total mastery for all game courses
-     * const mastery = await client.timeback.user.mastery.fetch()
-     *
-     * // Get mastery for a specific grade/subject
-     * const mastery = await client.timeback.user.mastery.fetch({
-     *   grade: 3,
-     *   subject: 'Math'
-     * })
-     *
-     * // Get mastery with per-course breakdown
-     * const mastery = await client.timeback.user.mastery.fetch({
-     *   include: ['perCourse']
-     * })
-     *
-     * // Force fresh data
-     * const mastery = await client.timeback.user.mastery.fetch({ force: true })
-     * ```
-     */
-    fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
-}
-/**
- * Highest-grade-mastered data access for the current user.
- * Results are cached for 5 seconds to avoid redundant network requests.
- */
-interface TimebackUserHighestGradeMastered {
-    /**
-     * Fetch the highest grade the current student has mastered for a subject.
-     * Results are cached for 5 seconds (use `force: true` to bypass).
-     */
-    fetch(options: GetHighestGradeMasteredOptions): Promise<HighestGradeMasteredResponse>;
-}
-/**
- * Options for querying student XP.
- */
-interface GetXpOptions {
-    /** Grade level to filter (must be used with subject) */
-    grade?: TimebackGrade;
-    /** Subject to filter (must be used with grade) */
-    subject?: TimebackSubject;
-    /** Additional data to include: 'perCourse', 'today' */
-    include?: ('perCourse' | 'today')[];
-    /** Bypass cache and fetch fresh data (default: false) */
-    force?: boolean;
-}
-/**
- * Options for querying student mastery.
- */
-interface GetMasteryOptions {
-    /** Grade level to filter (must be used with subject) */
-    grade?: TimebackGrade;
-    /** Subject to filter (must be used with grade) */
-    subject?: TimebackSubject;
-    /** Additional data to include: 'perCourse' */
-    include?: 'perCourse'[];
-    /** Bypass cache and fetch fresh data (default: false) */
-    force?: boolean;
-}
-/**
- * Options for querying highest grade mastered.
- */
-interface GetHighestGradeMasteredOptions {
-    /** Subject to query */
-    subject: TimebackSubject;
-    /** Bypass cache and fetch fresh data (default: false) */
-    force?: boolean;
-}
-/**
- * XP data for a single course.
- */
-interface CourseXp {
-    grade: TimebackGrade;
-    subject: TimebackSubject;
-    title: string;
-    totalXp: number;
-    todayXp?: number;
-}
-/**
- * Response from XP query.
- */
-interface XpResponse {
-    totalXp: number;
-    todayXp?: number;
-    courses?: CourseXp[];
-}
-interface CourseMastery {
-    grade: TimebackGrade;
-    subject: TimebackSubject;
-    title: string;
-    /** True mastered units from analytics. May exceed masterableUnits for historical data. */
-    masteredUnits: number;
-    /** Configured mastery ceiling for the course. */
-    masterableUnits: number;
-    /** Clamped course completion percentage from 0..100. */
-    pctComplete: number;
-    isComplete: boolean;
-}
-/**
- * Response from mastery query.
- */
-interface MasteryResponse {
-    /** True mastered units across all queried courses. */
-    totalMasteredUnits: number;
-    /** Configured mastery ceiling across all queried courses. */
-    totalMasterableUnits: number;
-    courses?: CourseMastery[];
-}
-/**
- * Response from highest-grade-mastered query.
- */
-interface HighestGradeMasteredResponse {
-    subject: TimebackSubject;
-    highestGradeMastered: TimebackGrade | null;
-}
-
-/**
- * Core client configuration and lifecycle types
- */
-
-type TokenType = 'session' | 'apiKey' | 'gameJwt';
-/**
- * Runtime mode for a Playcademy game client.
- *
- * - `'platform'` — game is embedded in the platform (e.g. the cademy hub)
- *   with a real authenticated user and full access to SDK namespaces.
- * - `'demo'` — game is embedded in the landing page demo shell with an
- *   anonymous user; platform-only namespaces throw, and `client.demo.*`
- *   is the supported surface for signaling demo lifecycle events and
- *   reading/updating the anonymous profile.
- * - `'standalone'` — game is running outside any iframe (e.g. `bun run dev`
- *   or direct-deploy preview) with a mock token and no real platform
- *   context. API calls will not succeed; use this to branch UX locally.
- */
-type PlaycademyMode = 'platform' | 'demo' | 'standalone';
-interface ClientConfig {
-    baseUrl: string;
-    gameUrl?: string;
-    token?: string;
-    tokenType?: TokenType;
-    gameId?: string;
-    launchId?: string;
-    mode?: PlaycademyMode;
-}
-interface InitPayload {
-    /** Hub API base URL */
-    baseUrl: string;
-    /** Game deployment URL (serves both frontend assets and backend API) */
-    gameUrl?: string;
-    /** Short-lived game token */
-    token: string;
-    /** Game ID */
-    gameId: string;
-    /** Timeback context (if user has a Timeback account) */
-    timeback?: TimebackInitContext;
-    /** Runtime mode for the game client */
-    mode?: PlaycademyMode;
-    /** Launch session correlation ID (UUID, set by platform on game launch) */
-    launchId?: string;
-    /** When `true`, the parent shell provides a heartbeat relay via postMessage, so the SDK can skip its own `fetch({ keepalive })` beacon on pagehide. Defaults to `false`. */
-    hasHeartbeatRelay?: boolean;
-}
-/**
- * Simplified user data passed to games via InitPayload
- * This is a subset of AuthenticatedUser suitable for external game consumption
- *
- * Note: Named GameInitUser to distinguish from the cross-game GameUser DTO
- * exported from @playcademy/types
- */
-interface GameInitUser {
-    /** Playcademy user ID */
-    id: string;
-    /** Unique username */
-    username: string | null;
-    /** Display name */
-    name: string | null;
-    /** Email address */
-    email: string | null;
-    /** Profile image URL */
-    image: string | null;
-    /** Whether the user has a Timeback account */
-    hasTimebackAccount: boolean;
-}
-interface GameContextPayload {
-    token: string;
-    baseUrl: string;
-    gameId: string;
-    forwardKeys?: string[];
-    mode?: PlaycademyMode;
-}
-type EventListeners = {
-    [E in keyof ClientEvents]?: ((payload: ClientEvents[E]) => void)[];
-};
-interface ClientEvents {
-    authChange: {
-        token: string | null;
-    };
-}
-
-/**
- * Event and message payload types for SDK messaging system
- */
-
-/**
- * Authentication state change event payload.
- * Used when authentication state changes in the application.
- */
-interface AuthStateChangePayload {
-    /** Whether the user is currently authenticated */
-    authenticated: boolean;
-    /** User information if authenticated, null otherwise */
-    user: UserInfo | null;
-    /** Error information if authentication failed */
-    error: Error | null;
-}
-/**
- * OAuth callback event payload.
- * Used when OAuth flow completes in popup/new-tab windows.
- */
-interface AuthCallbackPayload {
-    /** OAuth authorization code */
-    code: string;
-    /** OAuth state parameter for CSRF protection */
-    state: string;
-    /** Error message if OAuth flow failed */
-    error: string | null;
-}
-/**
- * Message sent from server callback to opener window.
- * This is the standardized format from our server-first architecture.
- */
-interface AuthServerMessage {
-    /** Type of the message */
-    type: 'PLAYCADEMY_AUTH_STATE_CHANGE';
-    /** Whether the user is currently authenticated */
-    authenticated: boolean;
-    /** Whether the authentication was successful */
-    success: boolean;
-    /** Timestamp of the message */
-    ts: number;
-    /** User information if authentication was successful */
-    user?: UserInfo;
-    /** Error message if authentication failed */
-    error?: string;
-}
-/**
- * Token refresh event payload.
- * Sent when authentication token is updated.
- */
-interface TokenRefreshPayload {
-    /** New authentication token */
-    token: string;
-    /** Token expiration timestamp */
-    exp: number;
-}
-/**
- * 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';
-}
-/**
- * Init error payload.
- * Sent from game iframe to parent when SDK initialization fails
- * (e.g. origin validation failure, INIT timeout, client creation error).
- */
-interface InitErrorPayload {
-    reason: string;
-}
-/**
- * Options for `client.demo.end(score, options?)`.
- *
- * All optional. The landing-page demo shell can render a meaningful CTA
- * from `score` alone, but `durationMs` enables a nicer summary and
- * `metadata` lets games pass any extra context they want to surface.
- */
-interface DemoEndOptions {
-    durationMs?: number;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Wire payload for the `PLAYCADEMY_DEMO_END` message.
- *
- * `score` is required — the demo shell always needs something to display
- * when the round ends. `durationMs` and `metadata` are optional.
- */
-interface DemoEndPayload extends DemoEndOptions {
-    score: number;
-}
-type TimebackHeartbeatRelayRequest = Omit<HeartbeatRequest, 'gameId' | 'studentId' | 'windowStartedAtMs' | 'windowSequence'> & {
-    windowStartedAtMs: number;
-};
-
-/**
- * SDK-specific API response types
- */
-interface LoginResponse {
-    token: string;
-}
-interface GameTokenResponse {
-    token: string;
-    exp: number;
-    baseUrl?: string;
-}
-
-declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "user";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: true;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        name: drizzle_orm_pg_core.PgColumn<{
-            name: "name";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        username: drizzle_orm_pg_core.PgColumn<{
-            name: "username";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        email: drizzle_orm_pg_core.PgColumn<{
-            name: "email";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        isAnonymous: drizzle_orm_pg_core.PgColumn<{
-            name: "is_anonymous";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        timebackId: drizzle_orm_pg_core.PgColumn<{
-            name: "timeback_id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        emailVerified: drizzle_orm_pg_core.PgColumn<{
-            name: "email_verified";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        image: drizzle_orm_pg_core.PgColumn<{
-            name: "image";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        role: drizzle_orm_pg_core.PgColumn<{
-            name: "role";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "admin" | "developer" | "player" | "teacher";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["admin", "player", "developer", "teacher"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        developerStatus: drizzle_orm_pg_core.PgColumn<{
-            name: "developer_status";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "approved" | "none" | "pending";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["none", "pending", "approved"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        createdAt: drizzle_orm_pg_core.PgColumn<{
-            name: "created_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: 'pg';
-}>;
-
-interface GameMetadata {
-    description?: string;
-    emoji?: string;
-    [key: string]: unknown;
-}
-/**
- * DNS validation records for custom hostname
- * Structure for the validationRecords JSON field in game_custom_hostnames table
- */
-interface CustomHostnameValidationRecords {
-    /** TXT record for ownership verification */
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    /** TXT records for SSL certificate validation */
-    ssl?: {
-        txt_name?: string;
-        txt_value?: string;
-    }[];
+    /** TXT records for SSL certificate validation */
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
 }
 declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "games";
@@ -2212,146 +1534,866 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: 'pg';
-}>;
-declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
-    displayName: z.ZodString;
-    platform: z.ZodEnum<["web", "godot", "unity"]>;
-    metadata: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>>;
-    gameType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["hosted", "external"]>>>;
-    visibility: z.ZodOptional<z.ZodEnum<["visible", "unlisted", "internal"]>>;
-    externalUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, "strip", z.ZodTypeAny, {
-    displayName: string;
-    platform: "godot" | "unity" | "web";
-    metadata: Record<string, unknown>;
-    gameType: "external" | "hosted";
-    visibility?: "internal" | "unlisted" | "visible" | undefined;
-    externalUrl?: string | undefined;
-}, {
-    displayName: string;
-    platform: "godot" | "unity" | "web";
-    metadata?: Record<string, unknown> | undefined;
-    gameType?: "external" | "hosted" | undefined;
-    visibility?: "internal" | "unlisted" | "visible" | undefined;
-    externalUrl?: string | undefined;
-}>, {
-    displayName: string;
-    platform: "godot" | "unity" | "web";
-    metadata: Record<string, unknown>;
-    gameType: "external" | "hosted";
-    visibility?: "internal" | "unlisted" | "visible" | undefined;
-    externalUrl?: string | undefined;
-}, {
-    displayName: string;
-    platform: "godot" | "unity" | "web";
-    metadata?: Record<string, unknown> | undefined;
-    gameType?: "external" | "hosted" | undefined;
-    visibility?: "internal" | "unlisted" | "visible" | undefined;
-    externalUrl?: string | undefined;
-}>;
-declare const PatchGameMetadataSchema: z.ZodObject<{
-    displayName: z.ZodOptional<z.ZodString>;
-    visibility: z.ZodOptional<z.ZodEnum<["visible", "unlisted", "internal"]>>;
-    platform: z.ZodOptional<z.ZodEnum<["web", "godot", "unity"]>>;
-    metadata: z.ZodOptional<z.ZodObject<{
-        description: z.ZodOptional<z.ZodString>;
-        emoji: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    }, "strip", z.ZodTypeAny, {
-        description?: string | undefined;
-        emoji?: string | undefined;
-    }, {
-        description?: string | undefined;
-        emoji?: string | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    displayName?: string | undefined;
-    visibility?: "internal" | "unlisted" | "visible" | undefined;
-    platform?: "godot" | "unity" | "web" | undefined;
-    metadata?: {
-        description?: string | undefined;
-        emoji?: string | undefined;
-    } | undefined;
-}, {
-    displayName?: string | undefined;
-    visibility?: "internal" | "unlisted" | "visible" | undefined;
-    platform?: "godot" | "unity" | "web" | undefined;
-    metadata?: {
-        description?: string | undefined;
-        emoji?: string | undefined;
-    } | undefined;
-}>;
-declare const AddGameMemberSchema: z.ZodObject<{
-    userId: z.ZodString;
-    role: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"collaborator">>>;
-}, "strict", z.ZodTypeAny, {
-    userId: string;
-    role: "collaborator";
-}, {
-    userId: string;
-    role?: "collaborator" | undefined;
-}>;
-declare const UpdateGameMemberRoleSchema: z.ZodObject<{
-    role: z.ZodEnum<["owner", "collaborator"]>;
-}, "strict", z.ZodTypeAny, {
-    role: "collaborator" | "owner";
-}, {
-    role: "collaborator" | "owner";
-}>;
+    dialect: 'pg';
+}>;
+declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
+    displayName: z.ZodString;
+    platform: z.ZodEnum<["web", "godot", "unity"]>;
+    metadata: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>>;
+    gameType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["hosted", "external"]>>>;
+    visibility: z.ZodOptional<z.ZodEnum<["visible", "unlisted", "internal"]>>;
+    externalUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    displayName: string;
+    platform: "godot" | "unity" | "web";
+    metadata: Record<string, unknown>;
+    gameType: "external" | "hosted";
+    visibility?: "internal" | "unlisted" | "visible" | undefined;
+    externalUrl?: string | undefined;
+}, {
+    displayName: string;
+    platform: "godot" | "unity" | "web";
+    metadata?: Record<string, unknown> | undefined;
+    gameType?: "external" | "hosted" | undefined;
+    visibility?: "internal" | "unlisted" | "visible" | undefined;
+    externalUrl?: string | undefined;
+}>, {
+    displayName: string;
+    platform: "godot" | "unity" | "web";
+    metadata: Record<string, unknown>;
+    gameType: "external" | "hosted";
+    visibility?: "internal" | "unlisted" | "visible" | undefined;
+    externalUrl?: string | undefined;
+}, {
+    displayName: string;
+    platform: "godot" | "unity" | "web";
+    metadata?: Record<string, unknown> | undefined;
+    gameType?: "external" | "hosted" | undefined;
+    visibility?: "internal" | "unlisted" | "visible" | undefined;
+    externalUrl?: string | undefined;
+}>;
+declare const PatchGameMetadataSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    visibility: z.ZodOptional<z.ZodEnum<["visible", "unlisted", "internal"]>>;
+    platform: z.ZodOptional<z.ZodEnum<["web", "godot", "unity"]>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        emoji: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        emoji?: string | undefined;
+    }, {
+        description?: string | undefined;
+        emoji?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    displayName?: string | undefined;
+    visibility?: "internal" | "unlisted" | "visible" | undefined;
+    platform?: "godot" | "unity" | "web" | undefined;
+    metadata?: {
+        description?: string | undefined;
+        emoji?: string | undefined;
+    } | undefined;
+}, {
+    displayName?: string | undefined;
+    visibility?: "internal" | "unlisted" | "visible" | undefined;
+    platform?: "godot" | "unity" | "web" | undefined;
+    metadata?: {
+        description?: string | undefined;
+        emoji?: string | undefined;
+    } | undefined;
+}>;
+declare const AddGameMemberSchema: z.ZodObject<{
+    userId: z.ZodString;
+    role: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"collaborator">>>;
+}, "strict", z.ZodTypeAny, {
+    userId: string;
+    role: "collaborator";
+}, {
+    userId: string;
+    role?: "collaborator" | undefined;
+}>;
+declare const UpdateGameMemberRoleSchema: z.ZodObject<{
+    role: z.ZodEnum<["owner", "collaborator"]>;
+}, "strict", z.ZodTypeAny, {
+    role: "collaborator" | "owner";
+}, {
+    role: "collaborator" | "owner";
+}>;
+
+type GameRow = typeof games.$inferSelect;
+type BaseGame = Omit<GameRow, 'gameType' | 'deploymentUrl' | 'externalUrl'>;
+type HostedGame = BaseGame & {
+    gameType: 'hosted';
+    deploymentUrl: string;
+    externalUrl: null;
+};
+type ExternalGame = BaseGame & {
+    gameType: 'external';
+    deploymentUrl: null;
+    externalUrl: string;
+};
+type Game = HostedGame | ExternalGame;
+type GameMemberRow = typeof gameMembers.$inferSelect;
+type GameMemberWithUser = GameMemberRow & {
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        image: string | null;
+    };
+};
+interface GameMemberSearchResult {
+    id: string;
+    name: string;
+    email: string;
+    image: string | null;
+}
+type GameCustomHostnameRow = typeof gameCustomHostnames.$inferSelect;
+
+type UpsertGameMetadataInput = z.infer<typeof UpsertGameMetadataSchema>;
+type PatchGameMetadataInput = z.infer<typeof PatchGameMetadataSchema>;
+type AddGameMemberInput = z.infer<typeof AddGameMemberSchema>;
+type UpdateGameMemberRoleInput = z.infer<typeof UpdateGameMemberRoleSchema>;
+
+type UserRow = typeof users.$inferSelect;
+
+/**
+ * Cross-Domain Composite Types
+ */
+/**
+ * Game with optional manifest metadata from build tools
+ */
+type FetchedGame = (HostedGame | ExternalGame | GameRow) & {
+    manifest?: GameManifest;
+};
+/**
+ * Game custom hostname with validation records
+ */
+type GameCustomHostname = GameCustomHostnameRow & {
+    validationRecords?: DomainValidationRecords;
+};
+
+/**
+ * Base Playcademy SDK client with shared infrastructure.
+ * Provides authentication, HTTP requests, events,
+ * 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 authContext?: {
+        isInIframe: boolean;
+    };
+    protected initPayload?: InitPayload;
+    protected launchId?: string;
+    protected gameOrigin?: string;
+    private browserTimeZone?;
+    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;
+    /**
+     * Local day context supplied by the platform during iframe initialization.
+     */
+    get localDay(): LocalDayContext | undefined;
+    /**
+     * 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;
+    /**
+     * 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>;
+    private getBrowserTimeZone;
+    /**
+     * 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;
+    private _parseOrigin;
+    /**
+     * Detects and sets the authentication context (iframe vs standalone).
+     */
+    private _detectAuthContext;
+    /**
+     * Current user data.
+     * - `me()` - Get authenticated user profile
+     */
+    users: {
+        me: () => Promise<_playcademy_types.AuthenticatedUser>;
+    };
+}
+
+/**
+ * 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[];
+}): Promise<T>;
+
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @param baseUrl - The base URL of the Playcademy API
+ * @param email - User's email address
+ * @param password - User's password
+ * @returns Promise resolving to authentication response with token
+ * @throws PlaycademyError if authentication fails or network error occurs
+ *
+ * @example
+ * ```typescript
+ * // Preferred approach:
+ * const client = new PlaycademyClient({ baseUrl: '/api' })
+ * const result = await client.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * })
+ *
+ * // Legacy approach (still works):
+ * try {
+ *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
+ *   const client = new PlaycademyClient({ token: response.token })
+ * } catch (error) {
+ *   console.error('Login failed:', error.message)
+ * }
+ * ```
+ */
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ *
+ * SDK-specific types like TimebackInitContext that wrap the core types
+ * from @playcademy/types/user (which are re-exported via types/data.ts).
+ */
+
+/**
+ * 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[];
+}
+/**
+ * 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.
+ */
+interface TimebackUserXp {
+    /**
+     * Fetch XP data from the server.
+     * Returns XP for all courses in this game, or filter by grade/subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     *
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse', 'today'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to XP data
+     *
+     * @example
+     * ```typescript
+     * // Get total XP for all game courses
+     * const xp = await client.timeback.user.xp.fetch()
+     *
+     * // Get XP for a specific grade/subject
+     * const xp = await client.timeback.user.xp.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get XP with per-course breakdown
+     * const xp = await client.timeback.user.xp.fetch({
+     *   include: ['perCourse', 'today']
+     * })
+     *
+     * // Force fresh data
+     * const xp = await client.timeback.user.xp.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetXpOptions): Promise<XpResponse>;
+}
+/**
+ * TimeBack user object with cached getters, fetch, and targeted refresh methods.
+ */
+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?: 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.
+     */
+    xp: TimebackUserXp;
+    /**
+     * Mastery data for the current user.
+     * Call `mastery.fetch()` to get mastery progress from the server.
+     */
+    mastery: TimebackUserMastery;
+    /**
+     * Highest-grade-mastered data for the current user.
+     * Call `highestGradeMastered.fetch({ subject })` to get the student's
+     * highest mastered grade for a subject.
+     */
+    highestGradeMastered: TimebackUserHighestGradeMastered;
+}
+/**
+ * Mastery data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserMastery {
+    /**
+     * Fetch mastery data from the server.
+     * Returns mastery for all courses in this game, or filter by grade/subject.
+     * Returned masteredUnits values are true analytics values and may exceed
+     * the course masterableUnits maximum when historical data violates the
+     * expected invariant.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     *
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to mastery data
+     *
+     * @example
+     * ```typescript
+     * // Get total mastery for all game courses
+     * const mastery = await client.timeback.user.mastery.fetch()
+     *
+     * // Get mastery for a specific grade/subject
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get mastery with per-course breakdown
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   include: ['perCourse']
+     * })
+     *
+     * // Force fresh data
+     * const mastery = await client.timeback.user.mastery.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
+}
+/**
+ * Highest-grade-mastered data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserHighestGradeMastered {
+    /**
+     * Fetch the highest grade the current student has mastered for a subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     */
+    fetch(options: GetHighestGradeMasteredOptions): Promise<HighestGradeMasteredResponse>;
+}
+/**
+ * Options for querying student XP.
+ */
+interface GetXpOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse', 'today' */
+    include?: ('perCourse' | 'today')[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
+/**
+ * Options for querying student mastery.
+ */
+interface GetMasteryOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse' */
+    include?: 'perCourse'[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
+/**
+ * Options for querying highest grade mastered.
+ */
+interface GetHighestGradeMasteredOptions {
+    /** Subject to query */
+    subject: TimebackSubject;
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
+/**
+ * XP data for a single course.
+ */
+interface CourseXp {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from XP query.
+ */
+interface XpResponse {
+    totalXp: number;
+    todayXp?: number;
+    courses?: CourseXp[];
+}
+interface CourseMastery {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    /** True mastered units from analytics. May exceed masterableUnits for historical data. */
+    masteredUnits: number;
+    /** Configured mastery ceiling for the course. */
+    masterableUnits: number;
+    /** Clamped course completion percentage from 0..100. */
+    pctComplete: number;
+    isComplete: boolean;
+}
+/**
+ * Response from mastery query.
+ */
+interface MasteryResponse {
+    /** True mastered units across all queried courses. */
+    totalMasteredUnits: number;
+    /** Configured mastery ceiling across all queried courses. */
+    totalMasterableUnits: number;
+    courses?: CourseMastery[];
+}
+/**
+ * Response from highest-grade-mastered query.
+ */
+interface HighestGradeMasteredResponse {
+    subject: TimebackSubject;
+    highestGradeMastered: TimebackGrade | null;
+}
 
-type GameRow = typeof games.$inferSelect;
-type BaseGame = Omit<GameRow, 'gameType' | 'deploymentUrl' | 'externalUrl'>;
-type HostedGame = BaseGame & {
-    gameType: 'hosted';
-    deploymentUrl: string;
-    externalUrl: null;
-};
-type ExternalGame = BaseGame & {
-    gameType: 'external';
-    deploymentUrl: null;
-    externalUrl: string;
-};
-type Game = HostedGame | ExternalGame;
-type GameMemberRow = typeof gameMembers.$inferSelect;
-type GameMemberWithUser = GameMemberRow & {
-    user: {
-        id: string;
-        name: string;
-        email: string;
-        image: string | null;
-    };
-};
-interface GameMemberSearchResult {
+/**
+ * Core client configuration and lifecycle types
+ */
+
+type TokenType = 'session' | 'apiKey' | 'gameJwt';
+/**
+ * Runtime mode for a Playcademy game client.
+ *
+ * - `'platform'` — game is embedded in the platform (e.g. the cademy hub)
+ *   with a real authenticated user and full access to SDK namespaces.
+ * - `'demo'` — game is embedded in the landing page demo shell with an
+ *   anonymous user; platform-only namespaces throw, and `client.demo.*`
+ *   is the supported surface for signaling demo lifecycle events and
+ *   reading/updating the anonymous profile.
+ * - `'standalone'` — game is running outside any iframe (e.g. `bun run dev`
+ *   or direct-deploy preview) with a mock token and no real platform
+ *   context. API calls will not succeed; use this to branch UX locally.
+ */
+type PlaycademyMode = 'platform' | 'demo' | 'standalone';
+interface ClientConfig {
+    baseUrl: string;
+    gameUrl?: string;
+    token?: string;
+    tokenType?: TokenType;
+    gameId?: string;
+    launchId?: string;
+    mode?: PlaycademyMode;
+}
+interface InitPayload {
+    /** Hub API base URL */
+    baseUrl: string;
+    /** Game deployment URL (serves both frontend assets and backend API) */
+    gameUrl?: string;
+    /** Short-lived game token */
+    token: string;
+    /** Game ID */
+    gameId: string;
+    /** Timeback context (if user has a Timeback account) */
+    timeback?: TimebackInitContext;
+    /** Playcademy context for resolving the student's local learning day */
+    localDay?: LocalDayContext;
+    /** Runtime mode for the game client */
+    mode?: PlaycademyMode;
+    /** Launch session correlation ID (UUID, set by platform on game launch) */
+    launchId?: string;
+    /** When `true`, the parent shell provides a heartbeat relay via postMessage, so the SDK can skip its own `fetch({ keepalive })` beacon on pagehide. Defaults to `false`. */
+    hasHeartbeatRelay?: boolean;
+}
+/**
+ * Simplified user data passed to games via InitPayload
+ * This is a subset of AuthenticatedUser suitable for external game consumption
+ *
+ * Note: Named GameInitUser to distinguish from the cross-game GameUser DTO
+ * exported from @playcademy/types
+ */
+interface GameInitUser {
+    /** Playcademy user ID */
     id: string;
-    name: string;
-    email: string;
+    /** Unique username */
+    username: string | null;
+    /** Display name */
+    name: string | null;
+    /** Email address */
+    email: string | null;
+    /** Profile image URL */
     image: string | null;
+    /** Whether the user has a Timeback account */
+    hasTimebackAccount: boolean;
+}
+interface GameContextPayload {
+    token: string;
+    baseUrl: string;
+    gameId: string;
+    forwardKeys?: string[];
+    mode?: PlaycademyMode;
+}
+type EventListeners = {
+    [E in keyof ClientEvents]?: ((payload: ClientEvents[E]) => void)[];
+};
+interface ClientEvents {
+    authChange: {
+        token: string | null;
+    };
 }
-type GameCustomHostnameRow = typeof gameCustomHostnames.$inferSelect;
-
-type UpsertGameMetadataInput = z.infer<typeof UpsertGameMetadataSchema>;
-type PatchGameMetadataInput = z.infer<typeof PatchGameMetadataSchema>;
-type AddGameMemberInput = z.infer<typeof AddGameMemberSchema>;
-type UpdateGameMemberRoleInput = z.infer<typeof UpdateGameMemberRoleSchema>;
 
-type UserRow = typeof users.$inferSelect;
+/**
+ * Event and message payload types for SDK messaging system
+ */
 
 /**
- * Cross-Domain Composite Types
+ * 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;
+}
 /**
- * Game with optional manifest metadata from build tools
+ * OAuth callback event payload.
+ * Used when OAuth flow completes in popup/new-tab windows.
  */
-type FetchedGame = (HostedGame | ExternalGame | GameRow) & {
-    manifest?: GameManifest;
-};
+interface AuthCallbackPayload {
+    /** OAuth authorization code */
+    code: string;
+    /** OAuth state parameter for CSRF protection */
+    state: string;
+    /** Error message if OAuth flow failed */
+    error: string | null;
+}
 /**
- * Game custom hostname with validation records
+ * Message sent from server callback to opener window.
+ * This is the standardized format from our server-first architecture.
  */
-type GameCustomHostname = GameCustomHostnameRow & {
-    validationRecords?: DomainValidationRecords;
+interface AuthServerMessage {
+    /** Type of the message */
+    type: 'PLAYCADEMY_AUTH_STATE_CHANGE';
+    /** Whether the user is currently authenticated */
+    authenticated: boolean;
+    /** Whether the authentication was successful */
+    success: boolean;
+    /** Timestamp of the message */
+    ts: number;
+    /** User information if authentication was successful */
+    user?: UserInfo;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Token refresh event payload.
+ * Sent when authentication token is updated.
+ */
+interface TokenRefreshPayload {
+    /** New authentication token */
+    token: string;
+    /** Token expiration timestamp */
+    exp: number;
+}
+/**
+ * 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';
+}
+/**
+ * Init error payload.
+ * Sent from game iframe to parent when SDK initialization fails
+ * (e.g. origin validation failure, INIT timeout, client creation error).
+ */
+interface InitErrorPayload {
+    reason: string;
+}
+/**
+ * Options for `client.demo.end(score, options?)`.
+ *
+ * All optional. The landing-page demo shell can render a meaningful CTA
+ * from `score` alone, but `durationMs` enables a nicer summary and
+ * `metadata` lets games pass any extra context they want to surface.
+ */
+interface DemoEndOptions {
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Wire payload for the `PLAYCADEMY_DEMO_END` message.
+ *
+ * `score` is required — the demo shell always needs something to display
+ * when the round ends. `durationMs` and `metadata` are optional.
+ */
+interface DemoEndPayload extends DemoEndOptions {
+    score: number;
+}
+type TimebackHeartbeatRelayRequest = Omit<HeartbeatRequest, 'gameId' | 'studentId' | 'windowStartedAtMs' | 'windowSequence'> & {
+    windowStartedAtMs: number;
 };
 
+/**
+ * SDK-specific API response types
+ */
+interface LoginResponse {
+    token: string;
+}
+interface GameTokenResponse {
+    token: string;
+    exp: number;
+    baseUrl?: string;
+}
+
 /**
  * Scores namespace types
  */