@playcademy/sandbox 0.1.11 → 0.2.0

package/README.md

@@ -180,103 +180,77 @@ All production Playcademy APIs are available under the `/api` prefix, including
 
 ## TimeBack Integration Testing
 
-The sandbox supports three TimeBack modes for flexible development and testing.
+The sandbox supports TimeBack integration testing in three modes: mock (offline), local (Docker), and remote (real TimeBack API).
 
-### Mode 1: Local TimeBack (Recommended for Development)
+### TimeBack Modes
 
-**Use local TimeBack Docker instance for offline development:**
+| Mode         | Description                                                           |
+| :----------- | :-------------------------------------------------------------------- |
+| **Mock**     | No external dependencies, works offline. Uses generated mock data.    |
+| **Local**    | Connect to a local TimeBack instance (Docker).                        |
+| **Remote**   | Real course IDs + API credentials. Tests against actual TimeBack API. |
+| **Disabled** | No TimeBack config. TimeBack routes return errors.                    |
 
-```bash
-# Enable local mode
-TIMEBACK_LOCAL=true
+### CLI Options
 
-# Set local TimeBack URLs (different ports)
-TIMEBACK_ONEROSTER_API_URL=http://localhost:9000
-TIMEBACK_CALIPER_API_URL=http://localhost:9001
+When running the sandbox standalone, configure TimeBack via CLI flags:
 
-# Optional: pre-seed with course/student IDs
-SANDBOX_TIMEBACK_COURSE_ID=local-dev-course
-SANDBOX_TIMEBACK_STUDENT_ID=local-dev-student
+```bash
+# Local TimeBack (Docker)
+bunx @playcademy/sandbox \
+  --timeback-local \
+  --timeback-oneroster-url http://localhost:8080/ims/oneroster \
+  --timeback-caliper-url http://localhost:8080/caliper \
+  --timeback-student-id your-student-id
+
+# Remote TimeBack (requires env vars for credentials)
+bunx @playcademy/sandbox \
+  --timeback-student-id your-student-sourcedId
 ```
 
-**Benefits:**
-
-- ✅ No external API dependencies
-- ✅ Works offline
-- ✅ Fast iteration
-- ✅ No real credentials needed
-
-**Requirements:**
-
-- Install and run `@superbuilders/timeback-local` Docker container
+| Option                     | Description                         |
+| :------------------------- | :---------------------------------- |
+| `--timeback-local`         | Enable local TimeBack mode (Docker) |
+| `--timeback-oneroster-url` | OneRoster API URL                   |
+| `--timeback-caliper-url`   | Caliper API URL                     |
+| `--timeback-course-id`     | Course ID for enrollments           |
+| `--timeback-student-id`    | Student ID to link to demo user     |
 
-### Mode 2: Remote TimeBack (Staging/Production)
+### Environment Variables
 
-**Connect to real TimeBack for end-to-end testing:**
+For remote TimeBack (or as alternative to CLI flags):
 
 ```bash
-# Required: TimeBack API credentials
+# TimeBack API credentials (required for remote mode)
 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
+# Link sandbox demo user to a real TimeBack student
 SANDBOX_TIMEBACK_STUDENT_ID=your-student-sourcedId
+SANDBOX_TIMEBACK_COURSE_ID=your-course-id
 ```
 
-**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
+### With Vite Plugin
 
-### Mode 3: Disabled (Default)
+When using `@playcademy/vite-plugin`, TimeBack enrollments and roles can be configured directly in `vite.config.ts` for a streamlined experience. See the [Vite plugin documentation](../vite-plugin/README.md#timeback-options-timeback) for details.
 
-No TimeBack integration. TimeBack routes return errors. This is the default when no TimeBack environment variables are set.
+The Vite plugin also provides a `t` hotkey to cycle through TimeBack roles during development.
 
-### Runtime Testing Workflow
+### Runtime Testing
 
-Once you have TimeBack credentials and IDs configured:
+Once configured, your game can use the SDK to submit activities:
 
-```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 }
+```typescript
+await client.timeback.endActivity({
+    correctQuestions: 8,
+    totalQuestions: 10,
 })
-
-# 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.
+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.
 
 ### Available TimeBack Endpoints