@playcademy/sdk 0.2.11 → 0.2.13

package/dist/internal.d.ts

@@ -1,8 +1,8 @@
+import { SchemaInfo } from '@playcademy/cloudflare';
 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 { SchemaInfo } from '@playcademy/cloudflare';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
@@ -583,6 +583,56 @@ interface PopulateStudentResponse {
     status: string;
     message?: string;
 }
+interface TimebackSetupRequest {
+    gameId: string;
+    config: {
+        organization: {
+            name: string;
+            type: string;
+            identifier: string;
+        };
+        course: {
+            title: string;
+            subjects: string[];
+            grades: number[];
+            courseCode: string;
+            level: string;
+            gradingScheme: string;
+            metadata?: Record<string, unknown>;
+        };
+        component: {
+            title: string;
+            sortOrder: number;
+            prerequisites: string[];
+            prerequisiteCriteria: string;
+        };
+        resource: {
+            title: string;
+            vendorResourceId: string;
+            vendorId: string;
+            applicationId: string;
+            roles: string[];
+            importance: string;
+            metadata: {
+                type?: string;
+                launchUrl?: string;
+                toolProvider?: string;
+                instructionalMethod?: string;
+                subject?: string;
+                grades?: number[];
+                language?: string;
+                xp?: number;
+                [key: string]: unknown;
+            };
+        };
+        componentResource: {
+            title: string;
+            sortOrder: number;
+            lessonType: string | null;
+        };
+    };
+    verbose?: boolean;
+}
 interface PlatformTimebackSetupRequest {
     gameId: string;
     courses: DerivedPlatformCourseConfig[];
@@ -928,7 +978,7 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "user";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "admin" | "developer" | "player";
+            data: "admin" | "player" | "developer";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -945,7 +995,7 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "user";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "approved" | "none" | "pending";
+            data: "none" | "pending" | "approved";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1134,7 +1184,7 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "games";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "external" | "hosted";
+            data: "hosted" | "external";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1185,7 +1235,7 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "games";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "godot" | "unity" | "web";
+            data: "web" | "godot" | "unity";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1461,7 +1511,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "game_custom_hostnames";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "production" | "staging";
+            data: "staging" | "production";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1478,7 +1528,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "game_custom_hostnames";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "active" | "blocked" | "deleted" | "pending" | "pending_deletion" | "pending_deployment" | "pending_validation";
+            data: "pending" | "active" | "pending_validation" | "pending_deployment" | "pending_deletion" | "blocked" | "deleted";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1495,7 +1545,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "game_custom_hostnames";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "active" | "deleted" | "initializing" | "pending_deployment" | "pending_issuance" | "pending_validation";
+            data: "active" | "pending_validation" | "pending_deployment" | "deleted" | "initializing" | "pending_issuance";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1657,7 +1707,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "items";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+            data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -2348,7 +2398,7 @@ declare const mapElements: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "map_elements";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "door_in" | "door_out" | "game_entry" | "game_registry" | "info" | "npc_interaction" | "quest_trigger" | "teleport";
+            data: "info" | "game_entry" | "game_registry" | "teleport" | "door_in" | "door_out" | "npc_interaction" | "quest_trigger";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -2901,7 +2951,7 @@ declare const characterComponents: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "character_components";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "accessory" | "body" | "eyes" | "hairstyle" | "outfit";
+            data: "accessory" | "body" | "outfit" | "hairstyle" | "eyes";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -3427,7 +3477,7 @@ declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "notifications";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "high" | "low" | "normal" | "urgent";
+            data: "low" | "normal" | "high" | "urgent";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -3444,7 +3494,7 @@ declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "notifications";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
+            data: "pending" | "delivered" | "seen" | "clicked" | "dismissed" | "expired";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -3605,33 +3655,33 @@ declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
     gameType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["hosted", "external"]>>>;
     externalUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    displayName: string;
-    mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
     metadata: Record<string, unknown>;
-    gameType: "external" | "hosted";
+    displayName: string;
+    gameType: "hosted" | "external";
+    platform: "web" | "godot" | "unity";
     externalUrl?: string | undefined;
+    mapElementId?: string | null | undefined;
 }, {
     displayName: string;
-    mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
+    platform: "web" | "godot" | "unity";
     metadata?: Record<string, unknown> | undefined;
-    gameType?: "external" | "hosted" | undefined;
+    gameType?: "hosted" | "external" | undefined;
     externalUrl?: string | undefined;
-}>, {
-    displayName: string;
     mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
+}>, {
     metadata: Record<string, unknown>;
-    gameType: "external" | "hosted";
+    displayName: string;
+    gameType: "hosted" | "external";
+    platform: "web" | "godot" | "unity";
     externalUrl?: string | undefined;
+    mapElementId?: string | null | undefined;
 }, {
     displayName: string;
-    mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
+    platform: "web" | "godot" | "unity";
     metadata?: Record<string, unknown> | undefined;
-    gameType?: "external" | "hosted" | undefined;
+    gameType?: "hosted" | "external" | undefined;
     externalUrl?: string | undefined;
+    mapElementId?: string | null | undefined;
 }>;
 
 declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
@@ -3725,7 +3775,7 @@ declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
         tableName: "items";
         dataType: "string";
         columnType: "PgEnumColumn";
-        data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+        data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
         driverParam: string;
         notNull: true;
         hasDefault: true;
@@ -3820,24 +3870,24 @@ declare const UpdateItemSchema: z.ZodObject<Omit<{
     imageUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     createdAt: z.ZodOptional<z.ZodDate>;
-}, "createdAt" | "id">, "strip", z.ZodTypeAny, {
+}, "id" | "createdAt">, "strip", z.ZodTypeAny, {
+    description?: string | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     slug?: string | undefined;
-    gameId?: string | null | undefined;
     displayName?: string | undefined;
-    description?: string | null | undefined;
-    type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
+    gameId?: string | null | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
-    metadata?: Record<string, unknown> | undefined;
 }, {
+    description?: string | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     slug?: string | undefined;
-    gameId?: string | null | undefined;
     displayName?: string | undefined;
-    description?: string | null | undefined;
-    type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
+    gameId?: string | null | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
-    metadata?: Record<string, unknown> | undefined;
 }>;
 declare const InsertCurrencySchema: drizzle_zod.BuildSchema<"insert", {
     id: drizzle_orm_pg_core.PgColumn<{
@@ -3947,16 +3997,16 @@ declare const InsertCurrencySchema: drizzle_zod.BuildSchema<"insert", {
     isPrimary: z.ZodDefault<z.ZodBoolean>;
 }>;
 declare const UpdateCurrencySchema: z.ZodObject<{
-    itemId: z.ZodOptional<z.ZodString>;
     symbol: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    itemId: z.ZodOptional<z.ZodString>;
     isPrimary: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
-    itemId?: string | undefined;
     symbol?: string | null | undefined;
+    itemId?: string | undefined;
     isPrimary?: boolean | undefined;
 }, {
-    itemId?: string | undefined;
     symbol?: string | null | undefined;
+    itemId?: string | undefined;
     isPrimary?: boolean | undefined;
 }>;
 declare const InsertShopListingSchema: drizzle_zod.BuildSchema<"insert", {
@@ -4167,28 +4217,28 @@ declare const UpdateShopListingSchema: z.ZodObject<{
     updatedAt: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
 }, "strip", z.ZodTypeAny, {
     id?: string | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | null | undefined;
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
-    createdAt?: Date | undefined;
-    updatedAt?: Date | null | undefined;
 }, {
     id?: string | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | null | undefined;
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
-    createdAt?: Date | undefined;
-    updatedAt?: Date | null | undefined;
 }>;
 
 type GameRow = typeof games.$inferSelect;
@@ -5569,71 +5619,6 @@ declare class PlaycademyMessaging {
  */
 declare const messaging: PlaycademyMessaging;
 
-/**
- * Auto-initializes a PlaycademyClient with context from the environment.
- * Works in both iframe mode (production/development) and standalone mode (local dev).
- *
- * This is the recommended way to initialize the SDK as it automatically:
- * - Detects the runtime environment (iframe vs standalone)
- * - Configures the client with the appropriate context
- * - Sets up event listeners for token refresh
- * - Exposes the client for debugging in development mode
- *
- * @param options - Optional configuration overrides
- * @param options.baseUrl - Override the base URL for API requests
- * @returns Promise resolving to a fully initialized PlaycademyClient
- * @throws Error if not running in a browser context
- *
- * @example
- * ```typescript
- * // Default initialization
- * const client = await PlaycademyClient.init()
- *
- * // With custom base URL
- * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
- * ```
- */
-declare function init<T extends PlaycademyClient = PlaycademyClient>(this: new (...args: ConstructorParameters<typeof PlaycademyClient>) => 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>;
-
 /**
  * @fileoverview Authentication Strategy Pattern
  *
@@ -5768,6 +5753,9 @@ declare abstract class PlaycademyBaseClient {
      * Initializes connection monitoring if enabled.
      */
     private _initializeConnectionMonitor;
+    /**
+     * Initializes an internal game session for automatic session management.
+     */
     private _initializeInternalSession;
     /**
      * Current user data and inventory management.
@@ -5788,144 +5776,81 @@ declare abstract class PlaycademyBaseClient {
 }
 
 /**
- * Playcademy SDK client for game developers.
- * Provides namespaced access to platform features for games running inside Cademy.
- */
-declare class PlaycademyClient extends PlaycademyBaseClient {
-    /**
-     * Connect external identity providers to the user's Playcademy account.
-     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
-     */
-    identity: {
-        connect: (options: AuthOptions) => Promise<AuthResult>;
-        _getContext: () => {
-            isInIframe: boolean;
-        };
-    };
-    /**
-     * Game runtime lifecycle and asset loading.
-     * - `exit()` - Return to Cademy hub
-     * - `getGameToken()` - Get short-lived auth token
-     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
-     * - `on('pause')`, `on('resume')` - Handle visibility changes
-     */
-    runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean | undefined;
-        } | undefined) => Promise<GameTokenResponse>;
-        exit: () => Promise<void>;
-        onInit: (handler: (context: GameContextPayload) => void) => void;
-        onTokenRefresh: (handler: (data: {
-            token: string;
-            exp: number;
-        }) => void) => void;
-        onPause: (handler: () => void) => void;
-        onResume: (handler: () => void) => void;
-        onForceExit: (handler: () => void) => void;
-        onOverlay: (handler: (isVisible: boolean) => void) => void;
-        ready: () => void;
-        sendTelemetry: (data: {
-            fps: number;
-            mem: number;
-        }) => void;
-        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
-            token: string;
-            exp: number;
-        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
-        removeAllListeners: () => void;
-        getListenerCounts: () => Record<string, number>;
-        assets: {
-            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit | undefined) => Promise<Response>;
-            json: <T = unknown>(path: string) => Promise<T>;
-            blob: (path: string) => Promise<Blob>;
-            text: (path: string) => Promise<string>;
-            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
-        };
-    };
-    /**
-     * TimeBack integration for activity tracking and user context.
-     *
-     * 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.organizations` - Schools/districts the player belongs to
-     * - `user.fetch()` - Refresh user context from server
-     *
-     * Activity tracking:
-     * - `startActivity(metadata)` - Begin tracking an activity
-     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
-     * - `endActivity(scoreData)` - Submit activity results to TimeBack
-     */
-    timeback: {
-        readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData) => void;
-        pauseActivity: () => void;
-        resumeActivity: () => void;
-        endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
-    };
-    /**
-     * Playcademy Credits (platform currency) management.
-     * - `get()` - Get user's credit balance
-     * - `add(amount)` - Award credits to user
-     */
-    credits: {
-        balance: () => Promise<number>;
-        add: (amount: number) => Promise<number>;
-        spend: (amount: number) => Promise<number>;
-    };
-    /**
-     * Game score submission and leaderboards.
-     * - `submit(gameId, score, metadata?)` - Record a game score
-     */
-    scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
-    };
-    /**
-     * Realtime multiplayer authentication.
-     * - `getToken()` - Get token for WebSocket/realtime connections
-     */
-    realtime: {
-        token: {
-            get: () => Promise<RealtimeTokenResponse>;
-        };
-    };
-    /**
-     * Make requests to your game's custom backend API routes.
-     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
-     * - 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>;
-        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-    };
-    /** Auto-initializes a PlaycademyClient with context from the environment */
-    static init: typeof init;
-    /** Authenticates a user with email and password */
-    static login: typeof login;
-    /** Static identity utilities for OAuth operations */
-    static identity: {
-        parseOAuthState: typeof parseOAuthState;
-    };
-}
-
-/**
- * Type definitions for the game timeback namespace.
+ * Auto-initializes a PlaycademyClient with context from the environment.
+ * Works in both iframe mode (production/development) and standalone mode (local dev).
  *
- * SDK-specific types like TimebackInitContext that wrap the core types
- * from @playcademy/types/user (which are re-exported via types/data.ts).
- */
-
-/**
- * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId.
- */
+ * This is the recommended way to initialize the SDK as it automatically:
+ * - Detects the runtime environment (iframe vs standalone)
+ * - Configures the client with the appropriate context
+ * - Sets up event listeners for token refresh
+ * - Exposes the client for debugging in development mode
+ *
+ * @param options - Optional configuration overrides
+ * @param options.baseUrl - Override the base URL for API requests
+ * @returns Promise resolving to a fully initialized PlaycademyClient
+ * @throws Error if not running in a browser context
+ *
+ * @example
+ * ```typescript
+ * // Default initialization
+ * const client = await PlaycademyClient.init()
+ *
+ * // With custom base URL
+ * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
+ * ```
+ */
+declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}): Promise<T>;
+
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @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>;
+
+/**
+ * Type definitions for the game timeback namespace.
+ *
+ * SDK-specific types like TimebackInitContext that wrap the core types
+ * from @playcademy/types/user (which are re-exported via types/data.ts).
+ */
+
+/**
+ * A TimeBack enrollment for the current game session.
+ * Alias for UserEnrollment without the optional gameId.
+ */
 type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
  * A TimeBack organization (school/district) for the current user.
@@ -5960,6 +5885,45 @@ interface TimebackUserContext {
     /** User's organizations (schools/districts) */
     organizations: TimebackOrganization[];
 }
+/**
+ * XP data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserXp {
+    /**
+     * Fetch XP data from the server.
+     * Returns XP for all courses in this game, or filter by grade/subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     *
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse', 'today'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to XP data
+     *
+     * @example
+     * ```typescript
+     * // Get total XP for all game courses
+     * const xp = await client.timeback.user.xp.fetch()
+     *
+     * // Get XP for a specific grade/subject
+     * const xp = await client.timeback.user.xp.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get XP with per-course breakdown
+     * const xp = await client.timeback.user.xp.fetch({
+     *   include: ['perCourse', 'today']
+     * })
+     *
+     * // Force fresh data
+     * const xp = await client.timeback.user.xp.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetXpOptions): Promise<XpResponse>;
+}
 /**
  * TimeBack user object with both cached getters and fetch method.
  */
@@ -5973,6 +5937,42 @@ interface TimebackUser extends TimebackUserContext {
     fetch(options?: {
         force?: boolean;
     }): Promise<TimebackUserContext>;
+    /**
+     * XP data for the current user.
+     * Call `xp.fetch()` to get XP from the server.
+     */
+    xp: TimebackUserXp;
+}
+/**
+ * Options for querying student XP.
+ */
+interface GetXpOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse', 'today' */
+    include?: ('perCourse' | 'today')[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
+/**
+ * XP data for a single course.
+ */
+interface CourseXp {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from XP query.
+ */
+interface XpResponse {
+    totalXp: number;
+    todayXp?: number;
+    courses?: CourseXp[];
 }
 
 /**
@@ -6497,6 +6497,9 @@ interface CustomRoutesIntegration {
 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';
 }
 /**
  * Integrations configuration
@@ -6703,8 +6706,8 @@ declare class PlaycademyInternalClient 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: {
@@ -6728,7 +6731,7 @@ declare class PlaycademyInternalClient 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>;
@@ -6759,13 +6762,13 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
      */
     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;
     };
     /**
@@ -6780,21 +6783,28 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             password: string;
         }) => Promise<{
             success: boolean;
-            token?: string | undefined;
+            token?: string;
             user?: {
                 id: string;
                 email: string;
-            } | undefined;
-            expiresAt?: string | undefined;
-            error?: string | undefined;
+            };
+            expiresAt?: string;
+            error?: string;
         }>;
         logout: () => Promise<void>;
         apiKeys: {
             create: (options?: {
-                name?: string | undefined;
-                expiresIn?: number | null | undefined;
-                permissions?: Record<string, string[]> | undefined;
-            } | undefined) => Promise<BetterAuthApiKeyResponse>;
+                name?: string;
+                expiresIn
+                /**
+                 * Platform-wide achievements system.
+                 * - `list()` - Get all achievements
+                 * - `getUserAchievements()` - Get user's earned achievements
+                 * - `award(achievementId)` - Grant achievement to user
+                 */
+                ?: number | null;
+                permissions?: Record<string, string[]>;
+            }) => Promise<BetterAuthApiKeyResponse>;
             list: () => Promise<BetterAuthApiKey[]>;
             revoke: (keyId: string) => Promise<void>;
         };
@@ -6811,198 +6821,143 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             resumeGame: (gameId: string) => Promise<void>;
         };
         items: {
-            create: (props: {
-                id?: string | undefined;
+            create: (props: InsertItemInput) => Promise<{
+                gameId: string | null;
+                id: string;
                 slug: string;
-                gameId?: string | null | undefined;
                 displayName: string;
-                description?: string | null | undefined;
-                type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
-                isPlaceable?: boolean | undefined;
-                imageUrl?: string | null | undefined;
-                metadata?: Record<string, unknown> | undefined;
-                createdAt?: Date | undefined;
-            }) => Promise<{
-                createdAt: Date;
                 description: string | null;
-                displayName: string;
-                gameId: string | null;
-                id: string;
-                imageUrl: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
+                imageUrl: string | null;
                 metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+                createdAt: Date;
             }>;
             get: (itemId: string) => Promise<{
-                createdAt: Date;
-                description: string | null;
-                displayName: string;
                 gameId: string | null;
                 id: string;
-                imageUrl: string | null;
+                slug: string;
+                displayName: string;
+                description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
+                imageUrl: string | null;
                 metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+                createdAt: Date;
             }>;
             list: () => Promise<{
-                createdAt: Date;
-                description: string | null;
-                displayName: string;
                 gameId: string | null;
                 id: string;
-                imageUrl: string | null;
+                slug: string;
+                displayName: string;
+                description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
+                imageUrl: string | null;
                 metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-            }[]>;
-            update: (itemId: string, props: {
-                slug?: string | undefined;
-                gameId?: string | null | undefined;
-                displayName?: string | undefined;
-                description?: string | null | undefined;
-                type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
-                isPlaceable?: boolean | undefined;
-                imageUrl?: string | null | undefined;
-                metadata?: Record<string, unknown> | undefined;
-            }) => Promise<{
                 createdAt: Date;
-                description: string | null;
-                displayName: string;
+            }[]>;
+            update: (itemId: string, props: UpdateItemInput) => Promise<{
                 gameId: string | null;
                 id: string;
-                imageUrl: string | null;
+                slug: string;
+                displayName: string;
+                description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
+                imageUrl: string | null;
                 metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+                createdAt: Date;
             }>;
             delete: (itemId: string) => Promise<void>;
         };
         currencies: {
-            create: (props: {
-                id?: string | undefined;
-                itemId: string;
-                symbol?: string | null | undefined;
-                isPrimary: boolean;
-                createdAt?: Date | undefined;
-                updatedAt?: Date | null | undefined;
-            }) => Promise<{
-                createdAt: Date;
+            create: (props: InsertCurrencyInput) => Promise<{
+                symbol: string | null;
                 id: string;
-                isPrimary: boolean;
+                createdAt: Date;
                 itemId: string;
-                symbol: string | null;
                 updatedAt: Date | null;
+                isPrimary: boolean;
             }>;
             get: (currencyId: string) => Promise<{
-                createdAt: Date;
+                symbol: string | null;
                 id: string;
-                isPrimary: boolean;
+                createdAt: Date;
                 itemId: string;
-                symbol: string | null;
                 updatedAt: Date | null;
+                isPrimary: boolean;
             }>;
             list: () => Promise<{
-                createdAt: Date;
+                symbol: string | null;
                 id: string;
-                isPrimary: boolean;
+                createdAt: Date;
                 itemId: string;
-                symbol: string | null;
                 updatedAt: Date | null;
+                isPrimary: boolean;
             }[]>;
-            update: (currencyId: string, props: {
-                itemId?: string | undefined;
-                symbol?: string | null | undefined;
-                isPrimary?: boolean | undefined;
-            }) => Promise<{
-                createdAt: Date;
+            update: (currencyId: string, props: UpdateCurrencyInput) => Promise<{
+                symbol: string | null;
                 id: string;
-                isPrimary: boolean;
+                createdAt: Date;
                 itemId: string;
-                symbol: string | null;
                 updatedAt: Date | null;
+                isPrimary: boolean;
             }>;
             delete: (currencyId: string) => Promise<void>;
         };
         shopListings: {
-            create: (props: {
-                id?: string | undefined;
+            create: (props: InsertShopListingInput) => Promise<{
+                id: string;
+                createdAt: Date;
                 itemId: string;
+                updatedAt: Date | null;
                 currencyId: string;
                 price: number;
-                sellBackPercentage?: number | null | undefined;
-                stock?: number | null | undefined;
+                sellBackPercentage: number | null;
+                stock: number | null;
                 isActive: boolean;
-                availableFrom?: Date | null | undefined;
-                availableUntil?: Date | null | undefined;
-                createdAt?: Date | undefined;
-                updatedAt?: Date | null | undefined;
-            }) => Promise<{
                 availableFrom: Date | null;
                 availableUntil: Date | null;
-                createdAt: Date;
-                currencyId: string;
-                id: string;
-                isActive: boolean;
-                itemId: string;
-                price: number;
-                sellBackPercentage: number | null;
-                stock: number | null;
-                updatedAt: Date | null;
             }>;
             get: (listingId: string) => Promise<{
-                availableFrom: Date | null;
-                availableUntil: Date | null;
-                createdAt: Date;
-                currencyId: string;
                 id: string;
-                isActive: boolean;
+                createdAt: Date;
                 itemId: string;
+                updatedAt: Date | null;
+                currencyId: string;
                 price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
-                updatedAt: Date | null;
-            }>;
-            list: () => Promise<{
+                isActive: boolean;
                 availableFrom: Date | null;
                 availableUntil: Date | null;
-                createdAt: Date;
-                currencyId: string;
+            }>;
+            list: () => Promise<{
                 id: string;
-                isActive: boolean;
+                createdAt: Date;
                 itemId: string;
+                updatedAt: Date | null;
+                currencyId: string;
                 price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
-                updatedAt: Date | null;
-            }[]>;
-            update: (listingId: string, props: {
-                id?: string | undefined;
-                itemId?: string | undefined;
-                currencyId?: string | undefined;
-                price?: number | undefined;
-                sellBackPercentage?: number | null | undefined;
-                stock?: number | null | undefined;
-                isActive?: boolean | undefined;
-                availableFrom?: Date | null | undefined;
-                availableUntil?: Date | null | undefined;
-                createdAt?: Date | undefined;
-                updatedAt?: Date | null | undefined;
-            }) => Promise<{
+                isActive: boolean;
                 availableFrom: Date | null;
                 availableUntil: Date | null;
-                createdAt: Date;
-                currencyId: string;
+            }[]>;
+            update: (listingId: string, props: UpdateShopListingInput) => Promise<{
                 id: string;
-                isActive: boolean;
+                createdAt: Date;
                 itemId: string;
+                updatedAt: Date | null;
+                currencyId: string;
                 price: number;
                 sellBackPercentage: number | null;
                 stock: number | null;
-                updatedAt: Date | null;
+                isActive: boolean;
+                availableFrom: Date | null;
+                availableUntil: Date | null;
             }>;
             delete: (listingId: string) => Promise<void>;
         };
@@ -7016,31 +6971,17 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     dev: {
         status: {
             apply: () => Promise<void>;
-            get: () => Promise<DeveloperStatusEnumType>;
+            get: () => Promise<DeveloperStatusValue>;
         };
         games: {
             deploy: (slug: string, options: {
-                metadata?: {
-                    displayName: string;
-                    mapElementId?: string | null | undefined;
-                    platform: "godot" | "unity" | "web";
-                    metadata: Record<string, unknown>;
-                    gameType: "external" | "hosted";
-                    externalUrl?: string | undefined;
-                } | undefined;
-                file?: Blob | File | null | undefined;
-                backend?: BackendDeploymentBundle | undefined;
-                hooks?: DevUploadHooks | undefined;
-            }) => Promise<Game>;
-            seed: (slug: string, code: string, environment?: "production" | "staging" | undefined, secrets?: Record<string, string> | undefined) => Promise<SeedResponse>;
-            upsert: (slug: string, metadata: {
-                displayName: string;
-                mapElementId?: string | null | undefined;
-                platform: "godot" | "unity" | "web";
-                metadata: Record<string, unknown>;
-                gameType: "external" | "hosted";
-                externalUrl?: string | undefined;
+                metadata?: UpsertGameMetadataInput;
+                file?: File | Blob | null;
+                backend?: BackendDeploymentBundle;
+                hooks?: DevUploadHooks;
             }) => Promise<Game>;
+            seed: (slug: string, code: string, environment?: "staging" | "production", secrets?: Record<string, string>) => Promise<SeedResponse>;
+            upsert: (slug: string, metadata: UpsertGameMetadataInput) => Promise<Game>;
             delete: (gameId: string) => Promise<void>;
             secrets: {
                 set: (slug: string, secrets: Record<string, string>) => Promise<string[]>;
@@ -7051,7 +6992,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 reset: (slug: string, schema?: {
                     sql: string;
                     hash: string;
-                } | undefined) => Promise<{
+                }) => Promise<{
                     success: boolean;
                     deploymentId: string;
                     resetAt: string;
@@ -7059,13 +7000,13 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 }>;
             };
             bucket: {
-                list: (slug: string, prefix?: string | undefined) => Promise<BucketFile[]>;
+                list: (slug: string, prefix?: string) => Promise<BucketFile[]>;
                 get: (slug: string, key: string) => Promise<ArrayBuffer>;
-                put: (slug: string, key: string, content: ArrayBuffer | Blob | Uint8Array<ArrayBufferLike>, contentType?: string | undefined) => Promise<void>;
+                put: (slug: string, key: string, content: Blob | ArrayBuffer | Uint8Array, contentType?: string) => Promise<void>;
                 delete: (slug: string, key: string) => Promise<void>;
             };
             kv: {
-                list: (slug: string, prefix?: string | undefined) => Promise<KVKeyEntry[]>;
+                list: (slug: string, prefix?: string) => Promise<KVKeyEntry[]>;
                 get: (slug: string, key: string) => Promise<string | null>;
                 set: (slug: string, key: string, value: string) => Promise<void>;
                 delete: (slug: string, key: string) => Promise<void>;
@@ -7077,177 +7018,30 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             domains: {
                 add: (slug: string, hostname: string) => Promise<GameCustomHostname>;
                 list: (slug: string) => Promise<GameCustomHostname[]>;
-                status: (slug: string, hostname: string, refresh?: boolean | undefined) => Promise<GameCustomHostname>;
+                status: (slug: string, hostname: string, refresh?: boolean) => Promise<GameCustomHostname>;
                 delete: (slug: string, hostname: string) => Promise<void>;
             };
             logs: {
-                getToken: (slug: string, environment: "production" | "staging") => Promise<{
+                getToken: (slug: string, environment: "staging" | "production") => Promise<{
                     token: string;
                     workerId: string;
                 }>;
             };
         };
         items: {
-            create: (gameId: string, slug: string, itemData: Omit<{
-                id?: string | undefined;
-                slug: string;
-                gameId?: string | null | undefined;
-                displayName: string;
-                description?: string | null | undefined;
-                type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
-                isPlaceable?: boolean | undefined;
-                imageUrl?: string | null | undefined;
-                metadata?: Record<string, unknown> | undefined;
-                createdAt?: Date | undefined;
-            }, "gameId" | "slug">) => Promise<{
-                createdAt: Date;
-                description: string | null;
-                displayName: string;
-                gameId: string | null;
-                id: string;
-                imageUrl: string | null;
-                isPlaceable: boolean;
-                metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-            }>;
-            update: (gameId: string, itemId: string, updates: {
-                slug?: string | undefined;
-                gameId?: string | null | undefined;
-                displayName?: string | undefined;
-                description?: string | null | undefined;
-                type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
-                isPlaceable?: boolean | undefined;
-                imageUrl?: string | null | undefined;
-                metadata?: Record<string, unknown> | undefined;
-            }) => Promise<{
-                createdAt: Date;
-                description: string | null;
-                displayName: string;
-                gameId: string | null;
-                id: string;
-                imageUrl: string | null;
-                isPlaceable: boolean;
-                metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-            }>;
-            list: (gameId: string) => Promise<{
-                createdAt: Date;
-                description: string | null;
-                displayName: string;
-                gameId: string | null;
-                id: string;
-                imageUrl: string | null;
-                isPlaceable: boolean;
-                metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-            }[]>;
-            get: (gameId: string, slug: string) => Promise<{
-                createdAt: Date;
-                description: string | null;
-                displayName: string;
-                gameId: string | null;
-                id: string;
-                imageUrl: string | null;
-                isPlaceable: boolean;
-                metadata: unknown;
-                slug: string;
-                type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-            }>;
+            create: (gameId: string, slug: string, itemData: Omit<InsertItemInput, "slug" | "gameId">) => Promise<ItemRow>;
+            update: (gameId: string, itemId: string, updates: UpdateItemInput) => Promise<ItemRow>;
+            list: (gameId: string) => Promise<Array<ItemRow>>;
+            get: (gameId: string, slug: string) => Promise<ItemRow>;
             delete: (gameId: string, itemId: string) => Promise<void>;
             shop: {
-                create: (gameId: string, itemId: string, listingData: Omit<{
-                    id?: string | undefined;
-                    itemId: string;
-                    currencyId: string;
-                    price: number;
-                    sellBackPercentage?: number | null | undefined;
-                    stock?: number | null | undefined;
-                    isActive: boolean;
-                    availableFrom?: Date | null | undefined;
-                    availableUntil?: Date | null | undefined;
-                    createdAt?: Date | undefined;
-                    updatedAt?: Date | null | undefined;
-                }, "itemId">) => Promise<{
-                    availableFrom: Date | null;
-                    availableUntil: Date | null;
-                    createdAt: Date;
-                    currencyId: string;
-                    id: string;
-                    isActive: boolean;
-                    itemId: string;
-                    price: number;
-                    sellBackPercentage: number | null;
-                    stock: number | null;
-                    updatedAt: Date | null;
-                }>;
-                get: (gameId: string, itemId: string) => Promise<{
-                    availableFrom: Date | null;
-                    availableUntil: Date | null;
-                    createdAt: Date;
-                    currencyId: string;
-                    id: string;
-                    isActive: boolean;
-                    itemId: string;
-                    price: number;
-                    sellBackPercentage: number | null;
-                    stock: number | null;
-                    updatedAt: Date | null;
-                } | null>;
-                update: (gameId: string, itemId: string, updates: {
-                    id?: string | undefined;
-                    itemId?: string | undefined;
-                    currencyId?: string | undefined;
-                    price?: number | undefined;
-                    sellBackPercentage?: number | null | undefined;
-                    stock?: number | null | undefined;
-                    isActive?: boolean | undefined;
-                    availableFrom?: Date | null | undefined;
-                    availableUntil?: Date | null | undefined;
-                    createdAt?: Date | undefined;
-                    updatedAt?: Date | null | undefined;
-                }) => Promise<{
-                    availableFrom: Date | null;
-                    availableUntil: Date | null;
-                    createdAt: Date;
-                    currencyId: string;
-                    id: string;
-                    isActive: boolean;
-                    itemId: string;
-                    price: number;
-                    sellBackPercentage: number | null;
-                    stock: number | null;
-                    updatedAt: Date | null;
-                }>;
+                create: (gameId: string, itemId: string, listingData: Omit<InsertShopListingInput, "itemId">) => Promise<ShopListingRow>;
+                get: (gameId: string, itemId: string) => Promise<ShopListingRow | null>;
+                update: (gameId: string, itemId: string, updates: UpdateShopListingInput) => Promise<ShopListingRow>;
                 delete: (gameId: string, itemId: string) => Promise<void>;
-                list: (gameId: string) => Promise<({
-                    availableFrom: Date | null;
-                    availableUntil: Date | null;
-                    createdAt: Date;
-                    currencyId: string;
-                    id: string;
-                    isActive: boolean;
-                    itemId: string;
-                    price: number;
-                    sellBackPercentage: number | null;
-                    stock: number | null;
-                    updatedAt: Date | null;
-                } & {
-                    item: {
-                        createdAt: Date;
-                        description: string | null;
-                        displayName: string;
-                        gameId: string | null;
-                        id: string;
-                        imageUrl: string | null;
-                        isPlaceable: boolean;
-                        metadata: unknown;
-                        slug: string;
-                        type: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
-                    };
-                })[]>;
+                list: (gameId: string) => Promise<Array<ShopListingRow & {
+                    item: ItemRow;
+                }>>;
             };
         };
     };
@@ -7259,21 +7053,21 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `getGameToken(gameId)` - Get short-lived game auth token
      */
     games: {
-        fetch: (gameIdOrSlug: string, options?: TTLCacheConfig | undefined) => Promise<FetchedGame>;
-        list: (options?: TTLCacheConfig | undefined) => Promise<Game[]>;
+        fetch: (gameIdOrSlug: string, options?: TTLCacheConfig) => Promise<FetchedGame>;
+        list: (options?: TTLCacheConfig) => Promise<Array<Game>>;
         getSubjects: () => Promise<Record<string, string | null>>;
-        startSession: (gameId?: string | undefined) => Promise<StartSessionResponse>;
-        endSession: (sessionId: string, gameId?: string | undefined) => Promise<void>;
+        startSession: (gameId?: string) => Promise<StartSessionResponse>;
+        endSession: (sessionId: string, gameId?: string) => Promise<void>;
         token: {
             create: (gameId: string, options?: {
-                apply?: boolean | undefined;
-            } | undefined) => Promise<GameTokenResponse>;
+                apply?: boolean;
+            }) => Promise<GameTokenResponse>;
         };
         leaderboard: {
             get: (gameId: string, options?: {
-                limit?: number | undefined;
-                offset?: number | undefined;
-            } | undefined) => Promise<LeaderboardEntry[]>;
+                limit?: number;
+                offset?: number;
+            }) => Promise<LeaderboardEntry[]>;
         };
     };
     /**
@@ -7282,34 +7076,20 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `update(config)` - Update avatar appearance
      */
     character: {
-        get: (userId?: string | undefined) => Promise<PlayerCharacterRow | null>;
+        get: (userId?: string) => Promise<PlayerCharacterRow | null>;
         create: (characterData: CreateCharacterData) => Promise<PlayerCharacterRow>;
         update: (updates: UpdateCharacterData) => Promise<PlayerCharacterRow>;
         components: {
-            list: (options?: (CharacterComponentsOptions & TTLCacheConfig) | undefined) => Promise<CharacterComponentWithSpriteUrl[]>;
-            clearCache: (key?: string | undefined) => void;
+            list: (options?: CharacterComponentsOptions & TTLCacheConfig) => Promise<CharacterComponentWithSpriteUrl[]>;
+            clearCache: (key?: string) => void;
             getCacheKeys: () => string[];
         };
         accessories: {
-            equip: (slot: string, componentId: string) => Promise<{
-                accessoryComponentId: string;
-                equippedAt: Date;
-                id: string;
-                playerCharacterId: string;
-                slot: string;
-                updatedAt: Date;
-            }>;
+            equip: (slot: string, componentId: string) => Promise<PlayerCharacterAccessoryRow>;
             remove: (slot: string) => Promise<{
                 success: boolean;
             }>;
-            list: () => Promise<{
-                accessoryComponentId: string;
-                equippedAt: Date;
-                id: string;
-                playerCharacterId: string;
-                slot: string;
-                updatedAt: Date;
-            }[]>;
+            list: () => Promise<PlayerCharacterAccessoryRow[]>;
         };
     };
     /**
@@ -7319,11 +7099,11 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `award(achievementId)` - Grant achievement to user
      */
     achievements: {
-        list: (options?: TTLCacheConfig | undefined) => Promise<AchievementCurrent[]>;
+        list: (options?: TTLCacheConfig) => Promise<AchievementCurrent[]>;
         history: {
             list: (queryOptions?: {
-                limit?: number | undefined;
-            } | undefined, cacheOptions?: TTLCacheConfig | undefined) => Promise<AchievementHistoryEntry[]>;
+                limit?: number;
+            }, cacheOptions?: TTLCacheConfig) => Promise<AchievementHistoryEntry[]>;
         };
         progress: {
             submit: (achievementId: string) => Promise<AchievementProgressResponse>;
@@ -7335,7 +7115,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `submit(leaderboardId, score)` - Submit score to leaderboard
      */
     leaderboard: {
-        fetch: (options?: LeaderboardOptions | undefined) => Promise<GameLeaderboardEntry[]>;
+        fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
         getUserRank: (gameId: string, userId: string) => Promise<UserRank | null>;
     };
     /**
@@ -7344,36 +7124,16 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `addXp(amount)` - Award XP to user
      */
     levels: {
-        get: () => Promise<{
-            createdAt: Date;
-            currentLevel: number;
-            currentXp: number;
-            lastLevelUpAt: Date | null;
-            totalXP: number;
-            updatedAt: Date | null;
-            userId: string;
-        }>;
-        progress: (options?: CooldownCacheConfig | undefined) => Promise<{
+        get: () => Promise<UserLevelRow>;
+        progress: (options?: CooldownCacheConfig) => Promise<{
             level: number;
             currentXp: number;
             xpToNextLevel: number;
             totalXP: number;
         }>;
         config: {
-            list: () => Promise<{
-                createdAt: Date;
-                creditsReward: number;
-                id: string;
-                level: number;
-                xpRequired: number;
-            }[]>;
-            get: (level: number) => Promise<{
-                createdAt: Date;
-                creditsReward: number;
-                id: string;
-                level: number;
-                xpRequired: number;
-            } | null>;
+            list: () => Promise<LevelConfigRow[]>;
+            get: (level: number) => Promise<LevelConfigRow | null>;
         };
     };
     /**
@@ -7391,108 +7151,23 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      */
     notifications: {
         list: (queryOptions?: {
-            status?: NotificationStatus | undefined;
-            type?: NotificationType | undefined;
-            limit?: number | undefined;
-            offset?: number | undefined;
-        } | undefined, cacheOptions?: TTLCacheConfig | undefined) => Promise<{
-            clickUrl: string | null;
-            clickedAt: Date | null;
-            createdAt: Date;
-            data: unknown;
-            deliveredAt: Date | null;
-            expiresAt: Date | null;
-            id: string;
-            message: string;
-            metadata: unknown;
-            method: string | null;
-            priority: "high" | "low" | "normal" | "urgent";
-            seenAt: Date | null;
-            status: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
-            title: string;
-            type: string;
-            userId: string;
-        }[]>;
-        markAsSeen: (notificationId: string) => Promise<{
-            clickUrl: string | null;
-            clickedAt: Date | null;
-            createdAt: Date;
-            data: unknown;
-            deliveredAt: Date | null;
-            expiresAt: Date | null;
-            id: string;
-            message: string;
-            metadata: unknown;
-            method: string | null;
-            priority: "high" | "low" | "normal" | "urgent";
-            seenAt: Date | null;
-            status: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
-            title: string;
-            type: string;
-            userId: string;
-        }>;
-        markAsClicked: (notificationId: string) => Promise<{
-            clickUrl: string | null;
-            clickedAt: Date | null;
-            createdAt: Date;
-            data: unknown;
-            deliveredAt: Date | null;
-            expiresAt: Date | null;
-            id: string;
-            message: string;
-            metadata: unknown;
-            method: string | null;
-            priority: "high" | "low" | "normal" | "urgent";
-            seenAt: Date | null;
-            status: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
-            title: string;
-            type: string;
-            userId: string;
-        }>;
-        dismiss: (notificationId: string) => Promise<{
-            clickUrl: string | null;
-            clickedAt: Date | null;
-            createdAt: Date;
-            data: unknown;
-            deliveredAt: Date | null;
-            expiresAt: Date | null;
-            id: string;
-            message: string;
-            metadata: unknown;
-            method: string | null;
-            priority: "high" | "low" | "normal" | "urgent";
-            seenAt: Date | null;
-            status: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
-            title: string;
-            type: string;
-            userId: string;
-        }>;
-        markAsDelivered: (notificationId: string, method?: NotificationMethod) => Promise<{
-            clickUrl: string | null;
-            clickedAt: Date | null;
-            createdAt: Date;
-            data: unknown;
-            deliveredAt: Date | null;
-            expiresAt: Date | null;
-            id: string;
-            message: string;
-            metadata: unknown;
-            method: string | null;
-            priority: "high" | "low" | "normal" | "urgent";
-            seenAt: Date | null;
-            status: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
-            title: string;
-            type: string;
-            userId: string;
-        }>;
+            status?: NotificationStatus;
+            type?: NotificationType;
+            limit?: number;
+            offset?: number;
+        }, cacheOptions?: TTLCacheConfig) => Promise<NotificationRow[]>;
+        markAsSeen: (notificationId: string) => Promise<NotificationRow>;
+        markAsClicked: (notificationId: string) => Promise<NotificationRow>;
+        dismiss: (notificationId: string) => Promise<NotificationRow>;
+        markAsDelivered: (notificationId: string, method?: NotificationMethod) => Promise<NotificationRow>;
         deliverPending: () => Promise<{
             success: boolean;
         }>;
         stats: {
             get: (queryOptions?: {
-                from?: string | undefined;
-                to?: string | undefined;
-            } | undefined, cacheOptions?: TTLCacheConfig | undefined) => Promise<NotificationStats>;
+                from?: string;
+                to?: string;
+            }, cacheOptions?: TTLCacheConfig) => Promise<NotificationStats>;
         };
     };
     /**
@@ -7501,8 +7176,8 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `unlock(areaId)` - Unlock a new map area
      */
     maps: {
-        get: (identifier: string, options?: TTLCacheConfig | undefined) => Promise<MapData>;
-        elements: (mapId: string, options?: TTLCacheConfig | undefined) => Promise<MapElementWithGame[]>;
+        get: (identifier: string, options?: TTLCacheConfig) => Promise<MapData>;
+        elements: (mapId: string, options?: TTLCacheConfig) => Promise<MapElementWithGame[]>;
         objects: {
             list: (mapId: string) => Promise<MapObjectWithItem[]>;
             create: (mapId: string, objectData: CreateMapObjectData) => Promise<MapObjectWithItem>;
@@ -7533,10 +7208,10 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
      * - `getByUser(userId)` - Get all scores for a user
      */
     scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
         getByUser: (gameId: string, userId: string, options?: {
-            limit?: number | undefined;
-        } | undefined) => Promise<UserScore[]>;
+            limit?: number;
+        }) => Promise<UserScore[]>;
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
     };
     /**
      * TimeBack integration for user context, XP tracking, and course management.
@@ -7557,9 +7232,9 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     timeback: {
         readonly user: PlatformTimebackUser;
         populateStudent: (names?: {
-            firstName?: string | undefined;
-            lastName?: string | undefined;
-        } | undefined) => Promise<PopulateStudentResponse>;
+            firstName?: string;
+            lastName?: string;
+        }) => Promise<PopulateStudentResponse>;
         startActivity: (_metadata: ActivityData) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
@@ -7569,71 +7244,26 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             verify: (gameId: string) => Promise<TimebackVerifyAllResponse>;
             cleanup: (gameId: string) => Promise<void>;
             get: (gameId: string) => Promise<GameTimebackIntegration[]>;
-            getConfig: (gameId: string) => Promise<{
-                organization: {
-                    name: string;
-                    type: string;
-                    identifier: string;
-                };
-                course: {
-                    title: string;
-                    subjects: string[];
-                    grades: number[];
-                    courseCode: string;
-                    level: string;
-                    gradingScheme: string;
-                    metadata?: Record<string, unknown> | undefined;
-                };
-                component: {
-                    title: string;
-                    sortOrder: number;
-                    prerequisites: string[];
-                    prerequisiteCriteria: string;
-                };
-                resource: {
-                    title: string;
-                    vendorResourceId: string;
-                    vendorId: string;
-                    applicationId: string;
-                    roles: string[];
-                    importance: string;
-                    metadata: {
-                        [key: string]: unknown;
-                        type?: string | undefined;
-                        launchUrl?: string | undefined;
-                        toolProvider?: string | undefined;
-                        instructionalMethod?: string | undefined;
-                        subject?: string | undefined;
-                        grades?: number[] | undefined;
-                        language?: string | undefined;
-                        xp?: number | undefined;
-                    };
-                };
-                componentResource: {
-                    title: string;
-                    sortOrder: number;
-                    lessonType: string | null;
-                };
-            }>;
+            getConfig: (gameId: string) => Promise<TimebackSetupRequest["config"]>;
         };
         xp: {
             today: (options?: {
-                date?: string | undefined;
-                timezone?: string | undefined;
-            } | undefined) => Promise<TodayXpResponse>;
+                date?: string;
+                timezone?: string;
+            }) => Promise<TodayXpResponse>;
             total: () => Promise<TotalXpResponse>;
             history: (options?: {
-                startDate?: string | undefined;
-                endDate?: string | undefined;
-            } | undefined) => Promise<XpHistoryResponse>;
+                startDate?: string;
+                endDate?: string;
+            }) => Promise<XpHistoryResponse>;
             summary: (options?: {
-                date?: string | undefined;
-                timezone?: string | undefined;
-            } | undefined) => Promise<XpSummaryResponse>;
+                date?: string;
+                timezone?: string;
+            }) => Promise<XpSummaryResponse>;
         };
         students: {
-            get: (timebackId: string, options?: TTLCacheConfig | undefined) => Promise<PlatformTimebackUserContext>;
-            clearCache: (timebackId?: string | undefined) => void;
+            get: (timebackId: string, options?: TTLCacheConfig) => Promise<PlatformTimebackUserContext>;
+            clearCache: (timebackId?: string) => void;
         };
     };
     /** Auto-initializes a PlaycademyInternalClient with context from the environment */
@@ -7647,4 +7277,4 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
 }
 
 export { AchievementCompletionType, ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, NotificationStatus, NotificationType, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, HostedGame, 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, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, 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, XpSummaryResponse };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, 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, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, 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 };