@playcademy/sdk 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
-import * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
@@ -9,22 +7,146 @@ import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 declare class PlaycademyError extends Error {
     constructor(message: string);
 }
+/**
+ * Error codes returned by the API.
+ * These map to specific error types and HTTP status codes.
+ */
+type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'ALREADY_EXISTS' | 'GONE' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_FAILED' | 'TOO_MANY_REQUESTS' | 'RATE_LIMITED' | 'EXPIRED' | 'INTERNAL' | 'INTERNAL_ERROR' | 'NOT_IMPLEMENTED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | string;
+/**
+ * Structure of error response bodies returned by API endpoints.
+ *
+ * @example
+ * ```json
+ * {
+ *   "error": {
+ *     "code": "NOT_FOUND",
+ *     "message": "Item not found",
+ *     "details": { "identifier": "abc123" }
+ *   }
+ * }
+ * ```
+ */
+interface ErrorResponseBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * API error thrown when a request fails.
+ *
+ * Contains structured error information from the API response:
+ * - `status` - HTTP status code (e.g., 404)
+ * - `code` - API error code (e.g., "NOT_FOUND")
+ * - `message` - Human-readable error message
+ * - `details` - Optional additional error context
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.games.get('nonexistent')
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(error.status)   // 404
+ *     console.log(error.code)     // "NOT_FOUND"
+ *     console.log(error.message)  // "Game not found"
+ *     console.log(error.details)  // { identifier: "nonexistent" }
+ *   }
+ * }
+ * ```
+ */
 declare class ApiError extends Error {
-    status: number;
-    details: unknown;
-    constructor(status: number, message: string, details: unknown);
+    readonly status: number;
+    /**
+     * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
+     * Use this for programmatic error handling.
+     */
+    readonly code: ApiErrorCode;
+    /**
+     * Additional error context from the API.
+     * Structure varies by error type (e.g., validation errors include field details).
+     */
+    readonly details: unknown;
+    /**
+     * Raw response body for debugging.
+     * @internal
+     */
+    readonly rawBody: unknown;
+    constructor(
+    /** HTTP status code */
+    status: number, 
+    /** API error code */
+    code: ApiErrorCode, 
+    /** Human-readable error message */
+    message: string, 
+    /** Additional error context */
+    details?: unknown, 
+    /** Raw response body */
+    rawBody?: unknown);
+    /**
+     * Create an ApiError from an HTTP response.
+     * Parses the structured error response from the API.
+     *
+     * @internal
+     */
+    static fromResponse(status: number, statusText: string, body: unknown): ApiError;
+    /**
+     * Check if this is a specific error type.
+     *
+     * @example
+     * ```typescript
+     * if (error.is('NOT_FOUND')) {
+     *   // Handle not found
+     * } else if (error.is('VALIDATION_FAILED')) {
+     *   // Handle validation error
+     * }
+     * ```
+     */
+    is(code: ApiErrorCode): boolean;
+    /**
+     * Check if this is a client error (4xx).
+     */
+    isClientError(): boolean;
+    /**
+     * Check if this is a server error (5xx).
+     */
+    isServerError(): boolean;
+    /**
+     * Check if this error is retryable.
+     * Server errors and rate limits are typically retryable.
+     */
+    isRetryable(): boolean;
 }
 /**
- * Extract useful error information from an API error
- * Useful for displaying errors to users in a friendly way
+ * Extracted error information for display purposes.
  */
 interface ApiErrorInfo {
+    /** HTTP status code */
     status: number;
-    statusText: string;
-    error?: string;
-    message?: string;
+    /** API error code */
+    code: ApiErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error context */
     details?: unknown;
 }
+/**
+ * Extract useful error information from an API error.
+ * Useful for displaying errors to users in a friendly way.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.shop.purchase(itemId)
+ * } catch (error) {
+ *   const info = extractApiErrorInfo(error)
+ *   if (info) {
+ *     showToast(`Error: ${info.message}`)
+ *   }
+ * }
+ * ```
+ */
 declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
 
 /**
@@ -256,217 +378,151 @@ declare function parseOAuthState(state: string): {
     data?: Record<string, string>;
 };
 
-declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "user";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: true;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        name: drizzle_orm_pg_core.PgColumn<{
-            name: "name";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        username: drizzle_orm_pg_core.PgColumn<{
-            name: "username";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        email: drizzle_orm_pg_core.PgColumn<{
-            name: "email";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        timebackId: drizzle_orm_pg_core.PgColumn<{
-            name: "timeback_id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        emailVerified: drizzle_orm_pg_core.PgColumn<{
-            name: "email_verified";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        image: drizzle_orm_pg_core.PgColumn<{
-            name: "image";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        role: drizzle_orm_pg_core.PgColumn<{
-            name: "role";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "admin" | "player" | "developer";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["admin", "player", "developer"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        developerStatus: drizzle_orm_pg_core.PgColumn<{
-            name: "developer_status";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "none" | "pending" | "approved";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["none", "pending", "approved"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        characterCreated: drizzle_orm_pg_core.PgColumn<{
-            name: "character_created";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        createdAt: drizzle_orm_pg_core.PgColumn<{
-            name: "created_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * User Types
+ *
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
+ */
+type UserRoleEnumType = 'admin' | 'player' | 'developer';
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface UserEnrollment {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    enrollments: UserEnrollment[];
+}
+/**
+ * OpenID Connect UserInfo claims (NOT a database row).
+ */
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+/**
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ */
+interface AuthenticatedUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    username: string | null;
+    role: UserRoleEnumType;
+    developerStatus: DeveloperStatusEnumType;
+    characterCreated: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    hasTimebackAccount: boolean;
+    timeback?: UserTimebackData;
+}
+
+/**
+ * Valid Caliper subject values.
+ * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ */
+type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+
+/**
+ * TimeBack Client SDK DTOs
+ *
+ * Data transfer objects for the TimeBack client SDK including
+ * progress tracking, session management, and activity completion.
+ *
+ * Note: TimebackClientConfig lives in @playcademy/timeback as it's
+ * SDK configuration, not a DTO.
+ *
+ * @module types/timeback/client
+ */
+
+/**
+ * Activity data for ending an activity
+ */
+interface ActivityData {
+    /** Unique activity identifier (required) */
+    activityId: string;
+    /** Grade level for this activity (required for multi-grade course routing) */
+    grade: number;
+    /** Subject area (required for multi-grade course routing) */
+    subject: CaliperSubject;
+    /** Activity display name (optional) */
+    activityName?: string;
+    /** Course identifier (auto-filled from config if not provided) */
+    courseId?: string;
+    /** Course display name (auto-filled from config if not provided) */
+    courseName?: string;
+    /** Student email address (optional) */
+    studentEmail?: string;
+    /** Application name for Caliper events (defaults to 'Game') */
+    appName?: string;
+    /** Sensor URL for Caliper events (defaults to baseUrl) */
+    sensorUrl?: string;
+}
+/**
+ * Score data with optional XP override for ending an activity
+ */
+interface EndActivityScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
+    /** Optional XP override - bypasses automatic XP calculation */
+    xpAwarded?: number;
+    /** Number of learning units mastered */
+    masteredUnits?: number;
+}
+
+/**
+ * TimeBack API Request/Response Types
+ *
+ * Types for TimeBack API endpoints including XP tracking,
+ * setup, verification, and activity completion.
+ *
+ * @module types/timeback/api
+ */
+
+interface EndActivityResponse {
+    status: 'ok';
+    courseId: string;
+    xpAwarded: number;
+    masteredUnits?: number;
+    pctCompleteApp?: number;
+    scoreStatus?: string;
+    inProgress?: string;
+}
+
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
     schema: undefined;
@@ -561,7 +617,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "items";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -736,50 +792,11 @@ declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
-type Item = typeof items.$inferSelect;
-type InventoryItem = typeof inventoryItems.$inferSelect;
 
-type User = typeof users.$inferSelect;
-/**
- * User data with authentication provider information.
- * Returned by the /users/me endpoint with additional auth context.
- */
-type AuthenticatedUser = User & {
-    /** Whether the user authenticated via Timeback SSO */
-    hasTimebackAccount: boolean;
-};
-/**
- * Basic user information in the shape of the claims from identity providers
- */
-interface UserInfo {
-    /** Unique user identifier (sub claim from JWT) */
-    sub: string;
-    /** User's email address */
-    email: string;
-    /** User's display name */
-    name: string;
-    /** Whether the email has been verified */
-    email_verified: boolean;
-    /** Optional given name (first name) */
-    given_name?: string;
-    /** Optional family name (last name) */
-    family_name?: string;
-    /** TimeBack student ID (if user has TimeBack integration) */
-    timeback_id?: string;
-    /** Additional user attributes from the identity provider */
-    [key: string]: unknown;
-}
-type InventoryItemWithItem = Omit<InventoryItem, 'itemId'> & {
-    item: Item;
-};
-type EndActivityResponse = {
-    status: 'ok';
-    courseId: string;
-    xpAwarded: number;
-    masteredUnits?: number;
-    pctCompleteApp?: number;
-    scoreStatus?: string;
-    inProgress?: string;
+type ItemRow = typeof items.$inferSelect;
+type InventoryItemRow = typeof inventoryItems.$inferSelect;
+type InventoryItemWithItem = InventoryItemRow & {
+    item: ItemRow;
 };
 
 /**
@@ -847,208 +864,103 @@ declare function init<T extends PlaycademyClient = PlaycademyClient>(this: new (
  */
 declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
 
-/** Permitted HTTP verbs */
-type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * @fileoverview Authentication Strategy Pattern
+ *
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
+ */
+
+/**
+ * Base interface for authentication strategies
+ */
+interface AuthStrategy {
+    /** Get the token value */
+    getToken(): string | null;
+    /** Get the token type */
+    getType(): TokenType;
+    /** Get authentication headers for a request */
+    getHeaders(): Record<string, string>;
+}
 
 /**
- * Main Playcademy SDK client for interacting with the platform API.
- * Provides namespaced access to all platform features including games, users, inventory, and more.
+ * Base Playcademy SDK client with shared infrastructure.
+ * Provides authentication, HTTP requests, events, connection monitoring,
+ * and fundamental namespaces used by all clients.
+ *
+ * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
  */
-declare class PlaycademyClient {
+declare abstract class PlaycademyBaseClient {
     baseUrl: string;
     gameUrl?: string;
-    private authStrategy;
-    private gameId?;
-    private config;
-    private listeners;
-    private internalClientSessionId?;
-    private authContext?;
-    private initPayload?;
-    private connectionManager?;
+    protected authStrategy: AuthStrategy;
+    protected gameId?: string;
+    protected config: Partial<ClientConfig>;
+    protected listeners: EventListeners;
+    protected internalClientSessionId?: string;
+    protected authContext?: {
+        isInIframe: boolean;
+    };
+    protected initPayload?: InitPayload;
+    protected connectionManager?: ConnectionManager;
     /**
      * Internal session manager for automatic session lifecycle.
-     *
-     * This manager handles starting and ending game sessions automatically.
-     * Game developers don't need to call these methods directly - they're managed
-     * by the SDK during initialization and cleanup.
-     *
      * @private
      * @internal
      */
-    private _sessionManager;
-    /**
-     * Creates a new PlaycademyClient instance.
-     *
-     * @param config - Optional configuration object
-     * @param config.baseUrl - Base URL (e.g., 'https://hub.playcademy.net' or '/'). SDK automatically appends /api
-     * @param config.token - Authentication token
-     * @param config.tokenType - Optional token type (auto-detected if not provided)
-     * @param config.gameId - Game ID for automatic session management
-     * @param config.autoStartSession - Automatically start a game session?
-     */
+    protected _sessionManager: {
+        startSession: (gameId: string) => Promise<{
+            sessionId: string;
+        }>;
+        endSession: (sessionId: string, gameId: string) => Promise<void>;
+    };
     constructor(config?: Partial<ClientConfig>);
     /**
      * Gets the effective base URL for API requests.
-     * Converts relative URLs to absolute URLs in browser environments.
-     * Note: baseUrl already includes /api suffix from constructor.
-     *
-     * @returns The complete base URL for API requests (with /api suffix)
      */
     getBaseUrl(): string;
     /**
      * Gets the effective game backend URL for integration requests.
-     * Throws if gameUrl is not configured.
-     *
-     * @returns The complete game backend URL for API requests (with /api suffix)
-     * @throws PlaycademyError if gameUrl is not set
      */
-    private getGameBackendUrl;
+    protected getGameBackendUrl(): string;
     /**
      * Simple ping method for testing connectivity.
-     *
-     * @returns 'pong' string response
      */
     ping(): string;
     /**
      * Sets the authentication token for API requests.
-     * Emits an 'authChange' event when the token changes.
-     *
-     * @param token - The authentication token, or null to clear
-     * @param tokenType - Optional token type (auto-detected if not provided)
      */
     setToken(token: string | null, tokenType?: TokenType): void;
     /**
      * Gets the current token type.
-     *
-     * @returns The token type
      */
     getTokenType(): TokenType;
     /**
      * Gets the current authentication token.
-     *
-     * @returns The current token or null if not authenticated
-     *
-     * @example
-     * ```typescript
-     * // Send token to your backend for verification
-     * const token = client.getToken()
-     * const response = await fetch('/api/auth/playcademy', {
-     *     method: 'POST',
-     *     body: JSON.stringify({ gameToken: token })
-     * })
-     * ```
      */
     getToken(): string | null;
     /**
-     * Checks if the client has a valid API token for making Playcademy API requests.
-     *
-     * For games (iframe context): Checks if we have a valid token from the parent.
-     * For Cademy (standalone): Checks if we have a token from better-auth.
-     *
-     * Note: This checks for API authentication, not whether a user has linked
-     * their identity via OAuth.
-     *
-     * @returns true if API token exists, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (client.isAuthenticated()) {
-     *     // Can make API calls
-     *     const games = await client.games.list()
-     * } else {
-     *     console.error('No API token available')
-     * }
-     * ```
+     * Checks if the client has a valid API token.
      */
     isAuthenticated(): boolean;
     /**
      * Registers a callback to be called when authentication state changes.
-     *
-     * @param callback - Function to call when auth state changes
      */
     onAuthChange(callback: (token: string | null) => void): void;
     /**
      * Registers a callback to be called when connection issues are detected.
-     *
-     * This is a convenience method that filters connection change events to only
-     * fire when the connection degrades (offline or degraded states). Use this
-     * when you want to handle disconnects without being notified of recoveries.
-     *
-     * For all connection state changes, use `client.on('connectionChange', ...)` instead.
-     *
-     * @param callback - Function to call when connection state changes to offline or degraded
-     * @returns Cleanup function to unregister the callback
-     *
-     * @example
-     * ```typescript
-     * const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
-     *   console.log(`Connection ${state}: ${reason}`)
-     *
-     *   if (state === 'offline') {
-     *     // Save state and return to game lobby
-     *     displayAlert?.('Connection lost. Your progress has been saved.', { type: 'error' })
-     *     saveGameState()
-     *     returnToLobby()
-     *   } else if (state === 'degraded') {
-     *     displayAlert?.('Slow connection detected.', { type: 'warning' })
-     *   }
-     * })
-     *
-     * // Later: cleanup() to unregister
-     * ```
-     *
-     * @see Connection monitoring documentation in SDK Browser docs for detailed usage examples
-     * @see {@link ConnectionManager.onDisconnect} for the underlying implementation
      */
     onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
     /**
      * Gets the current connection state.
-     *
-     * Returns the last known connection state without triggering a new check.
-     * Use `checkConnection()` to force an immediate verification.
-     *
-     * @returns Current connection state ('online', 'offline', 'degraded') or 'unknown' if monitoring is disabled
-     *
-     * @example
-     * ```typescript
-     * const state = client.getConnectionState()
-     * if (state === 'offline') {
-     *   console.log('No connection available')
-     * }
-     * ```
-     *
-     * @see {@link checkConnection} to trigger an immediate connection check
-     * @see {@link ConnectionManager.getState} for the underlying implementation
      */
     getConnectionState(): ConnectionState | 'unknown';
     /**
      * Manually triggers a connection check immediately.
-     *
-     * Forces a heartbeat ping to verify connectivity right now, bypassing the normal
-     * interval. Useful when you need to verify connection status before a critical
-     * operation (e.g., saving important game state).
-     *
-     * @returns Promise resolving to the current connection state after verification
-     *
-     * @example
-     * ```typescript
-     * // Check before critical operation
-     * const state = await client.checkConnection()
-     * if (state !== 'online') {
-     *   alert('Please check your internet connection before saving')
-     *   return
-     * }
-     *
-     * await client.games.saveState(importantData)
-     * ```
-     *
-     * @see {@link getConnectionState} to get the last known state without checking
-     * @see {@link ConnectionManager.checkNow} for the underlying implementation
      */
     checkConnection(): Promise<ConnectionState | 'unknown'>;
     /**
      * Sets the authentication context for the client.
-     * This is called during initialization to store environment info.
      * @internal
      */
     _setAuthContext(context: {
@@ -1056,28 +968,14 @@ declare class PlaycademyClient {
     }): void;
     /**
      * Registers an event listener for client events.
-     *
-     * @param event - The event type to listen for
-     * @param callback - Function to call when the event is emitted
      */
     on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
     /**
      * Emits an event to all registered listeners.
-     *
-     * @param event - The event type to emit
-     * @param payload - The event payload
      */
-    private emit;
+    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
     /**
      * Makes an authenticated HTTP request to the platform API.
-     *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param options - Optional request configuration
-     * @param options.body - Request body
-     * @param options.headers - Additional headers
-     * @param options.raw - If true, returns raw Response instead of parsing
-     * @returns Promise resolving to the response data or raw Response
      */
     protected request<T>(path: string, method: Method, options?: {
         body?: unknown;
@@ -1086,53 +984,65 @@ declare class PlaycademyClient {
     }): Promise<T>;
     /**
      * Makes an authenticated HTTP request to the game's backend Worker.
-     * Uses gameUrl if set, otherwise falls back to platform API.
-     *
-     * @param path - API endpoint path
-     * @param method - HTTP method
-     * @param body - Request body (optional)
-     * @param headers - Additional headers (optional)
-     * @param raw - If true, returns raw Response instead of parsing (optional)
-     * @returns Promise resolving to the response data or raw Response
      */
     protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, raw?: boolean): Promise<T>;
     /**
      * Ensures a gameId is available, throwing an error if not.
-     *
-     * @returns The gameId
-     * @throws PlaycademyError if no gameId is configured
      */
-    private _ensureGameId;
+    protected _ensureGameId(): string;
     /**
      * Detects and sets the authentication context (iframe vs standalone).
-     * Safe to call in any environment - isInIframe handles browser detection.
      */
     private _detectAuthContext;
     /**
      * Initializes connection monitoring if enabled.
-     * Safe to call in any environment - only runs in browser.
      */
     private _initializeConnectionMonitor;
+    private _initializeInternalSession;
     /**
-     * Initializes an internal game session for automatic session management.
-     * Only starts a session if:
-     * 1. A gameId is configured
-     * 2. No session already exists
-     * 3. autoStartSession is enabled (defaults to false)
+     * Current user data and inventory management.
+     * - `me()` - Get authenticated user profile
+     * - `inventory.get()` - List user's items
+     * - `inventory.add(slug, qty)` - Award items to user
+     */
+    users: {
+        me: () => Promise<AuthenticatedUser>;
+        inventory: {
+            get: () => Promise<InventoryItemWithItem[]>;
+            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+            quantity: (identifier: string) => Promise<number>;
+            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
+        };
+    };
+}
+
+/**
+ * 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
      */
-    private _initializeInternalSession;
-    /** Identity provider connection methods (connect external accounts) */
     identity: {
         connect: (options: AuthOptions) => Promise<AuthResult>;
         _getContext: () => {
             isInIframe: boolean;
         };
     };
-    /** Runtime methods (getGameToken, exit) */
+    /**
+     * 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;
-        }) => Promise<GameTokenResponse>;
+            apply?: boolean | undefined;
+        } | undefined) => Promise<GameTokenResponse>;
         exit: () => Promise<void>;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -1156,57 +1066,73 @@ declare class PlaycademyClient {
         getListenerCounts: () => Record<string, number>;
         assets: {
             url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit) => Promise<Response>;
+            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>;
         };
     };
-    /** User methods (me, inventory management) */
-    users: {
-        me: () => Promise<AuthenticatedUser>;
-        inventory: {
-            get: () => Promise<InventoryItemWithItem[]>;
-            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            quantity: (identifier: string) => Promise<number>;
-            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-        };
-    };
-    /** TimeBack XP methods (today, total, history) */
+    /**
+     * 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: {
-        startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
+        readonly user: TimebackUser;
+        startActivity: (metadata: ActivityData) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
-        endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
+        endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
     };
-    /** Credits methods (credits management) */
+    /**
+     * 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>;
     };
-    /** Platform-wide scores methods (submit, getUserScores) */
+    /**
+     * Game score submission and leaderboards.
+     * - `submit(gameId, score, metadata?)` - Record a game score
+     */
     scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
     };
-    /** Realtime methods (token) */
+    /**
+     * Realtime multiplayer authentication.
+     * - `getToken()` - Get token for WebSocket/realtime connections
+     */
     realtime: {
         token: {
             get: () => Promise<RealtimeTokenResponse>;
         };
-        open(channel?: string, url?: string): Promise<_playcademy_realtime_server_types.RealtimeChannel>;
     };
-    /** Backend methods for calling custom game API routes */
+    /**
+     * 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>): 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>;
+        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 */
@@ -1219,9 +1145,70 @@ declare class PlaycademyClient {
     };
 }
 
+/**
+ * Type definitions for the game timeback namespace.
+ *
+ * SDK-specific types like TimebackInitContext that wrap the core types
+ * from @playcademy/types/user (which are re-exported via types/data.ts).
+ */
+
+/**
+ * A TimeBack enrollment for the current game session.
+ * Alias for UserEnrollment without the optional gameId.
+ */
+type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
+/**
+ * A TimeBack organization (school/district) for the current user.
+ * Alias for UserOrganization.
+ */
+type TimebackOrganization = UserOrganization;
+/**
+ * TimeBack context passed during game initialization.
+ * This is sent from the platform (cademy) to the game iframe via postMessage.
+ */
+interface TimebackInitContext {
+    /** User's TimeBack ID */
+    id: string;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's enrollments for this game (one per grade/subject combo) */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
+}
+/**
+ * TimeBack user context with current data (may be stale from init).
+ * Use `fetch()` to get fresh data from the server.
+ */
+interface TimebackUserContext {
+    /** User's TimeBack ID */
+    id: string | undefined;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole | undefined;
+    /** User's enrollments for this game */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
+}
+/**
+ * TimeBack user object with both cached getters and fetch method.
+ */
+interface TimebackUser extends TimebackUserContext {
+    /**
+     * Fetch TimeBack data from the server (cached for 5 min).
+     * Updates the cached values so subsequent property access returns fresh data.
+     * @param options - Cache options (pass { force: true } to bypass cache)
+     * @returns Promise resolving to fresh user context
+     */
+    fetch(options?: {
+        force?: boolean;
+    }): Promise<TimebackUserContext>;
+}
+
 /**
  * Core client configuration and lifecycle types
  */
+
 type TokenType = 'session' | 'apiKey' | 'gameJwt';
 interface ClientConfig {
     baseUrl: string;
@@ -1254,6 +1241,20 @@ interface DisconnectContext {
         duration?: number;
     }) => void;
 }
+interface InitPayload {
+    /** Hub API base URL */
+    baseUrl: string;
+    /** Game deployment URL (serves both frontend assets and backend API) */
+    gameUrl?: string;
+    /** Short-lived game token */
+    token: string;
+    /** Game ID */
+    gameId: string;
+    /** Realtime WebSocket URL */
+    realtimeUrl?: string;
+    /** Timeback context (if user has a Timeback account) */
+    timeback?: TimebackInitContext;
+}
 type GameContextPayload = {
     token: string;
     baseUrl: string;
@@ -1261,6 +1262,9 @@ type GameContextPayload = {
     gameId: string;
     forwardKeys?: string[];
 };
+type EventListeners = {
+    [E in keyof ClientEvents]?: Array<(payload: ClientEvents[E]) => void>;
+};
 interface ClientEvents {
     authChange: {
         token: string | null;
@@ -1456,6 +1460,8 @@ type DevUploadEvent = {
 } | {
     type: 'finalizeStatus';
     message: string;
+} | {
+    type: 'complete';
 } | {
     type: 'close';
 };
@@ -2203,4 +2209,4 @@ declare class PlaycademyMessaging {
 declare const messaging: PlaycademyMessaging;
 
 export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload };
+export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody };