@playcademy/sdk 0.2.12 → 0.2.13

package/dist/index.d.ts

@@ -817,71 +817,6 @@ type InventoryItemWithItem = InventoryItemRow & {
     item: ItemRow;
 };
 
-/**
- * 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
  *
@@ -1038,6 +973,71 @@ declare abstract class PlaycademyBaseClient {
     };
 }
 
+/**
+ * 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 PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}): Promise<T>;
+
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @param baseUrl - The base URL of the Playcademy API
+ * @param email - User's email address
+ * @param password - User's password
+ * @returns Promise resolving to authentication response with token
+ * @throws PlaycademyError if authentication fails or network error occurs
+ *
+ * @example
+ * ```typescript
+ * // Preferred approach:
+ * const client = new PlaycademyClient({ baseUrl: '/api' })
+ * const result = await client.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * })
+ *
+ * // Legacy approach (still works):
+ * try {
+ *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
+ *   const client = new PlaycademyClient({ token: response.token })
+ * } catch (error) {
+ *   console.error('Login failed:', error.message)
+ * }
+ * ```
+ */
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+
 /**
  * Playcademy SDK client for game developers.
  * Provides namespaced access to platform features for games running inside Cademy.

package/dist/index.js

@@ -1477,7 +1477,7 @@ function createTimebackNamespace(client) {
             const cacheKey = [
               options?.grade ?? "",
               options?.subject ?? "",
-              options?.include?.sort().join(",") ?? ""
+              options?.include?.toSorted().join(",") ?? ""
             ].join(":");
             return xpCache.get(cacheKey, async () => {
               const params = new URLSearchParams;

package/dist/internal.d.ts

@@ -5619,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
  *
@@ -5841,132 +5776,69 @@ declare abstract class PlaycademyBaseClient {
 }
 
 /**
- * Playcademy SDK client for game developers.
- * Provides namespaced access to platform features for games running inside Cademy.
+ * 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 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;
-        }) => 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) => 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>) => 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>): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
-        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-    };
-    /** Auto-initializes a PlaycademyClient with context from the environment */
-    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;
-    };
-}
+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.
@@ -6625,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

package/dist/internal.js

@@ -1477,7 +1477,7 @@ function createTimebackNamespace(client) {
             const cacheKey = [
               options?.grade ?? "",
               options?.subject ?? "",
-              options?.include?.sort().join(",") ?? ""
+              options?.include?.toSorted().join(",") ?? ""
             ].join(":");
             return xpCache.get(cacheKey, async () => {
               const params = new URLSearchParams;

package/dist/server.d.ts

@@ -382,6 +382,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

package/dist/types.d.ts

@@ -4674,71 +4674,6 @@ declare enum MessageEvents {
     AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
 }
 
-/**
- * Auto-initializes a PlaycademyClient with context from the environment.
- * Works in both iframe mode (production/development) and standalone mode (local dev).
- *
- * This is the recommended way to initialize the SDK as it automatically:
- * - Detects the runtime environment (iframe vs standalone)
- * - Configures the client with the appropriate context
- * - Sets up event listeners for token refresh
- * - Exposes the client for debugging in development mode
- *
- * @param options - Optional configuration overrides
- * @param options.baseUrl - Override the base URL for API requests
- * @returns Promise resolving to a fully initialized PlaycademyClient
- * @throws Error if not running in a browser context
- *
- * @example
- * ```typescript
- * // Default initialization
- * const client = await PlaycademyClient.init()
- *
- * // With custom base URL
- * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
- * ```
- */
-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
  *
@@ -4895,6 +4830,71 @@ declare abstract class PlaycademyBaseClient {
     };
 }
 
+/**
+ * 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 PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}): Promise<T>;
+
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @param baseUrl - The base URL of the Playcademy API
+ * @param email - User's email address
+ * @param password - User's password
+ * @returns Promise resolving to authentication response with token
+ * @throws PlaycademyError if authentication fails or network error occurs
+ *
+ * @example
+ * ```typescript
+ * // Preferred approach:
+ * const client = new PlaycademyClient({ baseUrl: '/api' })
+ * const result = await client.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * })
+ *
+ * // Legacy approach (still works):
+ * try {
+ *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
+ *   const client = new PlaycademyClient({ token: response.token })
+ * } catch (error) {
+ *   console.error('Login failed:', error.message)
+ * }
+ * ```
+ */
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+
 /**
  * Playcademy SDK client for game developers.
  * Provides namespaced access to platform features for games running inside Cademy.
@@ -5680,6 +5680,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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.2.12",
+    "version": "0.2.13",
     "type": "module",
     "exports": {
         ".": {
@@ -44,12 +44,12 @@
         "@playcademy/data": "0.0.1",
         "@playcademy/logger": "0.0.1",
         "@playcademy/types": "0.0.1",
-        "@playcademy/sandbox": "0.3.13",
+        "@playcademy/sandbox": "0.3.14",
         "@playcademy/test": "0.0.1",
         "@playcademy/timeback": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
-        "playcademy": "0.16.5",
+        "playcademy": "0.16.9",
         "rollup": "^4.50.2",
         "rollup-plugin-dts": "^6.2.3",
         "typescript": "^5.7.2"