@playcademy/sdk 0.9.1-beta.2 → 0.10.0

package/README.md

@@ -1,708 +1,215 @@
 # @playcademy/sdk
 
-**Official TypeScript SDK for the Playcademy platform**
-
-The Playcademy SDK provides a comprehensive, type-safe interface for building games on the Playcademy platform. It handles authentication, game sessions, user data, inventory management, and all platform APIs through a unified client interface.
+TypeScript SDK for building games on the Playcademy platform.
 
 ## Overview
 
-The SDK serves as the primary interface between your game and the Playcademy platform, providing:
-
-- **Automatic Environment Detection**: Seamlessly works in development and production
-- **Type-Safe API Access**: Full TypeScript support with comprehensive type definitions
-- **Session Management**: Automatic game session handling and state persistence
-- **Event System**: Real-time notifications for inventory changes, level ups, and more
-- **Developer Tools**: Built-in support for game development and testing workflows
-
-### Public vs Internal SDK
+The SDK is the interface between your game and the Playcademy platform. It provides:
 
-The Playcademy SDK is split into two entry points:
+- **Automatic Environment Detection** — works in development (sandbox) and production (platform loader)
+- **Type-Safe API Access** — full TypeScript support
+- **Activity Tracking** — TimeBack integration with automatic heartbeats and idle detection
+- **Developer Tools** — game deployment, secrets, database, and asset management
 
-#### Public SDK (`@playcademy/sdk`)
+### Entry Points
 
-For game developers building games on the Playcademy platform. Includes 8 essential namespaces:
+| Export                     | Use                                                                                      |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `@playcademy/sdk`          | Game SDK — used by games running on the platform                                         |
+| `@playcademy/sdk/internal` | Platform SDK — used by CLI, admin tools, and platform internals                          |
+| `@playcademy/sdk/server`   | Server SDK — used by game backends (token verification, server-side activity submission) |
+| `@playcademy/sdk/types`    | Type-only imports                                                                        |
+| `@playcademy/sdk/test`     | Test utilities                                                                           |
 
-- **Core**: `identity`, `runtime`, `backend`, `users`
-- **Economy**: `credits`
-- **Gameplay**: `scores`
-- **Multiplayer**: `realtime`
-- **Integrations**: `timeback`
+## Quick Start
 
 ```typescript
 import { PlaycademyClient } from '@playcademy/sdk'
 
 const client = await PlaycademyClient.init()
-await client.timeback.endActivity({
-    /* ... */
-})
-await client.users.inventory.add('gold-coin', 100)
-```
-
-#### Internal SDK (`@playcademy/sdk/internal`)
-
-For CLI, platform, and admin tools. Includes all 21 namespaces (8 public + 13 internal):
-
-**Additional internal namespaces:**
-
-- **Platform Auth**: `auth` (email/password login, API keys)
-- **Administration**: `admin` (game management, items, currencies)
-- **Developer Tools**: `dev` (publish games, uploads)
-- **Game Directory**: `games` (fetch, list, sessions)
-- **Overworld Features**: `character`, `achievements`, `leaderboard`, `levels`, `shop`, `maps`, `sprites`, `notifications`
-- **Analytics**: `telemetry`
-
-```typescript
-import { PlaycademyClient } from '@playcademy/sdk/internal'
 
-const client = new PlaycademyClient({ baseUrl: 'https://hub.playcademy.net' })
-await client.auth.login({ email: 'dev@example.com', password: '***' })
-const games = await client.games.list()
-await client.admin.games.pauseGame('game-123')
+const user = await client.users.me()
+console.log('Welcome,', user.displayName)
 ```
 
-**Note**: The internal SDK is for trusted code only (CLI, platform internals). Game developers should use the public SDK.
-
-### Key Benefits
-
-- **Zero Configuration**: Automatic initialization with environment detection
-- **Production Ready**: Battle-tested API patterns with robust error handling
-- **Real-Time Communication**: Open game-scoped WebSocket channels for multiplayer features.
-- **Event System**: Subscribe to platform events like inventory changes and level ups
-- **Comprehensive Coverage**: Access to all Playcademy platform features
-- **Development Experience**: Integrated with sandbox environment for local development
-
-### Use Cases
-
-- **Game Development**: Primary SDK for building games on Playcademy
-- **Web Applications**: Frontend applications interacting with the platform
-- **Developer Tools**: Scripts and utilities for game management
-- **Server Integration**: Backend services integrating with Playcademy APIs
-- **Testing & Automation**: Automated testing of platform integrations
-
-### Connection Monitoring
-
-The SDK automatically monitors network connectivity and provides hooks for games to handle disconnects gracefully:
+In development, the Vite plugin starts a local sandbox automatically. In production, the platform loader provides configuration via `postMessage`.
 
-- **Automatic Detection**: Multi-signal approach detects offline, slow, and degraded connections
-- **Game Handlers**: Implement custom disconnect behavior (e.g., return to lobby, pause game)
-- **Platform Integration**: Built-in helpers for displaying connection alerts
-- **Zero Config**: Works out of the box, customizable when needed
+## Game SDK Namespaces
 
-See the SDK Browser documentation for detailed connection monitoring documentation and examples.
+### `client.users`
 
-## Installation
-
-Install the SDK using your preferred package manager:
-
-```bash
-# Using Bun (recommended)
-bun add @playcademy/sdk
-
-# Using npm
-npm install @playcademy/sdk
-
-# Using yarn
-yarn add @playcademy/sdk
-
-# Using pnpm
-pnpm add @playcademy/sdk
-```
-
-## Quick Start
-
-### Automatic Initialization (Recommended)
-
-For most game development scenarios, use automatic initialization:
+User profile access.
 
 ```typescript
-import { PlaycademyClient } from '@playcademy/sdk'
-
-async function initializeGame() {
-    try {
-        // Automatic initialization - detects environment and configures appropriately
-        const client = await PlaycademyClient.init({
-            // Optional: Handle connection issues gracefully
-            onDisconnect: ({ state, displayAlert }) => {
-                if (state === 'offline') {
-                    displayAlert?.('Connection lost. Reconnecting...', { type: 'warning' })
-                    // Return to safe state (e.g., lobby)
-                }
-            },
-        })
-
-        // Get current user
-        const user = await client.users.me()
-        console.log('Welcome,', user.name)
-
-        // The client is ready for all platform operations
-        return client
-    } catch (error) {
-        console.error('Failed to initialize Playcademy SDK:', error)
-        throw error
-    }
-}
+const user = await client.users.me()
 ```
 
-### Environment Detection
-
-The SDK automatically detects and configures for different environments:
-
-- **Development**: Connects to local sandbox (started by `@playcademy/vite-plugin`)
-- **Production**: Receives configuration from Playcademy platform loader
-- **Testing**: Falls back to mock configuration for automated testing
-
-## Core Features
+### `client.runtime`
 
-### Game Session Management
+Game lifecycle and platform communication.
 
 ```typescript
-// Automatic session management when gameId is available
-const client = await PlaycademyClient.init()
-
-// Save transient game state (position, health, temporary data)
-await client.games.saveState({
-    currentLevel: 'forest_glade',
-    playerPosition: { x: 100, y: 200 },
-    health: 85,
-    activePowerUps: ['speed_boost'],
-})
+client.runtime.ready()
+client.runtime.exit()
+client.runtime.sendTelemetry({ fps: 60, mem: 128 })
 
-// Load previously saved state
-const gameState = await client.games.loadState()
-console.log('Loaded state:', gameState)
-
-// Exit game (automatically ends session if managed)
-await client.runtime.exit()
+client.runtime.onPause(() => pauseGame())
+client.runtime.onResume(() => resumeGame())
 ```
 
-### User & Inventory Management
+**Assets** — build CDN URLs for game assets uploaded via `playcademy deploy`:
 
 ```typescript
-// Get user information
-const user = await client.users.me()
-
-// Inventory operations (accepts UUIDs or slugs)
-const inventory = await client.users.inventory.get()
-await client.users.inventory.add('magic-sword', 1)
-await client.users.inventory.remove('health-potion', 1)
-
-// Check item quantities and ownership
-const goldCount = await client.users.inventory.quantity('gold-coin')
-const hasKey = await client.users.inventory.has('dungeon-key')
-const hasEnoughGold = await client.users.inventory.has('gold-coin', 100)
+const url = client.runtime.assets.url`sprites/player.png`
+const data = await client.runtime.assets.json('config/levels.json')
 ```
 
-### Credits & Currency
+### `client.scores`
+
+Score submission for the current game.
 
 ```typescript
-// Platform currency management
-const balance = await client.credits.balance()
-await client.credits.add(100)
-await client.credits.spend(50)
-
-// Check affordability
-if ((await client.credits.balance()) >= 100) {
-    await client.credits.spend(100)
-    console.log('Purchase successful!')
-}
+await client.scores.submit(1250, { level: 'forest', time: 42 })
 ```
 
-### Experience & Levels
+### `client.leaderboard`
 
-```typescript
-// Level management
-const userLevel = await client.levels.get()
-const progress = await client.levels.progress()
-console.log(`Level ${userLevel.currentLevel}, ${progress.xpToNextLevel} XP to next level`)
+Leaderboard queries for the current game.
 
-// Note: XP is now managed entirely through TimeBack integration.
-// XP updates come from TimeBack webhooks only.
+```typescript
+const entries = await client.leaderboard.fetch({
+    timeframe: 'weekly',
+    limit: 10,
+})
 ```
 
-### TimeBack Integration
+### `client.timeback`
 
-Access user role and enrollments, and track learning activities:
+TimeBack LMS integration — activity tracking with automatic heartbeats, idle detection, and pause/resume tied to tab visibility.
 
 ```typescript
-// Access TimeBack role and enrollments
-const role = client.timeback.role // 'student' | 'parent' | 'teacher' | 'administrator'
-const enrollments = client.timeback.enrollments // [{ subject, grade, courseId }]
-
-// Check if user is enrolled in a specific grade
-const grade3Enrollment = enrollments.find(e => e.grade === 3)
-if (grade3Enrollment) {
-    // Show grade 3 content
-}
+const role = client.timeback.user.role
+const enrollments = client.timeback.user.enrollments
 
-// Start tracking an activity (only activityId required!)
-const { runId } = client.timeback.startActivity({
+const { runId } = await client.timeback.startActivity({
     activityId: 'math-quiz-level-1',
 })
-// Auto-derived: activityName "Math Quiz Level 1"
-// Auto-filled by backend: appName, subject, sensorUrl
-// Returns the runId used by heartbeat and endActivity events
-// Automatically pauses active time when the tab is hidden, the shell pauses,
-// or the player has no visible keyboard/mouse activity for 10 minutes
-
-// Customize inactivity handling
-client.timeback.startActivity(
-    { activityId: 'math-quiz-level-1' },
-    {
-        inactivityTimeoutMs: 5 * 60 * 1000, // 5 minutes
-        heartbeatIntervalMs: 15_000,
-    },
-)
-
-// Disable keyboard/mouse inactivity tracking
-client.timeback.startActivity(
-    { activityId: 'math-quiz-level-1' },
-    { inactivityTimeoutMs: Infinity },
-)
 
-// ... player completes activity ...
+// Activity auto-pauses on tab hide, shell pause, or 10min keyboard/mouse idle.
+// Heartbeats are sent automatically.
 
-// End activity and submit results (XP calculated automatically)
 await client.timeback.endActivity({
     correctQuestions: 8,
     totalQuestions: 10,
 })
-// XP calculation: base (1 min = 1 XP) × accuracy multiplier
-// 100%: 1.25x | 80-99%: 1.0x | 65-79%: 0.5x | <65%: 0x
 ```
 
-### Real-time Authentication
-
-Get authentication tokens for WebSocket connections used by the platform's multiplayer system.
+Options for `startActivity`:
 
 ```typescript
-// Get a realtime token for WebSocket authentication
-const { token } = await client.realtime.token.get()
-
-// Token is used internally by the platform's multiplayer WebSocket client
-// for presence tracking, player positions, and real-time game features
+await client.timeback.startActivity(
+    { activityId: 'math-quiz-level-1' },
+    {
+        inactivityTimeoutMs: 5 * 60 * 1000, // custom idle timeout (default: 10min)
+        heartbeatIntervalMs: 15_000, // heartbeat frequency
+    },
+)
 ```
 
-## API Reference
-
-### Core Modules
-
-#### **Authentication** (`client.auth`)
-
-- `logout()`: Logs out user and clears authentication token
-
-#### **Users** (`client.users`)
-
-- `me()`: Get current user information
-- **Inventory** (`client.users.inventory`):
-    - `get()`: Get user's inventory
-    - `add(identifier, quantity)`: Add items to inventory
-    - `remove(identifier, quantity)`: Remove items from inventory
-    - `quantity(identifier)`: Get item quantity
-    - `has(identifier, minQuantity?)`: Check item ownership
-
-#### **Games** (`client.games`)
-
-- `list()`: Get all available games
-- `fetch(gameIdOrSlug)`: Get specific game details
-- `saveState(state)`: Save transient game state
-- `loadState()`: Load saved game state
-- `startSession(gameId?)`: Start game session
-- `endSession(sessionId, gameId?)`: End game session
-
-#### **Credits** (`client.credits`)
-
-- `balance()`: Get current credits balance
-- `add(amount)`: Add credits to user
-- `spend(amount)`: Spend user credits
-
-#### **Levels** (`client.levels`)
-
-- `get()`: Get current user level information
-- `progress()`: Get level progress and XP to next level
-- `addXP(amount)`: Add experience points
-- **Config** (`client.levels.config`):
-    - `list()`: Get all level configurations
-    - `get(level)`: Get specific level configuration
-
-#### **Maps** (`client.maps`)
-
-- `elements(mapId)`: Get map elements and points of interest
-
-#### **Runtime** (`client.runtime`)
-
-- `getGameToken(gameId, options?)`: Get game-specific authentication token
-- `exit()`: Signal platform to exit game view
-
-#### **Real-time** (`client.realtime`)
-
-- `token.get()`: Retrieves a JWT for WebSocket authentication (used by the platform's multiplayer system).
-
-#### **TimeBack** (`client.timeback`)
-
-- `role`: The user's TimeBack role (`'student'`, `'parent'`, `'teacher'`, or `'administrator'`)
-- `enrollments`: Array of course enrollments with `subject`, `grade`, and `courseId`
-- `currentRunId`: Active activity run ID, or `undefined` when no activity is active
-- `startActivity(metadata, options?)`: Start tracking an activity and return `{ runId }`
-    - `metadata.activityId`: Unique activity identifier (required)
-    - `metadata.activityName`: Human-readable activity name
-    - `metadata.subject`: Subject area (Math, Reading, Science, etc.)
-    - `metadata.appName`: Application name
-    - `metadata.sensorUrl`: Sensor URL for tracking
-    - Automatically pauses active time when the tab is hidden, the shell pauses the game, or the player is idle while visible
-    - `options.pausedHeartbeatTimeoutMs`: Stop periodic heartbeats after a long automatic pause (`hidden` or `inactivity`); `Infinity` keeps them running
-    - `options.heartbeatIntervalMs`: Flush incremental heartbeats (`Infinity` disables periodic heartbeats)
-    - `options.inactivityTimeoutMs`: Keyboard/mouse idle timeout while visible (defaults to 10 minutes; `Infinity` disables)
-    - `options.runId`: Stable UUID to reuse for resumable activities
-- `endActivity(scoreData)`: End activity and submit results
-    - `scoreData.correctQuestions`: Number of correct answers
-    - `scoreData.totalQuestions`: Total number of questions
-- **XP Query** (`client.timeback.xp`):
-    - `today(options?)`: Get today's XP (supports timezone parameter)
-    - `total()`: Get total accumulated XP
-    - `history(options?)`: Get XP history with optional date filtering
-    - `summary(options?)`: Get both today's and total XP in one call
-
-#### **Leaderboard** (`client.leaderboard`) - Game-specific
-
-- `fetch(options?)`: Get leaderboard for a specific game
-    - `options.timeframe`: Filter by time period (`'all_time'`, `'monthly'`, `'weekly'`, `'daily'`)
-    - `options.gameId`: Game ID to fetch leaderboard for (required)
-    - `options.limit`: Number of entries to return (default: 10)
-    - `options.offset`: Pagination offset (default: 0)
-
-#### **Scores** (`client.scores`) - Platform-wide
-
-- `submit(gameId, score, metadata?)`: Submit a score for any game
-- `getUserScores(userId, options?)`: Get all scores for a user
-    - `options.gameId`: Filter by specific game (optional)
-    - `options.limit`: Number of scores to return (default: 50)
-
-### Developer Tools
-
-#### **Developer Authentication** (`client.dev.auth`)
-
-- `applyForDeveloper()`: Apply for developer status
-- `getDeveloperStatus()`: Check current developer status
-
-#### **Game Management** (`client.dev.games`)
-
-- `upsert(slug, metadata, gameFile)`: Create or update game
-- `update(gameId, updates)`: Update game properties
-- `delete(gameId)`: Delete game
+### `client.backend`
 
-#### **API Keys** (`client.dev.keys`)
-
-- `createKey(gameId, name)`: Create API key for server authentication
-- `listKeys()`: List all API keys
-- `revokeKey(keyId)`: Revoke API key
-
-#### **Item Management** (`client.dev.items`)
-
-- `list(gameId)`: List all items for a game
-- `get(gameId, slug)`: Get specific item
-- `create(gameId, slug, data)`: Create new game item
-- `update(gameId, itemId, updates)`: Update existing item
-- `delete(gameId, itemId)`: Delete item
-
-## Event System
-
-The SDK provides real-time event notifications for important platform changes:
-
-### Available Events
+HTTP client for game-specific backend functions deployed via `playcademy deploy`.
 
 ```typescript
-// Authentication changes
-client.on('authChange', payload => {
-    console.log('Authentication changed:', payload.token)
-})
-
-// Connection state changes
-client.on('connectionChange', ({ state, reason }) => {
-    console.log(`Connection: ${state} - ${reason}`)
-})
+const result = await client.backend.post('/generate-puzzle', { difficulty: 3 })
+const config = await client.backend.get('/config')
+const url = client.backend.url`/assets/map.json`
+```
 
-// Inventory changes
-client.on('inventoryChange', payload => {
-    console.log(`Item ${payload.itemId}: ${payload.delta} (total: ${payload.newTotal})`)
-})
+### `client.identity`
 
-// Experience gained
-client.on('xpGained', payload => {
-    console.log(`Gained ${payload.amount} XP (total: ${payload.totalXP})`)
-})
+OAuth provider connections (Discord, Google, etc.).
 
-// Level up notifications
-client.on('levelUp', payload => {
-    console.log(`Level up! ${payload.oldLevel} → ${payload.newLevel}`)
-    console.log('Credits awarded:', payload.creditsAwarded)
-})
+```typescript
+await client.identity.connect({ provider: 'discord' })
 ```
 
-### Disconnect Handling
+### `client.demo`
 
-For convenience, use the `onDisconnect` method to handle only offline/degraded states:
+Demo mode for anonymous players on the landing page.
 
 ```typescript
-const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
-    console.log(`Disconnect detected: ${state}`)
-    displayAlert?.(`Connection ${state}: ${reason}`, { type: 'warning' })
-})
-
-// Later: cleanup() to unregister
+const profile = await client.demo.profile.get()
+client.demo.end(score, { displayName: 'Player 1' })
 ```
 
-### Event-Driven UI Updates
+## Internal SDK
+
+For CLI, admin dashboard, and platform tools. Includes all game namespaces plus:
+
+| Namespace         | Purpose                                                                   |
+| ----------------- | ------------------------------------------------------------------------- |
+| `client.auth`     | Email/password login, API key management                                  |
+| `client.admin`    | Game pause/resume                                                         |
+| `client.dev`      | Game deployment, secrets, database, KV, bucket management                 |
+| `client.games`    | Game listing, fetching, state, sessions                                   |
+| `client.timeback` | Platform-tier TimeBack operations (enrollment, XP grants, reconciliation) |
 
 ```typescript
-// Update UI in response to platform events
-client.on('inventoryChange', payload => {
-    updateInventoryDisplay(payload.itemId, payload.newTotal)
-})
+import { PlaycademyClient } from '@playcademy/sdk/internal'
 
-client.on('levelUp', payload => {
-    showLevelUpAnimation(payload.newLevel)
-    showCreditsAwarded(payload.creditsAwarded)
-})
+const client = new PlaycademyClient({ baseUrl: 'https://hub.playcademy.net' })
+await client.auth.login({ email: 'dev@example.com', password: '***' })
 
-client.on('xpGained', payload => {
-    updateXPBar(payload.totalXP, payload.leveledUp)
-})
+const games = await client.games.list()
+await client.dev.games.deploy('my-game', { metadata, file })
 ```
 
-## Advanced Usage
-
-### Manual Initialization
+## Server SDK
 
-For server-side applications or custom environments:
+For game backends that need to verify player tokens or submit activity results server-side.
 
 ```typescript
-import { PlaycademyClient } from '@playcademy/sdk'
+import { PlaycademyClient, verifyGameToken } from '@playcademy/sdk/server'
 
-import type { LoginResponse } from '@playcademy/sdk'
+const { user } = await verifyGameToken(token)
 
-// Step 1: Authenticate
-const loginData: LoginResponse = await PlaycademyClient.login(
-    'https://api.playcademy.com',
-    'user@example.com',
-    'password',
-)
-
-// Step 2: Initialize client
-const client = new PlaycademyClient({
-    baseUrl: 'https://api.playcademy.com',
-    token: loginData.token,
-    gameId: 'your-game-id', // Optional: enables automatic session management
-})
+const client = new PlaycademyClient({ apiToken, gameId, env })
+await client.timeback.endActivity(userId, payload)
 ```
 
-### Custom Configuration
+## Base Client API
+
+All client variants share:
 
 ```typescript
-const client = new PlaycademyClient({
-    baseUrl: 'https://api.playcademy.com',
-    token: 'your-auth-token',
-    gameId: 'your-game-id',
-    // Additional options
-    timeout: 10000, // Request timeout in milliseconds
-    retries: 3, // Number of retry attempts
-})
+client.getToken()
+client.setToken(token, tokenType?)
+client.isAuthenticated()
+client.on(event, callback)    // returns cleanup function
+client.off(event, callback)
+client.onAuthChange(callback)
 ```
 
-### Error Handling
+## Error Handling
 
 ```typescript
 import { PlaycademyError } from '@playcademy/sdk'
 
 try {
-    const user = await client.users.me()
-    // Handle success
+    await client.scores.submit(score)
 } catch (error) {
     if (error instanceof PlaycademyError) {
-        console.error('Playcademy API Error:', error.message)
-        console.error('Status Code:', error.statusCode)
-        console.error('Error Code:', error.code)
-    } else {
-        console.error('Unexpected error:', error)
+        console.error(error.message, error.statusCode, error.code)
     }
 }
 ```
 
-## Development Environment
-
-### Integration with Playcademy Vite Plugin
+## Development
 
-When using the official Playcademy Vite templates, the development environment is automatically configured:
+In development, the SDK connects to a local sandbox started by `@playcademy/vite-plugin`. The sandbox provides mock auth, a local API, and game asset serving — no platform account needed.
 
 ```typescript
-// In your game's main file
-import { PlaycademyClient } from '@playcademy/sdk'
-
-// The vite plugin automatically starts the sandbox
+// Automatic — vite plugin handles everything
 const client = await PlaycademyClient.init()
-// SDK automatically connects to local sandbox at http://localhost:4321
-```
-
-### Manual Sandbox Setup
-
-If not using the Vite plugin, start the sandbox manually:
-
-```bash
-# Start sandbox server (will also start realtime server on port 4322)
-bunx @playcademy/sandbox --port 4321 --verbose
-
-# In your application
-const client = new PlaycademyClient({
-    baseUrl: 'http://localhost:4321/api',
-    realtimeUrl: 'ws://localhost:4322',
-    token: 'dev-token' // Sandbox provides mock authentication
-})
 ```
-
-## Best Practices
-
-### Initialization & Setup
-
-- **Always use automatic initialization** for game development with `PlaycademyClient.init()`
-- **Handle initialization errors gracefully** with proper try-catch blocks
-- **Store the client instance** for reuse throughout your application lifecycle
-
-### State Management
-
-- **Use `games.saveState()`** for transient data (current level, position, temporary status)
-- **Use `users.inventory`** for persistent items and resources that carry between sessions
-- **Save state periodically**, not on every frame or minor change
-- **Load state once** at game start, then manage locally
-
-### Performance Optimization
-
-- **Cache frequently accessed data** like user information and inventory
-- **Batch inventory operations** when possible instead of individual API calls
-- **Use event listeners** to update UI reactively rather than polling
-- **Implement proper loading states** for better user experience
-
-### Error Handling
-
-- **Wrap all SDK calls** in appropriate try-catch blocks
-- **Provide fallback behavior** for network errors and API failures
-- **Show meaningful error messages** to users when operations fail
-- **Implement retry logic** for non-critical operations
-
-### Development Workflow
-
-- **Use the sandbox environment** for all local development
-- **Test both online and offline scenarios** to ensure robust error handling
-- **Enable verbose logging** during development for debugging
-- **Validate API responses** and handle edge cases appropriately
-
-## Testing
-
-### Unit Testing
-
-```typescript
-// Mock the SDK for unit tests
-import { jest } from '@jest/globals'
-
-// Mock the entire SDK module
-jest.mock('@playcademy/sdk', () => ({
-    PlaycademyClient: {
-        init: jest.fn().mockResolvedValue({
-            users: {
-                me: jest.fn().mockResolvedValue({ id: 'test-user', name: 'Test User' }),
-                inventory: {
-                    get: jest.fn().mockResolvedValue([]),
-                    add: jest.fn().mockResolvedValue(undefined),
-                },
-            },
-        }),
-    },
-}))
-```
-
-### Integration Testing
-
-```typescript
-// Test with real sandbox
-import { PlaycademyClient } from '@playcademy/sdk'
-
-describe('Playcademy Integration', () => {
-    let client: PlaycademyClient
-
-    beforeAll(async () => {
-        // Initialize with sandbox
-        client = new PlaycademyClient({
-            baseUrl: 'http://localhost:4321/api',
-            token: 'test-token',
-        })
-    })
-
-    test('should fetch user data', async () => {
-        const user = await client.users.me()
-        expect(user).toBeDefined()
-        expect(user.name).toEqual(expect.any(String))
-    })
-})
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**SDK Initialization Timeout**
-
-```
-Error: PLAYCADEMY_INIT not received within 5000ms
-```
-
-- Ensure you're running in the correct environment (development with sandbox, or production with platform)
-- Check that the Vite plugin is properly configured
-- Verify the sandbox is running on the expected port
-
-**Authentication Errors**
-
-```
-Error: Unauthorized (401)
-```
-
-- Check that your authentication token is valid
-- Ensure you have the necessary permissions for the operation
-- Try re-authenticating with `PlaycademyClient.login()`
-
-**Network Connection Issues**
-
-```
-Error: Failed to fetch
-```
-
-- Verify the API endpoint is accessible
-- Check network connectivity
-- Ensure CORS is properly configured for cross-origin requests
-
-### Debugging
-
-Use these debugging techniques for troubleshooting SDK issues:
-
-```typescript
-// Check initialization process
-try {
-    const client = await PlaycademyClient.init()
-    console.log('SDK initialized successfully')
-} catch (error) {
-    console.error('SDK initialization failed:', error)
-}
-
-// Monitor network requests in browser dev tools (Network tab)
-// Check console for SDK error messages
-// Verify API responses and error details
-```
-
-## Contributing
-
-The SDK is a critical component of the Playcademy platform ecosystem. When contributing:
-
-1. **Maintain Type Safety**: Ensure all new APIs are fully typed
-2. **Update Documentation**: Keep this README and JSDoc comments current
-3. **Add Tests**: Include both unit and integration tests for new features
-4. **Follow Patterns**: Use consistent patterns with existing SDK methods
-5. **Handle Errors**: Implement proper error handling and user feedback
-
-For general contribution guidelines, see the [monorepo CONTRIBUTING.md](../../CONTRIBUTING.md).