@playcademy/sdk 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-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 * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /**
@@ -740,13 +739,66 @@ type Item = typeof items.$inferSelect;
 type InventoryItem = typeof inventoryItems.$inferSelect;
 
 type User = typeof users.$inferSelect;
+/**
+ * TimeBack enrollment information for a game.
+ */
+type UserEnrollment = {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+};
+/**
+ * TimeBack user role (matches OneRoster spec).
+ */
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+/**
+ * Organization type (matches OneRoster spec).
+ */
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * TimeBack organization data for a user.
+ * Represents schools, districts, or other educational organizations.
+ */
+type UserOrganization = {
+    /** Organization ID (OneRoster sourcedId) */
+    id: string;
+    /** Organization name */
+    name: string | null;
+    /** Organization type (school, district, etc.) */
+    type: TimebackOrgType | string;
+    /** Whether this is the user's primary organization */
+    isPrimary: boolean;
+};
+/**
+ * TimeBack student profile (role + organizations).
+ * Subset of UserTimebackData returned by OneRoster API.
+ */
+type TimebackStudentProfile = {
+    /** User's primary role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's organizations (schools/districts) */
+    organizations: UserOrganization[];
+};
+/**
+ * TimeBack-related data for a user.
+ */
+type UserTimebackData = TimebackStudentProfile & {
+    /** User's TimeBack ID (sourcedId) */
+    id: string;
+    /** Course enrollments */
+    enrollments: UserEnrollment[];
+};
 /**
  * User data with authentication provider information.
  * Returned by the /users/me endpoint with additional auth context.
  */
-type AuthenticatedUser = User & {
+type AuthenticatedUser = Omit<User, 'timebackId'> & {
     /** Whether the user authenticated via Timeback SSO */
     hasTimebackAccount: boolean;
+    /** TimeBack data (id, role, enrollments, organizations) - only present if user has a timeback account */
+    timeback?: UserTimebackData;
 };
 /**
  * Basic user information in the shape of the claims from identity providers
@@ -782,6 +834,9 @@ type EndActivityResponse = {
     inProgress?: string;
 };
 
+/** Permitted HTTP verbs */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
 /**
  * Auto-initializes a PlaycademyClient with context from the environment.
  * Works in both iframe mode (production/development) and standalone mode (local dev).
@@ -847,208 +902,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 +1006,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,49 +1022,64 @@ 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;
     /**
      * 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)
      */
     private _initializeInternalSession;
-    /** Identity provider connection methods (connect external accounts) */
+    /**
+     * 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
+     */
     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;
@@ -1163,42 +1114,58 @@ declare class PlaycademyClient {
             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: {
+        readonly user: TimebackUser;
         startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: _playcademy_timeback_types.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>;
     };
-    /** 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>;
@@ -1219,9 +1186,70 @@ declare class PlaycademyClient {
     };
 }
 
+/**
+ * Type definitions for the game timeback namespace.
+ *
+ * Re-exports core types from @playcademy/data for SDK consumers,
+ * plus SDK-specific types like TimebackInitContext.
+ */
+
+/**
+ * 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 +1282,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 +1303,9 @@ type GameContextPayload = {
     gameId: string;
     forwardKeys?: string[];
 };
+type EventListeners = {
+    [E in keyof ClientEvents]?: Array<(payload: ClientEvents[E]) => void>;
+};
 interface ClientEvents {
     authChange: {
         token: string | null;