@playcademy/sdk 0.6.1-beta.3 → 0.6.1-beta.5

package/dist/types.d.ts

@@ -332,6 +332,14 @@ interface GameTimebackIntegration {
     createdAt: Date;
     updatedAt: Date;
 }
+type TimebackPromotionStatus = 'promoted' | 'no-next-course' | 'already-promoted' | 'not-enrolled' | 'not-mastered';
+interface TimebackPromotionResult {
+    status: TimebackPromotionStatus;
+    currentCourseId: string;
+    nextCourseId?: string;
+    masteredUnits?: number;
+    masterableUnits?: number;
+}
 interface EndActivityResponse {
     status: 'ok';
     courseId: string;
@@ -341,98 +349,200 @@ interface EndActivityResponse {
     scoreStatus?: string;
     inProgress?: string;
 }
+interface AdvanceCourseResponse {
+    status: 'ok';
+    promotion: TimebackPromotionResult;
+}
 
 /**
- * Achievement Types
+ * @fileoverview Server SDK Type Definitions
  *
- * @module types/achievement
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
  */
-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"
+
+/**
+ * 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>;
 }
-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;
+/**
+ * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
+ * Used in playcademy.config.* to allow per-course customization.
+ */
+interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
+    title?: string;
+    courseCode?: string;
+    level?: string;
+    metadata?: CourseConfig['metadata'];
+    totalXp?: number | null;
+    masterableUnits?: number | null;
 }
-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;
+/**
+ * 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.
+ */
+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 AchievementHistoryEntry {
-    achievementId: string;
-    title: string;
-    rewardCredits: number;
-    createdAt: Date;
-    scopeKey: string;
+/**
+ * Custom API routes integration
+ */
+interface CustomRoutesIntegration {
+    /** Directory for custom API routes (defaults to 'server/api') */
+    directory?: string;
 }
-interface AchievementProgressResponse {
-    achievementId: string;
-    status: 'completed' | 'already_completed';
-    rewardCredits: number;
-    scopeKey: string;
-    createdAt: Date;
+/**
+ * Database integration
+ */
+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;
+}
+/**
+ * Integrations configuration
+ * All backend features (database, custom routes, external services) are configured here
+ */
+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;
 }
 
 /**
- * Notification Types
+ * Configuration options for initializing a PlaycademyClient instance.
  *
- * @module types/notification
+ * @example
+ * ```typescript
+ * const config: PlaycademyServerClientConfig = {
+ *   apiKey: process.env.PLAYCADEMY_API_KEY!,
+ *   gameId: 'my-math-game',
+ *   configPath: './playcademy.config.js'
+ * }
+ * ```
  */
-
-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 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;
 }
-interface NotificationStats {
-    total: number;
-    delivered: number;
-    seen: number;
-    clicked: number;
-    dismissed: number;
-    expired: number;
-    clickThroughRate: number;
+/**
+ * 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;
 }
 
 /**
@@ -597,30 +707,94 @@ interface UserRankResponse {
     score: number;
     userId: string;
 }
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+/**
+ * Leaderboard entry with required game context.
+ * Used when fetching leaderboards for a specific game.
+ */
+interface GameLeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+
+/**
+ * Achievement Types
+ *
+ * @module types/achievement
+ */
+type AchievementScopeType = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'game' | 'global' | 'map' | 'level' | 'event';
+declare enum AchievementCompletionType {
+    TIME_PLAYED_SESSION = "time_played_session",
+    INTERACTION = "interaction",
+    LEADERBOARD_RANK = "leaderboard_rank",
+    FIRST_SCORE = "first_score",
+    PERSONAL_BEST = "personal_best"
+}
+interface AchievementCurrent {
+    id: string;
+    title: string;
+    description?: string | null;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: string;
+    completionConfig: unknown;
+    target: unknown;
+    active: boolean;
+    createdAt?: Date | null;
+    updatedAt?: Date | null;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart: string;
+    windowEnd: string;
+}
+interface AchievementWithStatus {
+    id: string;
+    title: string;
+    description: string | null;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: string;
+    completionConfig: unknown;
+    target: unknown;
+    active: boolean;
+    createdAt: Date | null;
+    updatedAt: Date | null;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart?: string;
+    windowEnd?: string;
+}
+interface AchievementHistoryEntry {
+    achievementId: string;
+    title: string;
+    rewardCredits: number;
+    createdAt: Date;
+    scopeKey: string;
 }
-/**
- * Leaderboard entry with required game context.
- * Used when fetching leaderboards for a specific game.
- */
-interface GameLeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
+interface AchievementProgressResponse {
+    achievementId: string;
+    status: 'completed' | 'already_completed';
+    rewardCredits: number;
+    scopeKey: string;
+    createdAt: Date;
 }
 
 /**
@@ -740,6 +914,35 @@ interface LevelProgressResponse {
     totalXP: number;
 }
 
+/**
+ * Notification Types
+ *
+ * @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;
+}
+
 /**
  * Shop Types
  *
@@ -1064,7 +1267,7 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 
 interface GameMetadata {
@@ -1340,7 +1543,7 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const gameSessions: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "game_sessions";
@@ -1432,7 +1635,7 @@ declare const gameSessions: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 /**
  * Custom hostnames table
@@ -1633,7 +1836,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
@@ -1810,7 +2013,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "inventory_items";
@@ -1902,7 +2105,7 @@ declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const currencies: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "currencies";
@@ -2011,7 +2214,7 @@ declare const currencies: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const shopListings: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "shop_listings";
@@ -2205,7 +2408,7 @@ declare const shopListings: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const maps: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "maps";
@@ -2356,7 +2559,7 @@ declare const maps: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const mapElements: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "map_elements";
@@ -2469,7 +2672,7 @@ declare const mapElements: drizzle_orm_pg_core.PgTableWithColumns<{
             $type: Record<string, unknown>;
         }>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const mapObjects: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "map_objects";
@@ -2629,7 +2832,7 @@ declare const mapObjects: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 
 declare const userLevels: drizzle_orm_pg_core.PgTableWithColumns<{
@@ -2756,7 +2959,7 @@ declare const userLevels: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const levelConfigs: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "level_configs";
@@ -2848,7 +3051,7 @@ declare const levelConfigs: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 
 declare const spriteTemplates: drizzle_orm_pg_core.PgTableWithColumns<{
@@ -2945,7 +3148,7 @@ declare const spriteTemplates: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const characterComponents: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "character_components";
@@ -3128,7 +3331,7 @@ declare const characterComponents: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const playerCharacters: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "player_characters";
@@ -3271,7 +3474,7 @@ declare const playerCharacters: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const playerCharacterAccessories: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "player_character_accessories";
@@ -3382,7 +3585,7 @@ declare const playerCharacterAccessories: drizzle_orm_pg_core.PgTableWithColumns
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "notifications";
@@ -3667,7 +3870,7 @@ declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
     displayName: z.ZodString;
@@ -4410,197 +4613,6 @@ type SpriteTemplateRow = typeof spriteTemplates.$inferSelect;
 
 type NotificationRow = InferSelectModel<typeof notifications>;
 
-/**
- * @fileoverview Server SDK Type Definitions
- *
- * TypeScript type definitions for the server-side Playcademy SDK.
- * Includes configuration types, client state, and re-exported TimeBack types.
- */
-
-/**
- * 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>;
-}
-/**
- * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
- * Used in playcademy.config.* to allow per-course customization.
- */
-interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
-    title?: string;
-    courseCode?: string;
-    level?: string;
-    metadata?: CourseConfig['metadata'];
-    totalXp?: number | null;
-    masterableUnits?: number | null;
-}
-/**
- * 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.
- */
-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;
-}
-/**
- * Custom API routes integration
- */
-interface CustomRoutesIntegration {
-    /** Directory for custom API routes (defaults to 'server/api') */
-    directory?: string;
-}
-/**
- * Database integration
- */
-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;
-}
-/**
- * Integrations configuration
- * All backend features (database, custom routes, external services) are configured here
- */
-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;
-}
-
 /**
  * Connection monitoring types
  *
@@ -5241,8 +5253,8 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     runtime: {
         getGameToken: (gameId: string, options?: {
-            apply?: boolean | undefined;
-        } | undefined) => Promise<GameTokenResponse>;
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
         exit: () => Promise<void>;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -5266,7 +5278,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
         getListenerCounts: () => Record<string, number>;
         assets: {
             url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit | undefined) => Promise<Response>;
+            fetch: (path: string, options?: RequestInit) => Promise<Response>;
             json: <T = unknown>(path: string) => Promise<T>;
             blob: (path: string) => Promise<Blob>;
             text: (path: string) => Promise<string>;
@@ -5291,10 +5303,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData, options?: StartActivityOptions | undefined) => void;
+        startActivity: (metadata: ActivityData, options?: StartActivityOptions) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
+        advanceCourse: (options?: {
+            subject?: TimebackSubject;
+        }) => Promise<AdvanceCourseResponse>;
     };
     /**
      * Playcademy Credits (platform currency) management.
@@ -5311,14 +5326,14 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `submit(score, metadata?)` - Record a game score
      */
     scores: {
-        submit: (score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
+        submit: (score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
     };
     /**
      * Read-only leaderboard access for the current game scope.
      * - `fetch(options?)` - Fetch leaderboard entries
      */
     leaderboard: {
-        fetch: (options?: LeaderboardOptions | undefined) => Promise<GameLeaderboardEntry[]>;
+        fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
     };
     /**
      * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
@@ -5332,7 +5347,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             get: () => Promise<DemoProfile>;
             update: (updates: DemoProfileUpdate) => Promise<DemoProfile>;
         };
-        end: (score: number, options?: DemoEndOptions | undefined) => void;
+        end: (score: number, options?: DemoEndOptions) => void;
     };
     /**
      * Realtime multiplayer authentication.
@@ -5349,13 +5364,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
      */
     backend: {
-        get<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<Response>;
+        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
         url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
     };
     /** Auto-initializes a PlaycademyClient with context from the environment */