@playcademy/sdk 0.9.0 → 0.9.1-beta.2

package/dist/types.d.ts

@@ -1,8 +1,8 @@
+import { UserRole, AUTH_PROVIDER_IDS } from '@playcademy/constants';
 import { InferSelectModel } from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as drizzle_zod from 'drizzle-zod';
 import { z } from 'zod';
-import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
  * OAuth 2.0 implementation for the Playcademy SDK
@@ -26,105 +26,378 @@ interface RetryPolicy {
 }
 
 /**
- * TimeBack Enums & Literal Types
+ * User Types
  *
- * Basic type definitions used throughout the TimeBack integration.
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
  *
- * @module types/timeback/types
- */
-/**
- * Valid TimeBack subject values for course configuration.
- * These are the supported subject values for OneRoster courses.
- */
-type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
-/**
- * Grade levels per AE OneRoster GradeEnum.
- * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ * @module types/user
  */
-type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+
+type UserRoleEnumType = UserRole;
+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;
+    enrollmentIds?: {
+        active: string;
+        inactive?: string[];
+    };
+    grade: number;
+    subject: string;
+    orgId?: string;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    enrollments: UserEnrollment[];
+}
 /**
- * Valid Caliper subject values.
- * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ * OpenID Connect UserInfo claims (NOT a database row).
  */
-type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+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;
+}
+interface DemoProfile {
+    displayName: string;
+    isDefault: boolean;
+}
 /**
- * OneRoster organization types.
+ * Update shape for `client.demo.profile.update(...)`.
+ *
+ * Kept as a named type so callers typed against it pick up new fields
+ * automatically, but `displayName` is the only updatable field today and
+ * the server's `DemoProfileSchema` requires it — a no-field payload would
+ * 400 at runtime, so we model that at the type level too. When additional
+ * fields land, make them required/optional individually based on server
+ * validation, rather than blanket-optional.
  */
-type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface DemoProfileUpdate {
+    displayName: string;
+}
 /**
- * Lesson types for PowerPath integration.
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
  */
-type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
+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;
+}
 
 /**
- * TimeBack Configuration Types
+ * Game Types
  *
- * Configuration interfaces for Organization, Course, Component,
- * Resource, and complete TimeBack setup.
+ * Literal types and API DTOs. Database row types are in @playcademy/data/types.
  *
- * @module types/timeback/config
+ * @module types/game
  */
 
+type GameType = 'hosted' | 'external';
+type GamePlatform = 'web' | 'godot' | 'unity' | (string & {});
 /**
- * Organization configuration for TimeBack (user input - optionals allowed)
+ * Game manifest file format (manifest.json).
+ * Note: createdAt is a string here because it's parsed from JSON file.
  */
-interface OrganizationConfig {
-    /** Display name for your organization */
-    name?: string;
-    /** Organization type */
-    type?: OrganizationType;
-    /** Unique identifier (defaults to Playcademy's org) */
-    identifier?: string;
+interface ManifestV1 {
+    version: '1';
+    platform: string;
+    createdAt: string;
+}
+interface ManifestVersions {
+    vitePlugin?: string;
+    sdk?: string;
+    cli?: string;
+    vite?: string;
+    godotSdk?: string;
+    godot?: string;
+}
+interface ManifestV2 {
+    version: '2';
+    platform: string;
+    createdAt: string;
+    versions: ManifestVersions;
 }
+type GameManifest = ManifestV1 | ManifestV2;
+interface DomainValidationRecords {
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
+}
+
 /**
- * Course goals for daily student targets
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
  */
-interface CourseGoals {
-    /** Target XP students should earn per day */
-    dailyXp?: number;
-    /** Target lessons per day */
-    dailyLessons?: number;
-    /** Target active minutes per day */
-    dailyActiveMinutes?: number;
-    /** Target accuracy percentage */
-    dailyAccuracy?: number;
-    /** Target mastered units per day */
-    dailyMasteredUnits?: number;
+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;
 }
 /**
- * Course metrics and totals
+ * Leaderboard entry with required game context.
+ * Used when fetching leaderboards for a specific game.
  */
-interface CourseMetrics {
-    /** Total XP available in the course */
-    totalXp?: number;
-    /** Total lessons/activities in the course */
-    totalLessons?: number;
-    /** Total number of grade levels covered by this course */
-    totalGrades?: number;
-    /** The type of course (e.g. 'optional', 'hole-filling', 'base') */
-    courseType?: 'base' | 'hole-filling' | 'optional' | 'Base' | 'Hole-Filling' | 'Optional';
-    /** Indicates whether the course is supplemental content */
-    isSupplemental?: boolean;
+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;
 }
+
 /**
- * Complete course metadata structure
+ * Achievement Types
+ *
+ * @module types/achievement
  */
-interface CourseMetadata {
-    /** Define the type of course and priority for the student */
-    courseType?: 'base' | 'hole-filling' | 'optional';
-    /** Boolean value to determine if a course is supplemental to a base course */
-    isSupplemental?: boolean;
-    /** Boolean value to determine if a course is custom to an individual student */
-    isCustom?: boolean;
-    /** Signals whether a course is in production with students */
-    publishStatus?: 'draft' | 'testing' | 'published' | 'deactivated';
-    /** Whether this course appears in the TimeBack catalog for teachers and parents */
-    timebackVisible?: boolean;
-    /** Who to contact when issues reported with questions */
-    contactEmail?: string;
-    /** Primary app identifier */
-    primaryApp?: string;
-    /** Learning goals for students */
+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
+ *
+ * Basic type definitions used throughout the TimeBack integration.
+ *
+ * @module types/timeback/types
+ */
+/**
+ * Valid TimeBack subject values for course configuration.
+ * These are the supported subject values for OneRoster courses.
+ */
+type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+/**
+ * Valid Caliper subject values.
+ * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ */
+type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * OneRoster organization types.
+ */
+type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * Lesson types for PowerPath integration.
+ */
+type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
+
+/**
+ * TimeBack Configuration Types
+ *
+ * Configuration interfaces for Organization, Course, Component,
+ * Resource, and complete TimeBack setup.
+ *
+ * @module types/timeback/config
+ */
+
+/**
+ * Organization configuration for TimeBack (user input - optionals allowed)
+ */
+interface OrganizationConfig {
+    /** Display name for your organization */
+    name?: string;
+    /** Organization type */
+    type?: OrganizationType;
+    /** Unique identifier (defaults to Playcademy's org) */
+    identifier?: string;
+}
+/**
+ * Course goals for daily student targets
+ */
+interface CourseGoals {
+    /** Target XP students should earn per day */
+    dailyXp?: number;
+    /** Target lessons per day */
+    dailyLessons?: number;
+    /** Target active minutes per day */
+    dailyActiveMinutes?: number;
+    /** Target accuracy percentage */
+    dailyAccuracy?: number;
+    /** Target mastered units per day */
+    dailyMasteredUnits?: number;
+}
+/**
+ * Course metrics and totals
+ */
+interface CourseMetrics {
+    /** Total XP available in the course */
+    totalXp?: number;
+    /** Total lessons/activities in the course */
+    totalLessons?: number;
+    /** Total number of grade levels covered by this course */
+    totalGrades?: number;
+    /** The type of course (e.g. 'optional', 'hole-filling', 'base') */
+    courseType?: 'base' | 'hole-filling' | 'optional' | 'Base' | 'Hole-Filling' | 'Optional';
+    /** Indicates whether the course is supplemental content */
+    isSupplemental?: boolean;
+}
+/**
+ * Complete course metadata structure
+ */
+interface CourseMetadata {
+    /** Define the type of course and priority for the student */
+    courseType?: 'base' | 'hole-filling' | 'optional';
+    /** Boolean value to determine if a course is supplemental to a base course */
+    isSupplemental?: boolean;
+    /** Boolean value to determine if a course is custom to an individual student */
+    isCustom?: boolean;
+    /** Signals whether a course is in production with students */
+    publishStatus?: 'draft' | 'testing' | 'published' | 'deactivated';
+    /** Whether this course appears in the TimeBack catalog for teachers and parents */
+    timebackVisible?: boolean;
+    /** Who to contact when issues reported with questions */
+    contactEmail?: string;
+    /** Primary app identifier */
+    primaryApp?: string;
+    /** Learning goals for students */
     goals?: CourseGoals;
     /** Course metrics and totals */
     metrics?: CourseMetrics;
@@ -451,705 +724,804 @@ type GameMetricsProxyResponse = {
 };
 
 /**
- * @fileoverview Server SDK Type Definitions
+ * Inventory & Shop Types
  *
- * TypeScript type definitions for the server-side Playcademy SDK.
- * Includes configuration types, client state, and re-exported TimeBack 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';
 
 /**
- * Base configuration for TimeBack integration (shared across all courses).
- * References upstream TimeBack types from @playcademy/timeback.
+ * Map & Placement Types
  *
- * All fields are optional and support template variables: {grade}, {subject}, {gameSlug}
+ * Literal types and JSON shapes for maps. Database row types are in @playcademy/data/types.
+ *
+ * @module types/map
  */
-interface TimebackBaseConfig {
-    /** Organization configuration (shared across all courses) */
-    organization?: Partial<OrganizationConfig>;
-    /** Course defaults (can be overridden per-course) */
-    course?: Partial<CourseConfig>;
-    /** Component defaults */
-    component?: Partial<ComponentConfig>;
-    /** Resource defaults */
-    resource?: Partial<ResourceConfig>;
-    /** ComponentResource defaults */
-    componentResource?: Partial<ComponentResourceConfig>;
-}
 /**
- * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
- * Used in playcademy.config.* to allow per-course customization.
+ * Allowed map interaction types.
  */
-interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
+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;
-    courseCode?: string;
-    level?: string;
-    metadata?: CourseConfig['metadata'];
-    totalXp?: number | null;
-    masterableUnits?: number | null;
+    targetMapIdentifier?: string;
+    targetSpawnTileX?: number;
+    targetSpawnTileY?: number;
+    sourceTiledObjects?: Record<string, unknown>[];
+    [key: string]: unknown;
 }
 /**
- * TimeBack integration configuration for Playcademy config file.
- *
- * Supports two levels of customization:
- * 1. `base`: Shared defaults for all courses (organization, course, component, resource, componentResource)
- * 2. Per-course overrides in the `courses` array (title, courseCode, level, gradingScheme, metadata)
- *
- * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
+ * Metadata describing how an item should be placed on the map.
  */
-interface TimebackIntegrationConfig {
-    /** Multi-grade course configuration (array of grade/subject/totalXp with optional per-course overrides) */
-    courses: TimebackCourseConfigWithOverrides[];
-    /** Optional base configuration (shared across all courses, can be overridden per-course) */
-    base?: TimebackBaseConfig;
+interface PlaceableItemMetadata {
+    tilesWide?: number;
+    tilesHigh?: number;
+    flippable?: boolean;
+    [key: string]: unknown;
 }
 /**
- * Custom API routes integration
+ * Simplified map data for API responses.
  */
-interface CustomRoutesIntegration {
-    /** Directory for custom API routes (defaults to 'server/api') */
-    directory?: string;
+interface MapData {
+    id: string;
+    identifier: string;
+    displayName: string;
+    description?: string | null;
+    metadata?: Record<string, unknown> | null;
 }
 /**
- * Database integration
+ * Input for creating a map object.
  */
-interface DatabaseIntegration {
-    /** Database directory (defaults to 'db') */
-    directory?: string;
-    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
-     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
-    strategy?: 'push' | 'migrate';
-}
-interface QueueConfig {
-    maxBatchSize?: number;
-    maxRetries?: number;
-    maxBatchTimeout?: number;
-    maxConcurrency?: number;
-    retryDelay?: number;
-    deadLetterQueue?: string;
+interface CreateMapObjectData {
+    itemId: string;
+    worldX: number;
+    worldY: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    scale?: number;
+    metadata?: Record<string, unknown>;
 }
+
 /**
- * Integrations configuration
- * All backend features (database, custom routes, external services) are configured here
+ * Character & Avatar Types
+ *
+ * Literal types for character system. Database row types are in @playcademy/data/types.
+ *
+ * @module types/character
  */
-interface IntegrationsConfig {
-    /** TimeBack integration (optional) */
-    timeback?: TimebackIntegrationConfig | null;
-    /** Custom API routes (optional) */
-    customRoutes?: CustomRoutesIntegration | boolean;
-    /** Database (optional) */
-    database?: DatabaseIntegration | boolean;
-    /** Key-Value storage (optional) */
-    kv?: boolean;
-    /** Bucket storage (optional) */
-    bucket?: boolean;
-    /** Authentication (optional) */
-    auth?: boolean;
-    /** Queues (optional) */
-    queues?: Record<string, QueueConfig | boolean>;
-}
 /**
- * Unified Playcademy configuration
- * Used for playcademy.config.{js,json}
+ * Character component categories.
  */
-interface PlaycademyConfig {
-    /** Game name */
-    name: string;
-    /** Game description */
-    description?: string;
-    /** Game emoji icon */
-    emoji?: string;
-    /** Build command to run before deployment */
-    buildCommand?: string[];
-    /** Path to build output */
-    buildPath?: string;
-    /** Game type */
-    gameType?: 'hosted' | 'external';
-    /** External URL (for external games) */
-    externalUrl?: string;
-    /** Game platform */
-    platform?: 'web' | 'unity' | 'godot';
-    /** Integrations (database, custom routes, external services) */
-    integrations?: IntegrationsConfig;
-}
+type CharacterComponentType = 'body' | 'outfit' | 'hairstyle' | 'eyes' | 'accessory';
 
 /**
- * Configuration options for initializing a PlaycademyClient instance.
+ * Level & Progression Types
  *
- * @example
- * ```typescript
- * const config: PlaycademyServerClientConfig = {
- *   apiKey: process.env.PLAYCADEMY_API_KEY!,
- *   gameId: 'my-math-game',
- *   configPath: './playcademy.config.js'
- * }
- * ```
+ * API response DTOs for level system. Database row types are in @playcademy/data/types.
+ *
+ * @module types/level
  */
-interface PlaycademyServerClientConfig {
-    /**
-     * Playcademy API key for server-to-server authentication.
-     * Obtain from the Playcademy developer dashboard.
-     */
-    apiKey: string;
-    /**
-     * Optional path to playcademy.config.js file.
-     * If not provided, searches current directory and up to 3 parent directories.
-     * Ignored if `config` is provided directly.
-     *
-     * @example './config/playcademy.config.js'
-     */
-    configPath?: string;
-    /**
-     * Optional config object (for edge environments without filesystem).
-     * If provided, skips filesystem-based config loading.
-     *
-     * @example { name: 'My Game', integrations: { timeback: {...} } }
-     */
-    config?: PlaycademyConfig;
-    /**
-     * Optional base URL for Playcademy API.
-     * Defaults to environment variables or 'https://hub.playcademy.net'.
-     *
-     * @example 'http://localhost:3000' for local development
-     */
-    baseUrl?: string;
-    /**
-     * Optional game ID.
-     * If not provided, will attempt to fetch from API using the API token.
-     *
-     * @example 'my-math-game'
-     */
-    gameId?: string;
-}
 /**
- * Internal state maintained by the PlaycademyClient instance.
- *
- * @internal
+ * Result of adding XP to a user.
  */
-interface PlaycademyServerClientState {
-    /** API key for authentication */
-    apiKey: string;
-    /** Base URL for API requests */
-    baseUrl: string;
-    /** Game identifier */
-    gameId: string;
-    /** Loaded game configuration from playcademy.config.js */
-    config: PlaycademyConfig;
-    /**
-     * TimeBack course ID fetched from the Playcademy API.
-     * Used for all TimeBack event recording.
-     */
-    courseId?: string;
+interface XPAddResult {
+    totalXP: number;
+    newLevel: number;
+    leveledUp: boolean;
+    creditsAwarded: number;
+    xpToNextLevel: number;
 }
-
 /**
- * User Types
- *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
- *
- * @module types/user
+ * Result of checking whether a level up occurred.
  */
-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[];
+interface LevelUpCheckResult {
+    newLevel: number;
+    remainingXp: number;
+    leveledUp: boolean;
+    creditsAwarded: number;
+    xpToNextLevel: number;
 }
 /**
- * OpenID Connect UserInfo claims (NOT a database row).
+ * Level progress API response.
  */
-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;
-}
-interface DemoProfile {
-    displayName: string;
-    isDefault: boolean;
+interface LevelProgressResponse {
+    level: number;
+    currentXp: number;
+    xpToNextLevel: number;
+    totalXP: number;
 }
+
 /**
- * Update shape for `client.demo.profile.update(...)`.
+ * Notification Types
  *
- * Kept as a named type so callers typed against it pick up new fields
- * automatically, but `displayName` is the only updatable field today and
- * the server's `DemoProfileSchema` requires it — a no-field payload would
- * 400 at runtime, so we model that at the type level too. When additional
- * fields land, make them required/optional individually based on server
- * validation, rather than blanket-optional.
+ * @module types/notification
  */
-interface DemoProfileUpdate {
-    displayName: string;
+
+declare enum NotificationType {
+    ACHIEVEMENT = "achievement",
+    SYSTEM = "system",
+    PROMO = "promo"
 }
-/**
- * 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;
+declare enum NotificationStatus {
+    PENDING = "pending",
+    DELIVERED = "delivered",
+    SEEN = "seen",
+    CLICKED = "clicked",
+    DISMISSED = "dismissed",
+    EXPIRED = "expired"
 }
-interface GameUser {
-    id: string;
-    name: string | null;
-    role: UserRoleEnumType;
-    username: string | null;
-    email: string | null;
-    timeback?: UserTimebackData;
+interface NotificationStats {
+    total: number;
+    delivered: number;
+    seen: number;
+    clicked: number;
+    dismissed: number;
+    expired: number;
+    clickThroughRate: number;
 }
 
 /**
- * Game Types
- *
- * Literal types and API DTOs. Database row types are in @playcademy/data/types.
+ * Shop Types
  *
- * @module types/game
+ * @module types/shop
  */
-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.
+ * Currency display info for shop UI.
  */
-interface ManifestV1 {
-    version: '1';
-    platform: string;
-    createdAt: string;
-}
-interface ManifestVersions {
-    vitePlugin?: string;
-    sdk?: string;
-    cli?: string;
-    vite?: string;
-    godotSdk?: string;
-    godot?: string;
-}
-interface ManifestV2 {
-    version: '2';
-    platform: string;
-    createdAt: string;
-    versions: ManifestVersions;
-}
-type GameManifest = ManifestV1 | ManifestV2;
-interface DomainValidationRecords {
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    ssl?: {
-        txt_name?: string;
-        txt_value?: string;
-    }[];
+interface ShopCurrency {
+    id: string;
+    symbol: string | null;
+    isPrimary: boolean;
+    displayName?: string | null;
+    imageUrl?: string | null;
 }
-
 /**
- * Leaderboard Types
- *
- * @module types/leaderboard
+ * Shop item for display.
+ * Combines Item fields (excluding createdAt) with shop listing data.
  */
-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 {
+interface ShopDisplayItem {
     id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: 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;
 }
 /**
- * Leaderboard entry with required game context.
- * Used when fetching leaderboards for a specific game.
+ * Complete shop view response.
  */
-interface GameLeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+interface ShopViewResponse {
+    shopItems: ShopDisplayItem[];
+    currencies: ShopCurrency[];
 }
 
 /**
- * Achievement Types
+ * Sprite Types
  *
- * @module types/achievement
+ * JSON shapes for sprite configuration. Database row types are in @playcademy/data/types.
+ *
+ * @module types/sprite
  */
-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;
+/**
+ * Animation frame configuration.
+ */
+interface SpriteAnimationFrame {
+    row: number;
+    frameStart: number;
+    numFrames: number;
+    fps: number;
 }
-interface AchievementHistoryEntry {
-    achievementId: string;
-    title: string;
-    rewardCredits: number;
-    createdAt: Date;
-    scopeKey: string;
+/**
+ * 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 AchievementProgressResponse {
-    achievementId: string;
-    status: 'completed' | 'already_completed';
-    rewardCredits: number;
-    scopeKey: string;
-    createdAt: Date;
+/**
+ * Sprite sheet configuration with precomputed dimensions.
+ */
+interface SpriteConfigWithDimensions {
+    textureUrl: string;
+    columns: number;
+    rows: number;
+    spriteWidth: number;
+    spriteHeight: number;
+    animations: Record<string, SpriteAnimationFrame>;
 }
 
 /**
- * Inventory & Shop Types
- *
- * Literal types for inventory system. Database row types are in @playcademy/data/types.
+ * Connection monitoring types
  *
- * @module types/inventory
+ * Type definitions for connection state, configuration, and callbacks.
  */
 /**
- * Item categories available on the platform.
+ * Possible connection states.
+ *
+ * - **online**: Connection is stable and healthy
+ * - **offline**: Complete loss of network connectivity
+ * - **degraded**: Connection is slow or experiencing intermittent issues
  */
-type ItemType = 'currency' | 'badge' | 'trophy' | 'collectible' | 'consumable' | 'unlock' | 'upgrade' | 'accessory' | 'other';
+type ConnectionState = 'online' | 'offline' | 'degraded';
 
 /**
- * Map & Placement Types
+ * Connection Manager
  *
- * Literal types and JSON shapes for maps. Database row types are in @playcademy/data/types.
+ * Manages connection monitoring and integrates it with the Playcademy client.
+ * Handles event wiring, state management, and disconnect callbacks.
  *
- * @module types/map
+ * In iframe mode, disables local monitoring and listens to platform connection
+ * state broadcasts instead (avoids duplicate heartbeats).
  */
+
 /**
- * Allowed map interaction types.
+ * Configuration for the ConnectionManager.
  */
-type InteractionType = 'game_entry' | 'game_registry' | 'info' | 'teleport' | 'door_in' | 'door_out' | 'npc_interaction' | 'quest_trigger';
+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;
+}
 /**
- * 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;
-}
-/**
- * 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.
+ * 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
  */
-interface CreateMapObjectData {
-    itemId: string;
-    worldX: number;
-    worldY: number;
-    width?: number;
-    height?: number;
-    rotation?: number;
-    scale?: number;
-    metadata?: Record<string, unknown>;
+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;
 }
 
 /**
- * Character & Avatar Types
+ * @fileoverview Playcademy Messaging System
  *
- * Literal types for character system. Database row types are in @playcademy/data/types.
+ * This file implements a unified messaging system for the Playcademy platform that handles
+ * communication between different contexts:
  *
- * @module types/character
- */
-/**
- * Character component categories.
- */
-type CharacterComponentType = 'body' | 'outfit' | 'hairstyle' | 'eyes' | 'accessory';
-
-/**
- * Level & Progression Types
+ * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
+ *    they need to communicate with the parent window using postMessage API
  *
- * API response DTOs for level system. Database row types are in @playcademy/data/types.
+ * 2. **Local Communication**: When games run in the same context (local development),
+ *    they use CustomEvents for internal messaging
  *
- * @module types/level
- */
-/**
- * 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.
+ * 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
  */
-interface LevelProgressResponse {
-    level: number;
-    currentXp: number;
-    xpToNextLevel: number;
-    totalXP: number;
-}
 
 /**
- * Notification Types
+ * Enumeration of all message types used in the Playcademy messaging system.
  *
- * @module types/notification
- */
-
-declare enum NotificationType {
-    ACHIEVEMENT = "achievement",
-    SYSTEM = "system",
-    PROMO = "promo"
-}
-declare enum NotificationStatus {
-    PENDING = "pending",
-    DELIVERED = "delivered",
-    SEEN = "seen",
-    CLICKED = "clicked",
-    DISMISSED = "dismissed",
-    EXPIRED = "expired"
-}
-interface NotificationStats {
-    total: number;
-    delivered: number;
-    seen: number;
-    clicked: number;
-    dismissed: number;
-    expired: number;
-    clickThroughRate: number;
+ * **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 SDK initialization failed.
+     * Sent when the game iframe fails to complete SDK init (e.g.
+     * origin validation failure, INIT timeout, client creation error).
+     * Payload:
+     * - `reason`: string — human-readable failure description
+     */
+    INIT_ERROR = "PLAYCADEMY_INIT_ERROR",
+    /**
+     * 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",
+    /**
+     * Game signals that demo mode has ended.
+     * Sent when a demo experience reaches its CTA/upgrade boundary.
+     * Payload:
+     * - `score?`: number
+     * - `durationMs?`: number
+     * - `metadata?`: `Record<string, unknown>`
+     */
+    DEMO_END = "PLAYCADEMY_DEMO_END",
+    /**
+     * 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"
 }
 
 /**
- * Shop Types
- *
- * @module types/shop
+ * Cache configuration types for runtime customization
  */
 /**
- * Currency display info for shop UI.
+ * Runtime configuration for TTL cache behavior
  */
-interface ShopCurrency {
-    id: string;
-    symbol: string | null;
-    isPrimary: boolean;
-    displayName?: string | null;
-    imageUrl?: string | null;
+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;
 }
+
 /**
- * Shop item for display.
- * Combines Item fields (excluding createdAt) with shop listing data.
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
  */
-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;
+
+/**
+ * Base configuration for TimeBack integration (shared across all courses).
+ * References upstream TimeBack types from @playcademy/timeback.
+ *
+ * All fields are optional and support template variables: {grade}, {subject}, {gameSlug}
+ */
+interface TimebackBaseConfig {
+    /** Organization configuration (shared across all courses) */
+    organization?: Partial<OrganizationConfig>;
+    /** Course defaults (can be overridden per-course) */
+    course?: Partial<CourseConfig>;
+    /** Component defaults */
+    component?: Partial<ComponentConfig>;
+    /** Resource defaults */
+    resource?: Partial<ResourceConfig>;
+    /** ComponentResource defaults */
+    componentResource?: Partial<ComponentResourceConfig>;
 }
 /**
- * Complete shop view response.
+ * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
+ * Used in playcademy.config.* to allow per-course customization.
  */
-interface ShopViewResponse {
-    shopItems: ShopDisplayItem[];
-    currencies: ShopCurrency[];
+interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
+    title?: string;
+    courseCode?: string;
+    level?: string;
+    metadata?: CourseConfig['metadata'];
+    totalXp?: number | null;
+    masterableUnits?: number | null;
 }
-
 /**
- * Sprite Types
+ * TimeBack integration configuration for Playcademy config file.
  *
- * JSON shapes for sprite configuration. Database row types are in @playcademy/data/types.
+ * Supports two levels of customization:
+ * 1. `base`: Shared defaults for all courses (organization, course, component, resource, componentResource)
+ * 2. Per-course overrides in the `courses` array (title, courseCode, level, gradingScheme, metadata)
  *
- * @module types/sprite
+ * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
  */
+interface TimebackIntegrationConfig {
+    /** Multi-grade course configuration (array of grade/subject/totalXp with optional per-course overrides) */
+    courses: TimebackCourseConfigWithOverrides[];
+    /** Optional base configuration (shared across all courses, can be overridden per-course) */
+    base?: TimebackBaseConfig;
+}
 /**
- * Animation frame configuration.
+ * Custom API routes integration
  */
-interface SpriteAnimationFrame {
-    row: number;
-    frameStart: number;
-    numFrames: number;
-    fps: number;
+interface CustomRoutesIntegration {
+    /** Directory for custom API routes (defaults to 'server/api') */
+    directory?: string;
 }
 /**
- * Sprite template data structure (stored in JSONB).
+ * Database integration
  */
-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 DatabaseIntegration {
+    /** Database directory (defaults to 'db') */
+    directory?: string;
+    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
+     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
+    strategy?: 'push' | 'migrate';
+}
+interface QueueConfig {
+    maxBatchSize?: number;
+    maxRetries?: number;
+    maxBatchTimeout?: number;
+    maxConcurrency?: number;
+    retryDelay?: number;
+    deadLetterQueue?: string;
 }
 /**
- * Sprite sheet configuration with precomputed dimensions.
+ * Integrations configuration
+ * All backend features (database, custom routes, external services) are configured here
  */
-interface SpriteConfigWithDimensions {
-    textureUrl: string;
-    columns: number;
-    rows: number;
-    spriteWidth: number;
-    spriteHeight: number;
-    animations: Record<string, SpriteAnimationFrame>;
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig | null;
+    /** Custom API routes (optional) */
+    customRoutes?: CustomRoutesIntegration | boolean;
+    /** Database (optional) */
+    database?: DatabaseIntegration | boolean;
+    /** Key-Value storage (optional) */
+    kv?: boolean;
+    /** Bucket storage (optional) */
+    bucket?: boolean;
+    /** Authentication (optional) */
+    auth?: boolean;
+    /** Queues (optional) */
+    queues?: Record<string, QueueConfig | boolean>;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Integrations (database, custom routes, external services) */
+    integrations?: IntegrationsConfig;
+}
+
+/**
+ * Configuration options for initializing a PlaycademyClient instance.
+ *
+ * @example
+ * ```typescript
+ * const config: PlaycademyServerClientConfig = {
+ *   apiKey: process.env.PLAYCADEMY_API_KEY!,
+ *   gameId: 'my-math-game',
+ *   configPath: './playcademy.config.js'
+ * }
+ * ```
+ */
+interface PlaycademyServerClientConfig {
+    /**
+     * Playcademy API key for server-to-server authentication.
+     * Obtain from the Playcademy developer dashboard.
+     */
+    apiKey: string;
+    /**
+     * Optional path to playcademy.config.js file.
+     * If not provided, searches current directory and up to 3 parent directories.
+     * Ignored if `config` is provided directly.
+     *
+     * @example './config/playcademy.config.js'
+     */
+    configPath?: string;
+    /**
+     * Optional config object (for edge environments without filesystem).
+     * If provided, skips filesystem-based config loading.
+     *
+     * @example { name: 'My Game', integrations: { timeback: {...} } }
+     */
+    config?: PlaycademyConfig;
+    /**
+     * Optional base URL for Playcademy API.
+     * Defaults to environment variables or 'https://hub.playcademy.net'.
+     *
+     * @example 'http://localhost:3000' for local development
+     */
+    baseUrl?: string;
+    /**
+     * Optional game ID.
+     * If not provided, will attempt to fetch from API using the API token.
+     *
+     * @example 'my-math-game'
+     */
+    gameId?: string;
+}
+/**
+ * Internal state maintained by the PlaycademyClient instance.
+ *
+ * @internal
+ */
+interface PlaycademyServerClientState {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API requests */
+    baseUrl: string;
+    /** Game identifier */
+    gameId: string;
+    /** Loaded game configuration from playcademy.config.js */
+    config: PlaycademyConfig;
+    /**
+     * TimeBack course ID fetched from the Playcademy API.
+     * Used for all TimeBack event recording.
+     */
+    courseId?: string;
 }
 
 declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
@@ -3970,7 +4342,7 @@ declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
     displayName: z.ZodString;
     mapElementId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     platform: z.ZodEnum<["web", "godot", "unity"]>;
-    metadata: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    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.ZodString>;
@@ -4648,480 +5020,64 @@ interface PlayerInventoryItem {
     inventoryItemEntryId: InventoryItemRow['id'];
     item: ItemRow;
     quantity: InventoryItemRow['quantity'];
-    updatedAt: InventoryItemRow['updatedAt'];
-}
-interface PlayerLocation {
-    mapIdentifier: MapRow['identifier'];
-    mapDisplayName: MapRow['displayName'];
-    tileX?: number;
-    tileY?: number;
-    worldX?: number;
-    worldY?: number;
-    direction?: 'up' | 'down' | 'left' | 'right';
-}
-interface PlayerSessionPayload {
-    profile: PlayerProfile;
-    currencies: PlayerCurrency[];
-    inventory: PlayerInventoryItem[];
-    ownedGameIds: Game['id'][];
-    currentLocation?: PlayerLocation;
-    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>;
-
-/**
- * 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 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 SDK initialization failed.
-     * Sent when the game iframe fails to complete SDK init (e.g.
-     * origin validation failure, INIT timeout, client creation error).
-     * Payload:
-     * - `reason`: string — human-readable failure description
-     */
-    INIT_ERROR = "PLAYCADEMY_INIT_ERROR",
-    /**
-     * 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",
-    /**
-     * Game signals that demo mode has ended.
-     * Sent when a demo experience reaches its CTA/upgrade boundary.
-     * Payload:
-     * - `score?`: number
-     * - `durationMs?`: number
-     * - `metadata?`: `Record<string, unknown>`
-     */
-    DEMO_END = "PLAYCADEMY_DEMO_END",
-    /**
-     * 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).
- *
- * 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' })
- * ```
+    updatedAt: InventoryItemRow['updatedAt'];
+}
+interface PlayerLocation {
+    mapIdentifier: MapRow['identifier'];
+    mapDisplayName: MapRow['displayName'];
+    tileX?: number;
+    tileY?: number;
+    worldX?: number;
+    worldY?: number;
+    direction?: 'up' | 'down' | 'left' | 'right';
+}
+interface PlayerSessionPayload {
+    profile: PlayerProfile;
+    currencies: PlayerCurrency[];
+    inventory: PlayerInventoryItem[];
+    ownedGameIds: Game['id'][];
+    currentLocation?: PlayerLocation;
+    characterCreated?: UserRow['characterCreated'];
+    playerCharacter?: PlayerCharacterRow | null;
+}
+/**
+ * Map-related Composite Types
+ * DB row + joined game/item data
  */
-declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
-    baseUrl?: string;
-    allowedParentOrigins?: string[];
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
-}): Promise<T>;
-
+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;
+    };
+};
 /**
- * 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)
- * }
- * ```
+ * Game custom hostname with validation records
  */
-declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+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>;
 
 /**
  * @fileoverview Authentication Strategy Pattern
@@ -5295,52 +5251,69 @@ declare abstract class PlaycademyBaseClient {
 }
 
 /**
- * Options for configuring activity tracking behavior.
+ * 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' })
+ * ```
  */
-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;
-}
+declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}): Promise<T>;
+
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @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>;
 
 /**
  * Playcademy SDK client for game developers.
@@ -5404,19 +5377,22 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * User context (cached from init, refreshable):
      * - `user.role` - User's role (student, parent, teacher, etc.)
      * - `user.enrollments` - Courses the player is enrolled in for this game
+     * - `user.refresh({ only: ['enrollments'] })` - Refresh enrollments from server
      * - `user.organizations` - Schools/districts the player belongs to
      * - `user.fetch()` - Refresh user context from server
      *
      * Activity tracking:
-     * - `startActivity(metadata)` - Begin tracking an activity with automatic
-     *   hidden-tab and visible-tab inactivity handling, plus configurable
-     *   paused-heartbeat timeout behavior
+     * - `currentRunId` - Current activity run ID, or undefined when inactive
+     * - `startActivity(metadata)` - Begin tracking an activity, return its run
+     *   ID, and automatically handle hidden-tab and visible-tab inactivity
+     *   with configurable paused-heartbeat timeout behavior
      * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
      * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData, options?: StartActivityOptions) => void;
+        readonly currentRunId: string | undefined;
+        startActivity: (metadata: ActivityData, options?: StartActivityOptions) => StartActivityResult;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
@@ -5496,6 +5472,57 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
     };
 }
 
+/**
+ * Options for configuring activity tracking behavior.
+ */
+interface StartActivityOptions {
+    /**
+     * How long heartbeats continue after the activity is automatically paused
+     * because the tab is hidden or the player is inactive while visible.
+     * Defaults to 10 minutes. Set to `Infinity` to keep heartbeats running
+     * indefinitely during automatic pauses. Invalid values fall back to the
+     * 10-minute default.
+     */
+    pausedHeartbeatTimeoutMs?: number;
+    /**
+     * @deprecated Use `pausedHeartbeatTimeoutMs` instead.
+     *
+     * Backward-compatible alias for callers that still use the old option
+     * name from earlier SDK releases.
+     */
+    hiddenTimeoutMs?: number;
+    /**
+     * How often to flush periodic heartbeats with accumulated time data.
+     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
+     * final unload/endActivity flushes still run. Values must be greater than
+     * 0 or `Infinity`; invalid values fall back to the 15-second default.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * How long the tab can remain visible without keyboard or mouse activity
+     * before the activity is marked inactive. Defaults to 10 minutes. Set to
+     * `Infinity` to disable keyboard/mouse inactivity tracking. Invalid values
+     * fall back to the 10-minute default.
+     */
+    inactivityTimeoutMs?: number;
+    /**
+     * Stable identifier for this activity run. When provided, it is used on
+     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     *
+     * Pass the same `runId` across multiple `startActivity()` calls (for
+     * example, after the player closes and reopens a resumable activity) so
+     * downstream systems can correlate related sessions into a single run.
+     *
+     * Must be a UUID (the backend validates it as such) and unique per
+     * logical run. If omitted, the SDK generates a new UUID on each call,
+     * which means every session is treated as its own run.
+     */
+    runId?: string;
+}
+interface StartActivityResult {
+    runId: string;
+}
+
 /**
  * Type definitions for the game timeback namespace.
  *
@@ -5505,7 +5532,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
 
 /**
  * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId.
+ * Alias for UserEnrollment without the optional gameId. Active enrollment IDs
+ * are available at `enrollment.enrollmentIds?.active` when supplied by the
+ * platform.
  */
 type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
@@ -5541,6 +5570,14 @@ interface TimebackUserContext {
     /** User's organizations (schools/districts) */
     organizations: TimebackOrganization[];
 }
+/**
+ * Slice options for refreshing the cached TimeBack user context.
+ */
+type TimebackUserRefreshField = 'enrollments';
+interface TimebackUserRefreshOptions extends TTLCacheConfig {
+    /** Refresh only these user data fields */
+    only: readonly TimebackUserRefreshField[];
+}
 /**
  * XP data access for the current user.
  * Results are cached for 5 seconds to avoid redundant network requests.
@@ -5581,7 +5618,7 @@ interface TimebackUserXp {
     fetch(options?: GetXpOptions): Promise<XpResponse>;
 }
 /**
- * TimeBack user object with both cached getters and fetch method.
+ * TimeBack user object with cached getters, fetch, and targeted refresh methods.
  */
 interface TimebackUser extends TimebackUserContext {
     /**
@@ -5590,9 +5627,14 @@ interface TimebackUser extends TimebackUserContext {
      * @param options - Cache options (pass { force: true } to bypass cache)
      * @returns Promise resolving to fresh user context
      */
-    fetch(options?: {
-        force?: boolean;
-    }): Promise<TimebackUserContext>;
+    fetch(options?: TTLCacheConfig): Promise<TimebackUserContext>;
+    /**
+     * Refresh selected TimeBack user data from the server.
+     * Updates the cached user snapshot used by the synchronous getters.
+     * @param options - Refresh fields and cache options
+     * @returns Promise resolving to the updated user context
+     */
+    refresh(options: TimebackUserRefreshOptions): Promise<TimebackUserContext>;
     /**
      * XP data for the current user.
      * Call `xp.fetch()` to get XP from the server.
@@ -6167,4 +6209,4 @@ interface AssessmentBankStatus {
 }
 
 export { AchievementCompletionType, NotificationStatus, NotificationType, PlaycademyClient };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameActivityMetrics, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, MapRow as GameMap, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitErrorPayload, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, QtiTestQuestionRef, QtiTestQuestionsResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameActivityMetrics, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, MapRow as GameMap, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitErrorPayload, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, QtiTestQuestionRef, QtiTestQuestionsResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartActivityOptions, StartActivityResult, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };