@playcademy/sdk 0.4.1-beta.4 → 0.4.1-beta.5

package/dist/types.d.ts

@@ -22,241 +22,6 @@ declare function parseOAuthState(state: string): {
 /** Permitted HTTP verbs */
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 
-/**
- * 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 DeveloperStatusValue = DeveloperStatusEnumType;
-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 DeveloperStatusResponse {
-    status: DeveloperStatusEnumType;
-}
-/**
- * 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;
-}
-interface GameUser {
-    id: string;
-    name: string | null;
-    role: UserRoleEnumType;
-    username: string | null;
-    email: string | null;
-    timeback?: UserTimebackData;
-}
-
-/**
- * Game Types
- *
- * Literal types and API DTOs. Database row types are in @playcademy/data/types.
- *
- * @module types/game
- */
-type GameType = 'hosted' | 'external';
-type GamePlatform = 'web' | 'godot' | 'unity' | (string & {});
-/**
- * Game manifest file format (manifest.json).
- * Note: createdAt is a string here because it's parsed from JSON file.
- */
-interface ManifestV1 {
-    version: string;
-    platform: string;
-    createdAt: string;
-}
-interface DomainValidationRecords {
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    ssl?: {
-        txt_name?: string;
-        txt_value?: string;
-    }[];
-}
-
-/**
- * Leaderboard Types
- *
- * @module types/leaderboard
- */
-type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
-interface LeaderboardOptions {
-    timeframe?: LeaderboardTimeframe;
-    limit?: number;
-    offset?: number;
-    gameId?: string;
-}
-interface LeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId?: string;
-    gameTitle?: string;
-    gameSlug?: string;
-}
-interface UserRank {
-    rank: number;
-    totalPlayers: number;
-    score: number;
-    percentile: number;
-}
-interface UserRankResponse {
-    rank: number;
-    score: number;
-    userId: string;
-}
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: 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;
-}
-
-/**
- * Achievement Types
- *
- * @module types/achievement
- */
-type AchievementScopeType = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'game' | 'global' | 'map' | 'level' | 'event';
-declare enum AchievementCompletionType {
-    TIME_PLAYED_SESSION = "time_played_session",
-    INTERACTION = "interaction",
-    LEADERBOARD_RANK = "leaderboard_rank",
-    FIRST_SCORE = "first_score",
-    PERSONAL_BEST = "personal_best"
-}
-interface AchievementCurrent {
-    id: string;
-    title: string;
-    description?: string | null;
-    scope: AchievementScopeType;
-    rewardCredits: number;
-    limit: number;
-    completionType: string;
-    completionConfig: unknown;
-    target: unknown;
-    active: boolean;
-    createdAt?: Date | null;
-    updatedAt?: Date | null;
-    status: 'available' | 'completed';
-    scopeKey: string;
-    windowStart: string;
-    windowEnd: string;
-}
-interface AchievementWithStatus {
-    id: string;
-    title: string;
-    description: string | null;
-    scope: AchievementScopeType;
-    rewardCredits: number;
-    limit: number;
-    completionType: string;
-    completionConfig: unknown;
-    target: unknown;
-    active: boolean;
-    createdAt: Date | null;
-    updatedAt: Date | null;
-    status: 'available' | 'completed';
-    scopeKey: string;
-    windowStart?: string;
-    windowEnd?: string;
-}
-interface AchievementHistoryEntry {
-    achievementId: string;
-    title: string;
-    rewardCredits: number;
-    createdAt: Date;
-    scopeKey: string;
-}
-interface AchievementProgressResponse {
-    achievementId: string;
-    status: 'completed' | 'already_completed';
-    rewardCredits: number;
-    scopeKey: string;
-    createdAt: Date;
-}
-
 /**
  * TimeBack Enums & Literal Types
  *
@@ -575,120 +340,67 @@ interface EndActivityResponse {
 }
 
 /**
- * Inventory & Shop Types
- *
- * Literal types for inventory system. Database row types are in @playcademy/data/types.
- *
- * @module types/inventory
- */
-/**
- * Item categories available on the platform.
- */
-type ItemType = 'currency' | 'badge' | 'trophy' | 'collectible' | 'consumable' | 'unlock' | 'upgrade' | 'accessory' | 'other';
-
-/**
- * Map & Placement Types
- *
- * Literal types and JSON shapes for maps. Database row types are in @playcademy/data/types.
+ * Achievement Types
  *
- * @module types/map
- */
-/**
- * Allowed map interaction types.
+ * @module types/achievement
  */
-type InteractionType = 'game_entry' | 'game_registry' | 'info' | 'teleport' | 'door_in' | 'door_out' | 'npc_interaction' | 'quest_trigger';
-/**
- * Metadata for interactive map elements.
- */
-interface MapElementMetadata {
-    description?: string;
-    title?: string;
-    targetMapIdentifier?: string;
-    targetSpawnTileX?: number;
-    targetSpawnTileY?: number;
-    sourceTiledObjects?: Record<string, unknown>[];
-    [key: string]: unknown;
-}
-/**
- * Metadata describing how an item should be placed on the map.
- */
-interface PlaceableItemMetadata {
-    tilesWide?: number;
-    tilesHigh?: number;
-    flippable?: boolean;
-    [key: string]: unknown;
+type AchievementScopeType = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'game' | 'global' | 'map' | 'level' | 'event';
+declare enum AchievementCompletionType {
+    TIME_PLAYED_SESSION = "time_played_session",
+    INTERACTION = "interaction",
+    LEADERBOARD_RANK = "leaderboard_rank",
+    FIRST_SCORE = "first_score",
+    PERSONAL_BEST = "personal_best"
 }
-/**
- * Simplified map data for API responses.
- */
-interface MapData {
+interface AchievementCurrent {
     id: string;
-    identifier: string;
-    displayName: string;
+    title: string;
     description?: string | null;
-    metadata?: Record<string, unknown> | null;
-}
-/**
- * Input for creating a map object.
- */
-interface CreateMapObjectData {
-    itemId: string;
-    worldX: number;
-    worldY: number;
-    width?: number;
-    height?: number;
-    rotation?: number;
-    scale?: number;
-    metadata?: Record<string, unknown>;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: string;
+    completionConfig: unknown;
+    target: unknown;
+    active: boolean;
+    createdAt?: Date | null;
+    updatedAt?: Date | null;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart: string;
+    windowEnd: string;
 }
-
-/**
- * Character & Avatar Types
- *
- * Literal types for character system. Database row types are in @playcademy/data/types.
- *
- * @module types/character
- */
-/**
- * Character component categories.
- */
-type CharacterComponentType = 'body' | 'outfit' | 'hairstyle' | 'eyes' | 'accessory';
-
-/**
- * Level & Progression Types
- *
- * API response DTOs for level system. Database row types are in @playcademy/data/types.
- *
- * @module types/level
- */
-/**
- * Result of adding XP to a user.
- */
-interface XPAddResult {
-    totalXP: number;
-    newLevel: number;
-    leveledUp: boolean;
-    creditsAwarded: number;
-    xpToNextLevel: number;
+interface AchievementWithStatus {
+    id: string;
+    title: string;
+    description: string | null;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: string;
+    completionConfig: unknown;
+    target: unknown;
+    active: boolean;
+    createdAt: Date | null;
+    updatedAt: Date | null;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart?: string;
+    windowEnd?: string;
 }
-/**
- * Result of checking whether a level up occurred.
- */
-interface LevelUpCheckResult {
-    newLevel: number;
-    remainingXp: number;
-    leveledUp: boolean;
-    creditsAwarded: number;
-    xpToNextLevel: number;
+interface AchievementHistoryEntry {
+    achievementId: string;
+    title: string;
+    rewardCredits: number;
+    createdAt: Date;
+    scopeKey: string;
 }
-/**
- * Level progress API response.
- */
-interface LevelProgressResponse {
-    level: number;
-    currentXp: number;
-    xpToNextLevel: number;
-    totalXP: number;
+interface AchievementProgressResponse {
+    achievementId: string;
+    status: 'completed' | 'already_completed';
+    rewardCredits: number;
+    scopeKey: string;
+    createdAt: Date;
 }
 
 /**
@@ -721,435 +433,389 @@ interface NotificationStats {
 }
 
 /**
- * Shop Types
+ * User Types
  *
- * @module types/shop
- */
-/**
- * Currency display info for shop UI.
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
  */
-interface ShopCurrency {
+type UserRoleEnumType = 'admin' | 'player' | 'developer' | 'teacher';
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type DeveloperStatusValue = DeveloperStatusEnumType;
+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;
-    symbol: string | null;
+    name: string | null;
+    type: TimebackOrgType | string;
     isPrimary: boolean;
-    displayName?: string | null;
-    imageUrl?: string | null;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    enrollments: UserEnrollment[];
 }
 /**
- * Shop item for display.
- * Combines Item fields (excluding createdAt) with shop listing data.
+ * OpenID Connect UserInfo claims (NOT a database row).
  */
-interface ShopDisplayItem {
-    id: string;
-    slug: string;
-    gameId?: string | null;
-    displayName: string;
-    description?: string | null;
-    type: string;
-    isPlaceable: boolean;
-    imageUrl?: string | null;
-    metadata?: unknown;
-    listingId: string;
-    shopPrice: number;
-    currencyId: string;
-    currencySymbol?: string | null;
-    currencyDisplayName?: string | null;
-    currencyImageUrl?: string | null;
-    stock?: number | null;
-    sellBackPercentage?: number | null;
+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 DeveloperStatusResponse {
+    status: DeveloperStatusEnumType;
 }
 /**
- * Complete shop view response.
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
  */
-interface ShopViewResponse {
-    shopItems: ShopDisplayItem[];
-    currencies: ShopCurrency[];
+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;
+}
+interface GameUser {
+    id: string;
+    name: string | null;
+    role: UserRoleEnumType;
+    username: string | null;
+    email: string | null;
+    timeback?: UserTimebackData;
 }
 
 /**
- * Sprite Types
+ * Game Types
  *
- * JSON shapes for sprite configuration. Database row types are in @playcademy/data/types.
+ * Literal types and API DTOs. Database row types are in @playcademy/data/types.
  *
- * @module types/sprite
+ * @module types/game
  */
+type GameType = 'hosted' | 'external';
+type GamePlatform = 'web' | 'godot' | 'unity' | (string & {});
 /**
- * Animation frame configuration.
+ * Game manifest file format (manifest.json).
+ * Note: createdAt is a string here because it's parsed from JSON file.
  */
-interface SpriteAnimationFrame {
-    row: number;
-    frameStart: number;
-    numFrames: number;
-    fps: number;
-}
-/**
- * Sprite template data structure (stored in JSONB).
- */
-interface SpriteTemplateData {
-    tileSize: number;
-    tileHeight: number;
-    columns: number;
-    rows: number;
-    spacing: number;
-    animations: {
-        base_right: SpriteAnimationFrame;
-        base_up: SpriteAnimationFrame;
-        base_left: SpriteAnimationFrame;
-        base_down: SpriteAnimationFrame;
-        idle_right: SpriteAnimationFrame;
-        walk_right: SpriteAnimationFrame;
-        idle_up: SpriteAnimationFrame;
-        walk_up: SpriteAnimationFrame;
-        idle_left: SpriteAnimationFrame;
-        walk_left: SpriteAnimationFrame;
-        idle_down: SpriteAnimationFrame;
-        walk_down: SpriteAnimationFrame;
+interface ManifestV1 {
+    version: string;
+    platform: string;
+    createdAt: string;
+}
+interface DomainValidationRecords {
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
     };
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
 }
+
 /**
- * Sprite sheet configuration with precomputed dimensions.
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
  */
-interface SpriteConfigWithDimensions {
-    textureUrl: string;
-    columns: number;
-    rows: number;
-    spriteWidth: number;
-    spriteHeight: number;
-    animations: Record<string, SpriteAnimationFrame>;
+type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
+interface LeaderboardOptions {
+    timeframe?: LeaderboardTimeframe;
+    limit?: number;
+    offset?: number;
+    gameId?: string;
+}
+interface LeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId?: string;
+    gameTitle?: string;
+    gameSlug?: string;
+}
+interface UserRank {
+    rank: number;
+    totalPlayers: number;
+    score: number;
+    percentile: number;
+}
+interface UserRankResponse {
+    rank: number;
+    score: number;
+    userId: string;
+}
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: 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;
 }
 
 /**
- * Connection monitoring types
+ * Inventory & Shop Types
  *
- * Type definitions for connection state, configuration, and callbacks.
+ * Literal types for inventory system. Database row types are in @playcademy/data/types.
+ *
+ * @module types/inventory
  */
 /**
- * Possible connection states.
- *
- * - **online**: Connection is stable and healthy
- * - **offline**: Complete loss of network connectivity
- * - **degraded**: Connection is slow or experiencing intermittent issues
+ * Item categories available on the platform.
  */
-type ConnectionState = 'online' | 'offline' | 'degraded';
+type ItemType = 'currency' | 'badge' | 'trophy' | 'collectible' | 'consumable' | 'unlock' | 'upgrade' | 'accessory' | 'other';
 
 /**
- * Connection Manager
+ * Map & Placement Types
  *
- * Manages connection monitoring and integrates it with the Playcademy client.
- * Handles event wiring, state management, and disconnect callbacks.
+ * Literal types and JSON shapes for maps. Database row types are in @playcademy/data/types.
  *
- * In iframe mode, disables local monitoring and listens to platform connection
- * state broadcasts instead (avoids duplicate heartbeats).
+ * @module types/map
  */
-
 /**
- * Configuration for the ConnectionManager.
+ * Allowed map interaction types.
  */
-interface ConnectionManagerConfig {
-    /** Base URL for API requests (used for heartbeat pings) */
-    baseUrl: string;
-    /** Authentication context (iframe vs standalone) for alert routing */
-    authContext?: {
-        isInIframe: boolean;
-    };
-    /** Handler to call when connection issues are detected */
-    onDisconnect?: DisconnectHandler;
-    /** Callback to emit connection change events to the client */
-    onConnectionChange?: (state: ConnectionState, reason: string) => void;
+type InteractionType = 'game_entry' | 'game_registry' | 'info' | 'teleport' | 'door_in' | 'door_out' | 'npc_interaction' | 'quest_trigger';
+/**
+ * Metadata for interactive map elements.
+ */
+interface MapElementMetadata {
+    description?: string;
+    title?: string;
+    targetMapIdentifier?: string;
+    targetSpawnTileX?: number;
+    targetSpawnTileY?: number;
+    sourceTiledObjects?: Record<string, unknown>[];
+    [key: string]: unknown;
 }
 /**
- * Manages connection monitoring for the Playcademy client.
- *
- * The ConnectionManager serves as an integration layer between the low-level
- * ConnectionMonitor and the PlaycademyClient. It handles:
- * - Event wiring and coordination
- * - Disconnect callbacks with context
- * - Platform-level alert integration
- * - Request success/failure tracking
- *
- * This class is used internally by PlaycademyClient and typically not
- * instantiated directly by game developers.
- *
- * @see {@link ConnectionMonitor} for the underlying monitoring implementation
- * @see {@link PlaycademyClient.onDisconnect} for the public API
+ * Metadata describing how an item should be placed on the map.
  */
-declare class ConnectionManager {
-    private monitor?;
-    private authContext?;
-    private disconnectHandler?;
-    private connectionChangeCallback?;
-    private currentState;
-    private additionalDisconnectHandlers;
-    /**
-     * Creates a new ConnectionManager instance.
-     *
-     * @param config - Configuration options for the manager
-     *
-     * @example
-     * ```typescript
-     * const manager = new ConnectionManager({
-     *   baseUrl: 'https://api.playcademy.com',
-     *   authContext: { isInIframe: false },
-     *   onDisconnect: (context) => {
-     *     console.log(`Disconnected: ${context.state}`)
-     *   },
-     *   onConnectionChange: (state, reason) => {
-     *     console.log(`Connection changed: ${state}`)
-     *   }
-     * })
-     * ```
-     */
-    constructor(config: ConnectionManagerConfig);
-    /**
-     * Gets the current connection state.
-     *
-     * @returns The current connection state ('online', 'offline', or 'degraded')
-     *
-     * @example
-     * ```typescript
-     * const state = manager.getState()
-     * if (state === 'offline') {
-     *   console.log('No connection')
-     * }
-     * ```
-     */
-    getState(): ConnectionState;
-    /**
-     * Manually triggers a connection check immediately.
-     *
-     * Forces a heartbeat ping to verify the current connection status.
-     * Useful when you need to check connectivity before a critical operation.
-     *
-     * In iframe mode, this returns the last known state from platform.
-     *
-     * @returns Promise resolving to the current connection state
-     *
-     * @example
-     * ```typescript
-     * const state = await manager.checkNow()
-     * if (state === 'online') {
-     *   await performCriticalOperation()
-     * }
-     * ```
-     */
-    checkNow(): Promise<ConnectionState>;
-    /**
-     * Reports a successful API request to the connection monitor.
-     *
-     * This resets the consecutive failure counter and transitions from
-     * 'degraded' to 'online' state if applicable.
-     *
-     * Typically called automatically by the SDK's request wrapper.
-     * No-op in iframe mode (platform handles monitoring).
-     */
-    reportRequestSuccess(): void;
-    /**
-     * Reports a failed API request to the connection monitor.
-     *
-     * Only network errors are tracked (not 4xx/5xx HTTP responses).
-     * After consecutive failures exceed the threshold, the state transitions
-     * to 'degraded' or 'offline'.
-     *
-     * Typically called automatically by the SDK's request wrapper.
-     * No-op in iframe mode (platform handles monitoring).
-     *
-     * @param error - The error from the failed request
-     */
-    reportRequestFailure(error: unknown): void;
-    /**
-     * Registers a callback to be called when connection issues are detected.
-     *
-     * The callback only fires for 'offline' and 'degraded' states, not when
-     * recovering to 'online'. This provides a clean API for games to handle
-     * disconnect scenarios without being notified of every state change.
-     *
-     * Works in both iframe and standalone modes transparently.
-     *
-     * @param callback - Function to call when connection degrades
-     * @returns Cleanup function to unregister the callback
-     *
-     * @example
-     * ```typescript
-     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
-     *   if (state === 'offline') {
-     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
-     *     saveGameState()
-     *   }
-     * })
-     *
-     * // Later: cleanup() to unregister
-     * ```
-     */
-    onDisconnect(callback: DisconnectHandler): () => void;
-    /**
-     * Stops connection monitoring and performs cleanup.
-     *
-     * Removes event listeners and clears heartbeat intervals.
-     * Should be called when the client is being destroyed.
-     */
-    stop(): void;
-    /**
-     * Sets up listener for platform connection state broadcasts (iframe mode only).
-     */
-    private _setupPlatformListener;
-    /**
-     * Handles connection state changes from the monitor or platform.
-     *
-     * Coordinates between:
-     * 1. Emitting events to the client (for client.on('connectionChange'))
-     * 2. Calling the disconnect handler if configured
-     * 3. Calling any additional handlers registered via onDisconnect()
-     *
-     * @param state - The new connection state
-     * @param reason - Human-readable reason for the state change
-     */
-    private _handleConnectionChange;
+interface PlaceableItemMetadata {
+    tilesWide?: number;
+    tilesHigh?: number;
+    flippable?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Simplified map data for API responses.
+ */
+interface MapData {
+    id: string;
+    identifier: string;
+    displayName: string;
+    description?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Input for creating a map object.
+ */
+interface CreateMapObjectData {
+    itemId: string;
+    worldX: number;
+    worldY: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    scale?: number;
+    metadata?: Record<string, unknown>;
 }
 
 /**
- * @fileoverview Playcademy Messaging System
- *
- * This file implements a unified messaging system for the Playcademy platform that handles
- * communication between different contexts:
- *
- * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
- *    they need to communicate with the parent window using postMessage API
- *
- * 2. **Local Communication**: When games run in the same context (local development),
- *    they use CustomEvents for internal messaging
+ * Character & Avatar Types
  *
- * The system automatically detects the runtime environment and chooses the appropriate
- * transport method, abstracting this complexity from the developer.
+ * Literal types for character system. Database row types are in @playcademy/data/types.
  *
- * **Architecture Overview**:
- * - Games run in iframes for security and isolation
- * - Parent window (Playcademy shell) manages game lifecycle
- * - Messages flow bidirectionally between parent and iframe
- * - Local development mode simulates this architecture without iframes
+ * @module types/character
+ */
+/**
+ * Character component categories.
  */
+type CharacterComponentType = 'body' | 'outfit' | 'hairstyle' | 'eyes' | 'accessory';
 
 /**
- * Enumeration of all message types used in the Playcademy messaging system.
- *
- * **Message Flow Patterns**:
+ * Level & Progression Types
  *
- * **Parent → Game (Overworld → Game)**:
- * - INIT: Provides game with authentication token and configuration
- * - TOKEN_REFRESH: Updates game's authentication token before expiry
- * - PAUSE/RESUME: Controls game execution state
- * - FORCE_EXIT: Immediately terminates the game
- * - OVERLAY: Shows/hides UI overlays over the game
+ * API response DTOs for level system. Database row types are in @playcademy/data/types.
  *
- * **Game → Parent (Game → Overworld)**:
- * - READY: Game has loaded and is ready to receive messages
- * - EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
- * - TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)
+ * @module types/level
  */
-declare enum MessageEvents {
-    /**
-     * Initializes the game with authentication context and configuration.
-     * Sent immediately after game iframe loads.
-     * Payload:
-     * - `baseUrl`: string
-     * - `token`: string
-     * - `gameId`: string
-     */
-    INIT = "PLAYCADEMY_INIT",
-    /**
-     * Updates the game's authentication token before it expires.
-     * Sent periodically to maintain valid authentication.
-     * Payload:
-     * - `token`: string
-     * - `exp`: number
-     */
-    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
-    /**
-     * Pauses game execution (e.g., when user switches tabs).
-     * Game should pause timers, animations, and user input.
-     * Payload: void
-     */
-    PAUSE = "PLAYCADEMY_PAUSE",
-    /**
-     * Resumes game execution after being paused.
-     * Game should restore timers, animations, and user input.
-     * Payload: void
-     */
-    RESUME = "PLAYCADEMY_RESUME",
-    /**
-     * Forces immediate game termination (emergency exit).
-     * Game should clean up resources and exit immediately.
-     * Payload: void
-     */
-    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
-    /**
-     * Shows or hides UI overlays over the game.
-     * Game may need to pause or adjust rendering accordingly.
-     * Payload: boolean (true = show overlay, false = hide overlay)
-     */
-    OVERLAY = "PLAYCADEMY_OVERLAY",
-    /**
-     * Broadcasts connection state changes to games.
-     * Sent by platform when network connectivity changes.
-     * Payload:
-     * - `state`: 'online' | 'offline' | 'degraded'
-     * - `reason`: string
-     */
-    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
-    /**
-     * Game has finished loading and is ready to receive messages.
-     * Sent once after game initialization is complete.
-     * Payload: void
-     */
-    READY = "PLAYCADEMY_READY",
-    /**
-     * Game requests to be closed/exited.
-     * Sent when user clicks exit button or game naturally ends.
-     * Payload: void
-     */
-    EXIT = "PLAYCADEMY_EXIT",
-    /**
-     * Game reports performance telemetry data.
-     * Sent periodically for monitoring and analytics.
-     * Payload:
-     * - `fps`: number
-     * - `mem`: number
-     */
-    TELEMETRY = "PLAYCADEMY_TELEMETRY",
-    /**
-     * Game reports key events to parent.
-     * Sent when certain keys are pressed within the game iframe.
-     * Payload:
-     * - `key`: string
-     * - `code?`: string
-     * - `type`: 'keydown' | 'keyup'
-     */
-    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
-    /**
-     * Game requests platform to display an alert.
-     * Sent when connection issues are detected or other important events occur.
-     * Payload:
-     * - `message`: string
-     * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
-     */
-    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
-    /**
-     * Notifies about authentication state changes.
-     * Can be sent in both directions depending on auth flow.
-     * Payload:
-     * - `authenticated`: boolean
-     * - `user`: UserInfo | null
-     * - `error`: Error | null
-     */
-    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
-    /**
-     * OAuth callback data from popup/new-tab windows.
-     * Sent from popup window back to parent after OAuth completes.
-     * Payload:
-     * - `code`: string (OAuth authorization code)
-     * - `state`: string (OAuth state for CSRF protection)
-     * - `error`: string | null (OAuth error if any)
-     */
-    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
+/**
+ * Result of adding XP to a user.
+ */
+interface XPAddResult {
+    totalXP: number;
+    newLevel: number;
+    leveledUp: boolean;
+    creditsAwarded: number;
+    xpToNextLevel: number;
+}
+/**
+ * Result of checking whether a level up occurred.
+ */
+interface LevelUpCheckResult {
+    newLevel: number;
+    remainingXp: number;
+    leveledUp: boolean;
+    creditsAwarded: number;
+    xpToNextLevel: number;
+}
+/**
+ * Level progress API response.
+ */
+interface LevelProgressResponse {
+    level: number;
+    currentXp: number;
+    xpToNextLevel: number;
+    totalXP: number;
+}
+
+/**
+ * Shop Types
+ *
+ * @module types/shop
+ */
+/**
+ * Currency display info for shop UI.
+ */
+interface ShopCurrency {
+    id: string;
+    symbol: string | null;
+    isPrimary: boolean;
+    displayName?: string | null;
+    imageUrl?: string | null;
+}
+/**
+ * Shop item for display.
+ * Combines Item fields (excluding createdAt) with shop listing data.
+ */
+interface ShopDisplayItem {
+    id: string;
+    slug: string;
+    gameId?: string | null;
+    displayName: string;
+    description?: string | null;
+    type: string;
+    isPlaceable: boolean;
+    imageUrl?: string | null;
+    metadata?: unknown;
+    listingId: string;
+    shopPrice: number;
+    currencyId: string;
+    currencySymbol?: string | null;
+    currencyDisplayName?: string | null;
+    currencyImageUrl?: string | null;
+    stock?: number | null;
+    sellBackPercentage?: number | null;
+}
+/**
+ * Complete shop view response.
+ */
+interface ShopViewResponse {
+    shopItems: ShopDisplayItem[];
+    currencies: ShopCurrency[];
+}
+
+/**
+ * Sprite Types
+ *
+ * JSON shapes for sprite configuration. Database row types are in @playcademy/data/types.
+ *
+ * @module types/sprite
+ */
+/**
+ * Animation frame configuration.
+ */
+interface SpriteAnimationFrame {
+    row: number;
+    frameStart: number;
+    numFrames: number;
+    fps: number;
+}
+/**
+ * Sprite template data structure (stored in JSONB).
+ */
+interface SpriteTemplateData {
+    tileSize: number;
+    tileHeight: number;
+    columns: number;
+    rows: number;
+    spacing: number;
+    animations: {
+        base_right: SpriteAnimationFrame;
+        base_up: SpriteAnimationFrame;
+        base_left: SpriteAnimationFrame;
+        base_down: SpriteAnimationFrame;
+        idle_right: SpriteAnimationFrame;
+        walk_right: SpriteAnimationFrame;
+        idle_up: SpriteAnimationFrame;
+        walk_up: SpriteAnimationFrame;
+        idle_left: SpriteAnimationFrame;
+        walk_left: SpriteAnimationFrame;
+        idle_down: SpriteAnimationFrame;
+        walk_down: SpriteAnimationFrame;
+    };
+}
+/**
+ * Sprite sheet configuration with precomputed dimensions.
+ */
+interface SpriteConfigWithDimensions {
+    textureUrl: string;
+    columns: number;
+    rows: number;
+    spriteWidth: number;
+    spriteHeight: number;
+    animations: Record<string, SpriteAnimationFrame>;
 }
 
 declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
@@ -4668,44 +4334,232 @@ interface PlayerSessionPayload {
     characterCreated?: UserRow['characterCreated'];
     playerCharacter?: PlayerCharacterRow | null;
 }
-/**
- * Map-related Composite Types
- * DB row + joined game/item data
- */
-type MapElementWithGame = MapElementRow & {
-    game: {
-        id: string;
-        displayName: string;
-    } | null;
-};
-type MapObjectWithItem = MapObjectRow & {
-    item: {
-        id: string;
-        slug: string;
-        displayName: string;
-        description?: string | null;
-        imageUrl?: string | null;
-        isPlaceable: boolean;
-        metadata?: PlaceableItemMetadata | null;
-    };
-};
-/**
- * Game custom hostname with validation records
- */
-type GameCustomHostname = GameCustomHostnameRow & {
-    validationRecords?: DomainValidationRecords;
-};
-
-type UserLevelRow = typeof userLevels.$inferSelect;
-type LevelConfigRow = typeof levelConfigs.$inferSelect;
-type UserLevelWithConfig = UserLevelRow & {
-    xpToNextLevel: number;
-    nextLevelConfig?: LevelConfigRow;
-};
-
-type SpriteTemplateRow = typeof spriteTemplates.$inferSelect;
-
-type NotificationRow = InferSelectModel<typeof notifications>;
+/**
+ * Map-related Composite Types
+ * DB row + joined game/item data
+ */
+type MapElementWithGame = MapElementRow & {
+    game: {
+        id: string;
+        displayName: string;
+    } | null;
+};
+type MapObjectWithItem = MapObjectRow & {
+    item: {
+        id: string;
+        slug: string;
+        displayName: string;
+        description?: string | null;
+        imageUrl?: string | null;
+        isPlaceable: boolean;
+        metadata?: PlaceableItemMetadata | null;
+    };
+};
+/**
+ * Game custom hostname with validation records
+ */
+type GameCustomHostname = GameCustomHostnameRow & {
+    validationRecords?: DomainValidationRecords;
+};
+
+type UserLevelRow = typeof userLevels.$inferSelect;
+type LevelConfigRow = typeof levelConfigs.$inferSelect;
+type UserLevelWithConfig = UserLevelRow & {
+    xpToNextLevel: number;
+    nextLevelConfig?: LevelConfigRow;
+};
+
+type SpriteTemplateRow = typeof spriteTemplates.$inferSelect;
+
+type NotificationRow = InferSelectModel<typeof notifications>;
+
+/**
+ * Connection monitoring types
+ *
+ * Type definitions for connection state, configuration, and callbacks.
+ */
+/**
+ * Possible connection states.
+ *
+ * - **online**: Connection is stable and healthy
+ * - **offline**: Complete loss of network connectivity
+ * - **degraded**: Connection is slow or experiencing intermittent issues
+ */
+type ConnectionState = 'online' | 'offline' | 'degraded';
+
+/**
+ * Connection Manager
+ *
+ * Manages connection monitoring and integrates it with the Playcademy client.
+ * Handles event wiring, state management, and disconnect callbacks.
+ *
+ * In iframe mode, disables local monitoring and listens to platform connection
+ * state broadcasts instead (avoids duplicate heartbeats).
+ */
+
+/**
+ * Configuration for the ConnectionManager.
+ */
+interface ConnectionManagerConfig {
+    /** Base URL for API requests (used for heartbeat pings) */
+    baseUrl: string;
+    /** Authentication context (iframe vs standalone) for alert routing */
+    authContext?: {
+        isInIframe: boolean;
+    };
+    /** Handler to call when connection issues are detected */
+    onDisconnect?: DisconnectHandler;
+    /** Callback to emit connection change events to the client */
+    onConnectionChange?: (state: ConnectionState, reason: string) => void;
+}
+/**
+ * Manages connection monitoring for the Playcademy client.
+ *
+ * The ConnectionManager serves as an integration layer between the low-level
+ * ConnectionMonitor and the PlaycademyClient. It handles:
+ * - Event wiring and coordination
+ * - Disconnect callbacks with context
+ * - Platform-level alert integration
+ * - Request success/failure tracking
+ *
+ * This class is used internally by PlaycademyClient and typically not
+ * instantiated directly by game developers.
+ *
+ * @see {@link ConnectionMonitor} for the underlying monitoring implementation
+ * @see {@link PlaycademyClient.onDisconnect} for the public API
+ */
+declare class ConnectionManager {
+    private monitor?;
+    private authContext?;
+    private disconnectHandler?;
+    private connectionChangeCallback?;
+    private currentState;
+    private additionalDisconnectHandlers;
+    /**
+     * Creates a new ConnectionManager instance.
+     *
+     * @param config - Configuration options for the manager
+     *
+     * @example
+     * ```typescript
+     * const manager = new ConnectionManager({
+     *   baseUrl: 'https://api.playcademy.com',
+     *   authContext: { isInIframe: false },
+     *   onDisconnect: (context) => {
+     *     console.log(`Disconnected: ${context.state}`)
+     *   },
+     *   onConnectionChange: (state, reason) => {
+     *     console.log(`Connection changed: ${state}`)
+     *   }
+     * })
+     * ```
+     */
+    constructor(config: ConnectionManagerConfig);
+    /**
+     * Gets the current connection state.
+     *
+     * @returns The current connection state ('online', 'offline', or 'degraded')
+     *
+     * @example
+     * ```typescript
+     * const state = manager.getState()
+     * if (state === 'offline') {
+     *   console.log('No connection')
+     * }
+     * ```
+     */
+    getState(): ConnectionState;
+    /**
+     * Manually triggers a connection check immediately.
+     *
+     * Forces a heartbeat ping to verify the current connection status.
+     * Useful when you need to check connectivity before a critical operation.
+     *
+     * In iframe mode, this returns the last known state from platform.
+     *
+     * @returns Promise resolving to the current connection state
+     *
+     * @example
+     * ```typescript
+     * const state = await manager.checkNow()
+     * if (state === 'online') {
+     *   await performCriticalOperation()
+     * }
+     * ```
+     */
+    checkNow(): Promise<ConnectionState>;
+    /**
+     * Reports a successful API request to the connection monitor.
+     *
+     * This resets the consecutive failure counter and transitions from
+     * 'degraded' to 'online' state if applicable.
+     *
+     * Typically called automatically by the SDK's request wrapper.
+     * No-op in iframe mode (platform handles monitoring).
+     */
+    reportRequestSuccess(): void;
+    /**
+     * Reports a failed API request to the connection monitor.
+     *
+     * Only network errors are tracked (not 4xx/5xx HTTP responses).
+     * After consecutive failures exceed the threshold, the state transitions
+     * to 'degraded' or 'offline'.
+     *
+     * Typically called automatically by the SDK's request wrapper.
+     * No-op in iframe mode (platform handles monitoring).
+     *
+     * @param error - The error from the failed request
+     */
+    reportRequestFailure(error: unknown): void;
+    /**
+     * Registers a callback to be called when connection issues are detected.
+     *
+     * The callback only fires for 'offline' and 'degraded' states, not when
+     * recovering to 'online'. This provides a clean API for games to handle
+     * disconnect scenarios without being notified of every state change.
+     *
+     * Works in both iframe and standalone modes transparently.
+     *
+     * @param callback - Function to call when connection degrades
+     * @returns Cleanup function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
+     *   if (state === 'offline') {
+     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
+     *     saveGameState()
+     *   }
+     * })
+     *
+     * // Later: cleanup() to unregister
+     * ```
+     */
+    onDisconnect(callback: DisconnectHandler): () => void;
+    /**
+     * Stops connection monitoring and performs cleanup.
+     *
+     * Removes event listeners and clears heartbeat intervals.
+     * Should be called when the client is being destroyed.
+     */
+    stop(): void;
+    /**
+     * Sets up listener for platform connection state broadcasts (iframe mode only).
+     */
+    private _setupPlatformListener;
+    /**
+     * Handles connection state changes from the monitor or platform.
+     *
+     * Coordinates between:
+     * 1. Emitting events to the client (for client.on('connectionChange'))
+     * 2. Calling the disconnect handler if configured
+     * 3. Calling any additional handlers registered via onDisconnect()
+     *
+     * @param state - The new connection state
+     * @param reason - Human-readable reason for the state change
+     */
+    private _handleConnectionChange;
+}
 
 /**
  * @fileoverview Authentication Strategy Pattern
@@ -4862,6 +4716,169 @@ declare abstract class PlaycademyBaseClient {
     };
 }
 
+/**
+ * Options for configuring activity tracking behavior.
+ */
+interface StartActivityOptions {
+    /**
+     * How long the tab can stay hidden before the timing window resets on return.
+     * Defaults to 10 minutes. Set to `Infinity` to disable.
+     */
+    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.
+     */
+    heartbeatIntervalMs?: number;
+}
+
+/**
+ * @fileoverview Playcademy Messaging System
+ *
+ * This file implements a unified messaging system for the Playcademy platform that handles
+ * communication between different contexts:
+ *
+ * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
+ *    they need to communicate with the parent window using postMessage API
+ *
+ * 2. **Local Communication**: When games run in the same context (local development),
+ *    they use CustomEvents for internal messaging
+ *
+ * The system automatically detects the runtime environment and chooses the appropriate
+ * transport method, abstracting this complexity from the developer.
+ *
+ * **Architecture Overview**:
+ * - Games run in iframes for security and isolation
+ * - Parent window (Playcademy shell) manages game lifecycle
+ * - Messages flow bidirectionally between parent and iframe
+ * - Local development mode simulates this architecture without iframes
+ */
+
+/**
+ * Enumeration of all message types used in the Playcademy messaging system.
+ *
+ * **Message Flow Patterns**:
+ *
+ * **Parent → Game (Overworld → Game)**:
+ * - INIT: Provides game with authentication token and configuration
+ * - TOKEN_REFRESH: Updates game's authentication token before expiry
+ * - PAUSE/RESUME: Controls game execution state
+ * - FORCE_EXIT: Immediately terminates the game
+ * - OVERLAY: Shows/hides UI overlays over the game
+ *
+ * **Game → Parent (Game → Overworld)**:
+ * - READY: Game has loaded and is ready to receive messages
+ * - EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
+ * - TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)
+ */
+declare enum MessageEvents {
+    /**
+     * Initializes the game with authentication context and configuration.
+     * Sent immediately after game iframe loads.
+     * Payload:
+     * - `baseUrl`: string
+     * - `token`: string
+     * - `gameId`: string
+     */
+    INIT = "PLAYCADEMY_INIT",
+    /**
+     * Updates the game's authentication token before it expires.
+     * Sent periodically to maintain valid authentication.
+     * Payload:
+     * - `token`: string
+     * - `exp`: number
+     */
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
+    /**
+     * Pauses game execution (e.g., when user switches tabs).
+     * Game should pause timers, animations, and user input.
+     * Payload: void
+     */
+    PAUSE = "PLAYCADEMY_PAUSE",
+    /**
+     * Resumes game execution after being paused.
+     * Game should restore timers, animations, and user input.
+     * Payload: void
+     */
+    RESUME = "PLAYCADEMY_RESUME",
+    /**
+     * Forces immediate game termination (emergency exit).
+     * Game should clean up resources and exit immediately.
+     * Payload: void
+     */
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
+    /**
+     * Shows or hides UI overlays over the game.
+     * Game may need to pause or adjust rendering accordingly.
+     * Payload: boolean (true = show overlay, false = hide overlay)
+     */
+    OVERLAY = "PLAYCADEMY_OVERLAY",
+    /**
+     * Broadcasts connection state changes to games.
+     * Sent by platform when network connectivity changes.
+     * Payload:
+     * - `state`: 'online' | 'offline' | 'degraded'
+     * - `reason`: string
+     */
+    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
+    /**
+     * Game has finished loading and is ready to receive messages.
+     * Sent once after game initialization is complete.
+     * Payload: void
+     */
+    READY = "PLAYCADEMY_READY",
+    /**
+     * Game requests to be closed/exited.
+     * Sent when user clicks exit button or game naturally ends.
+     * Payload: void
+     */
+    EXIT = "PLAYCADEMY_EXIT",
+    /**
+     * Game reports performance telemetry data.
+     * Sent periodically for monitoring and analytics.
+     * Payload:
+     * - `fps`: number
+     * - `mem`: number
+     */
+    TELEMETRY = "PLAYCADEMY_TELEMETRY",
+    /**
+     * Game reports key events to parent.
+     * Sent when certain keys are pressed within the game iframe.
+     * Payload:
+     * - `key`: string
+     * - `code?`: string
+     * - `type`: 'keydown' | 'keyup'
+     */
+    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
+    /**
+     * Game requests platform to display an alert.
+     * Sent when connection issues are detected or other important events occur.
+     * Payload:
+     * - `message`: string
+     * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
+     */
+    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
+    /**
+     * Notifies about authentication state changes.
+     * Can be sent in both directions depending on auth flow.
+     * Payload:
+     * - `authenticated`: boolean
+     * - `user`: UserInfo | null
+     * - `error`: Error | null
+     */
+    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
+    /**
+     * OAuth callback data from popup/new-tab windows.
+     * Sent from popup window back to parent after OAuth completes.
+     * Payload:
+     * - `code`: string (OAuth authorization code)
+     * - `state`: string (OAuth state for CSRF protection)
+     * - `error`: string | null (OAuth error if any)
+     */
+    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
+}
+
 /**
  * Auto-initializes a PlaycademyClient with context from the environment.
  * Works in both iframe mode (production/development) and standalone mode (local dev).
@@ -4999,7 +5016,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData) => void;
+        startActivity: (metadata: ActivityData, options?: StartActivityOptions | undefined) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;