@playcademy/sandbox 0.1.0 → 0.1.1

package/README.md

@@ -176,7 +176,134 @@ Once running, the sandbox provides several key endpoints:
 - **API Base URL**: `/api`
 - **Real-time URL**: `ws://localhost:{realtimePort}`
 
-All production Playcademy APIs are available under the `/api` prefix, including `/users`, `/games`, `/inventory`, and more. Note that `/timeback` endpoints are available but return noop responses due to external API dependencies.
+All production Playcademy APIs are available under the `/api` prefix, including `/users`, `/games`, `/inventory`, and more.
+
+## TimeBack Integration Testing
+
+The sandbox supports three TimeBack modes for flexible development and testing.
+
+### Mode 1: Local TimeBack (Recommended for Development)
+
+**Use local TimeBack Docker instance for offline development:**
+
+```bash
+# Enable local mode
+TIMEBACK_LOCAL=true
+
+# Set local TimeBack URLs (different ports)
+TIMEBACK_ONEROSTER_API_URL=http://localhost:9000
+TIMEBACK_CALIPER_API_URL=http://localhost:9001
+
+# Optional: pre-seed with course/student IDs
+SANDBOX_TIMEBACK_COURSE_ID=local-dev-course
+SANDBOX_TIMEBACK_STUDENT_ID=local-dev-student
+```
+
+**Benefits:**
+
+- ✅ No external API dependencies
+- ✅ Works offline
+- ✅ Fast iteration
+- ✅ No real credentials needed
+
+**Requirements:**
+
+- Install and run `@superbuilders/timeback-local` Docker container
+
+### Mode 2: Remote TimeBack (Staging/Production)
+
+**Connect to real TimeBack for end-to-end testing:**
+
+```bash
+# Required: TimeBack API credentials
+TIMEBACK_ONEROSTER_API_URL=https://api.timeback.org/ims/oneroster
+TIMEBACK_API_CLIENT_ID=your-client-id
+TIMEBACK_API_CLIENT_SECRET=your-client-secret
+TIMEBACK_API_AUTH_URL=https://auth.timeback.org
+
+# Optional: pre-seed with existing course/student
+SANDBOX_TIMEBACK_COURSE_ID=your-existing-course-id
+SANDBOX_TIMEBACK_STUDENT_ID=your-student-sourcedId
+```
+
+**Benefits:**
+
+- ✅ Tests against real TimeBack
+- ✅ See actual events in TimeBack dashboard
+- ✅ Full production simulation
+
+**Pre-Seeding (Required for Local Testing):**
+
+```bash
+SANDBOX_TIMEBACK_COURSE_ID=your-existing-course-id
+SANDBOX_TIMEBACK_STUDENT_ID=your-existing-student-sourcedId
+```
+
+These are **required** (not optional) for local TimeBack testing because the sandbox uses mock authentication. CLI commands like `playcademy timeback setup` won't work against the sandbox - you must use existing TimeBack resources.
+
+**How to get these IDs:**
+
+1. Run `playcademy timeback setup` against the **platform** once (not sandbox)
+2. Get `courseId` from the output or your TimeBack dashboard
+3. Get `studentId` (sourcedId) from your TimeBack student roster
+4. Set them in `.env` for future local development
+
+What they do:
+
+- `SANDBOX_TIMEBACK_COURSE_ID` - Links your game to an existing TimeBack course
+- `SANDBOX_TIMEBACK_STUDENT_ID` - Links the sandbox demo user to a real TimeBack student
+
+### Mode 3: Disabled (Default)
+
+No TimeBack integration. TimeBack routes return errors. This is the default when no TimeBack environment variables are set.
+
+### Runtime Testing Workflow
+
+Once you have TimeBack credentials and IDs configured:
+
+```bash
+# 1. Start dev server
+bun dev
+
+# 2. Test in your game - TimeBack just works!
+client.timeback.endActivity({
+    activityData: { activityId: 'test-1' },
+    scoreData: { correctQuestions: 8, totalQuestions: 10 },
+    timingData: { durationSeconds: 300 }
+})
+
+# 3. Check your TimeBack dashboard - events appear in real-time!
+```
+
+**Note on CLI Commands:**
+The sandbox provides TimeBack management endpoints, but CLI commands (`playcademy timeback setup`, `verify`) require Better Auth authentication and won't work against the sandbox. These commands should be run against the platform. Once you have a course/student ID from the platform, set them in your `.env` for local testing.
+
+### Available TimeBack Endpoints
+
+The sandbox provides these TimeBack endpoints (matching production platform):
+
+**Management:**
+
+- `GET /api/timeback/integrations/:gameId` - Get integration details
+- `POST /api/timeback/setup` - Create TimeBack integration
+- `DELETE /api/timeback/integrations/:gameId` - Delete integration
+- `GET /api/timeback/verify/:gameId` - Verify OneRoster resources
+- `GET /api/timeback/config/:gameId` - Get TimeBack configuration
+
+**Runtime:**
+
+- `POST /api/timeback/end-activity` - Submit activity results
+
+**XP Queries:**
+
+- `GET /api/timeback/xp/today` - Get today's XP
+- `PUT /api/timeback/xp/today` - Update today's XP
+- `GET /api/timeback/xp/total` - Get total XP
+- `GET /api/timeback/xp/history` - Get XP history
+
+These use the same api-core handlers as the production platform, ensuring consistency.
+
+When properly configured, your game can call `client.timeback.endActivity()` during local development and see real events appear in your TimeBack dashboard.
 
 ## Debugging