@playcademy/sandbox 0.3.2 → 0.3.5

package/README.md

@@ -2,7 +2,7 @@
 
 **Local development server for isolated Playcademy game development.**
 
-The Playcademy sandbox provides a complete local simulation of the Playcademy platform, including API services and a real-time server, for development and testing.
+The Playcademy sandbox provides a complete local simulation of the Playcademy platform API for development and testing.
 
 ## What is the Sandbox?
 
@@ -20,21 +20,18 @@ It's a "mock Playcademy platform" running on your machine that behaves just like
 - **Isolated Environment**: Completely local execution with no external dependencies.
 - **Zero Configuration**: Automatic database setup and seeding.
 - **Full API Compatibility**: All Playcademy APIs available locally.
-- **Integrated Real-time Server**: Built-in WebSocket server for multiplayer features.
 - **Fast Development Cycle**: Quick startup with persistent local database.
 
 ## How It Works
 
-The sandbox runs two local servers to provide a complete development environment. When using our Vite templates, this is handled automatically.
+The sandbox runs a local API server to provide a complete development environment. When using our Vite templates, this is handled automatically.
 
 ```mermaid
 graph TD
     subgraph "Your Machine"
         A["Your Game (in browser)"] --> B["@playcademy/sdk"];
         B --> C["API Server (localhost:4321)"];
-        B --> D["Real-time Server (localhost:4322)"];
-        C --> E["Local PGlite Database"];
-        D --> E;
+        C --> D["Local PGlite Database"];
     end
 ```
 
@@ -66,7 +63,7 @@ npm run dev
 
 :::
 
-You'll see output confirming that both the API and real-time servers are running:
+You'll see output confirming that the sandbox is running:
 
 ```
 VITE v6.3.5
@@ -77,8 +74,7 @@ VITE v6.3.5
 PLAYCADEMY v0.1.0
 
 ➜  Game:      playground
-➜  API:       http://localhost:4321/api
-➜  Realtime:  ws://localhost:4322
+➜  Sandbox:   http://localhost:4321/api
 ```
 
 ```typescript
@@ -92,11 +88,6 @@ export default defineConfig({
         playcademy({
             sandbox: {
                 autoStart: true,
-                url: 'http://localhost:4321/api',
-                realtime: {
-                    enabled: true,
-                    port: 4322,
-                },
             },
         }),
     ],
@@ -113,39 +104,38 @@ You can run the sandbox as a standalone process from the command line.
 # Run with defaults
 bunx @playcademy/sandbox
 
-# Run with custom ports and verbose logging
-bunx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081 --verbose
+# Run with custom port and verbose logging
+bunx @playcademy/sandbox --port 8080 --verbose
 ```
 
 ```bash [pnpm]
-pnpm dlx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+pnpm dlx @playcademy/sandbox --port 8080 --verbose
 ```
 
 ```bash [yarn]
-yarn dlx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+yarn dlx @playcademy/sandbox --port 8080 --verbose
 ```
 
 ```bash [npm]
-npx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+npx @playcademy/sandbox --port 8080 --verbose
 ```
 
 :::
 
 #### Command-Line Options
 
-| Option                     | Alias | Description                              | Default      |
-| :------------------------- | :---- | :--------------------------------------- | :----------- |
-| `--port <number>`          | `-p`  | Port for the main API server.            | `4321`       |
-| `--verbose`                | `-v`  | Enables verbose logging for debugging.   | `false`      |
-| `--realtime`               |       | Enables the real-time WebSocket server.  | `false`      |
-| `--realtime-port <number>` |       | Port for the real-time WebSocket server. | API port + 1 |
-| `--no-seed`                |       | Disables seeding of demo data.           | seeds        |
-| `--recreate-db`            |       | Recreate the on-disk database on start.  | `false`      |
-| `--memory`                 |       | Use in-memory database (no persistence). | `false`      |
-| `--db-path <path>`         |       | Custom path for the database file.       | `undefined`  |
-| `--config-path <path>`     |       | Path to playcademy.config.json.          | `cwd`        |
-| `--project-name <name>`    |       | Sets the project name for game seeding.  | `undefined`  |
-| `--project-slug <slug>`    |       | Sets the project slug for game seeding.  | `undefined`  |
+| Option                  | Alias | Description                              | Default     |
+| :---------------------- | :---- | :--------------------------------------- | :---------- |
+| `--port <number>`       | `-p`  | Port for the API server.                 | `4321`      |
+| `--verbose`             | `-v`  | Enables verbose logging for debugging.   | `false`     |
+| `--quiet`               | `-q`  | Quiet mode (suppress interactive output) | `false`     |
+| `--no-seed`             |       | Disables seeding of demo data.           | seeds       |
+| `--recreate-db`         |       | Recreate the on-disk database on start.  | `false`     |
+| `--memory`              |       | Use in-memory database (no persistence). | `false`     |
+| `--db-path <path>`      |       | Custom path for the database file.       | `undefined` |
+| `--config-path <path>`  |       | Path to playcademy.config.json.          | `cwd`       |
+| `--project-name <name>` |       | Sets the project name for game seeding.  | `undefined` |
+| `--project-slug <slug>` |       | Sets the project slug for game seeding.  | `undefined` |
 
 #### Manual SDK Configuration
 
@@ -156,7 +146,6 @@ import { PlaycademyClient } from '@playcademy/sdk'
 
 const client = await PlaycademyClient.init({
     baseUrl: 'http://localhost:4321/api',
-    realtimeUrl: 'ws://localhost:4322',
     // In manual mode, you must provide a mock token
     token: 'mock-dev-token',
 })
@@ -167,7 +156,6 @@ const client = await PlaycademyClient.init({
 | Feature              | Description                                                                                                                                            |
 | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **API Simulation**   | Emulates the entire Playcademy backend API for users, games, inventory, etc.                                                                           |
-| **Real-time Server** | Provides WebSocket-based real-time channels for multiplayer communication.                                                                             |
 | **Data Persistence** | Persists data to disk by default (survives restarts). Use `--recreate-db` to reset, `--memory` for in-memory only, or `--db-path` for custom location. |
 | **Mock Data**        | Automatically seeds with demo users and data on first run or when database is empty.                                                                   |
 | **Game Context**     | When run via the Vite plugin, it automatically registers your current project as a mock game.                                                          |
@@ -178,7 +166,6 @@ Once running, the sandbox provides several key endpoints:
 
 - **Health Check**: `GET /health`
 - **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.
 
@@ -212,13 +199,17 @@ bunx @playcademy/sandbox \
   --timeback-student-id your-student-sourcedId
 ```
 
-| Option                           | Description                         |
-| :------------------------------- | :---------------------------------- |
-| `--timeback-local`               | Enable local TimeBack mode (Docker) |
-| `--timeback-oneroster-url <url>` | OneRoster API URL                   |
-| `--timeback-caliper-url <url>`   | Caliper API URL                     |
-| `--timeback-course-id <id>`      | Course ID for enrollments           |
-| `--timeback-student-id <id>`     | Student ID to link to demo user     |
+| Option                           | Description                                            |
+| :------------------------------- | :----------------------------------------------------- |
+| `--timeback-local`               | Enable local TimeBack mode (Docker)                    |
+| `--timeback-oneroster-url <url>` | OneRoster API URL                                      |
+| `--timeback-caliper-url <url>`   | Caliper API URL                                        |
+| `--timeback-course-id <id>`      | Course ID for enrollments                              |
+| `--timeback-student-id <id>`     | Student ID to link to demo user                        |
+| `--timeback-role <role>`         | User role (student, parent, teacher, administrator)    |
+| `--timeback-org-id <id>`         | Organization ID                                        |
+| `--timeback-org-name <name>`     | Organization display name                              |
+| `--timeback-org-type <type>`     | Organization type (school, district, department, etc.) |
 
 ### Environment Variables
 
@@ -304,13 +295,12 @@ This should return a JSON object with the status:
 
 ### Common Issues
 
-| Issue                          | Solution                                                                                                                                                      |
-| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Sandbox doesn't start**      | When using Vite, check that `autoStart: true` in `vite.config.ts` and `@playcademy/vite-plugin` is installed. Check terminal for errors.                      |
-| **API calls return HTML**      | This indicates the API server isn't running or is on a different port. Check your sandbox `url` configuration.                                                |
-| **WebSocket connection fails** | Verify the real-time server is enabled (`--realtime` flag or Vite config) and check its port in the console output.                                           |
-| **Port conflicts**             | Use the `--port` and `--realtime-port` options to choose different ports. The sandbox will automatically try the next available port if its default is taken. |
-| **Data persists unexpectedly** | By default, the sandbox persists data to disk. Use `--recreate-db` to reset the database, or `--memory` for session-only data that doesn't persist.           |
+| Issue                          | Solution                                                                                                                                            |
+| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Sandbox doesn't start**      | When using Vite, check that `autoStart: true` in `vite.config.ts` and `@playcademy/vite-plugin` is installed. Check terminal for errors.            |
+| **API calls return HTML**      | This indicates the API server isn't running or is on a different port. Check your sandbox `url` configuration.                                      |
+| **Port conflicts**             | The sandbox uses port 4321 by default. If another process is using this port, stop it or use `--port` to specify a different port.                  |
+| **Data persists unexpectedly** | By default, the sandbox persists data to disk. Use `--recreate-db` to reset the database, or `--memory` for session-only data that doesn't persist. |
 
 ## Production vs. Sandbox