@playcademy/sandbox 0.2.3 → 0.3.0

package/dist/config.d.ts

@@ -1,7 +1,23 @@
+import { TimebackOrgType, TimebackUserRole } from '@playcademy/data/types';
+
 /**
  * Configuration Type Definitions
  */
+
 type TimebackMode = 'local' | 'remote' | 'disabled';
+/**
+ * Organization configuration input for sandbox.
+ * All fields optional since they can be derived from defaults.
+ */
+interface TimebackOrganizationInput {
+    id?: string;
+    name?: string;
+    type?: TimebackOrgType;
+}
+/**
+ * Timeback configuration input for sandbox.
+ * All fields optional since they can be derived from defaults.
+ */
 interface TimebackConfig {
     mode: TimebackMode;
     onerosterApiUrl?: string;
@@ -10,12 +26,22 @@ interface TimebackConfig {
     clientSecret?: string;
     authUrl?: string;
     courseId?: string;
-    studentId?: string;
+    timebackId?: string;
+    organization?: TimebackOrganizationInput;
+    role?: TimebackUserRole;
 }
+/**
+ * Authentication configuration input for sandbox.
+ * All fields required.
+ */
 interface AuthConfig {
     betterAuthSecret: string;
     gameJwtSecret: string;
 }
+/**
+ * Sandbox configuration input for sandbox.
+ * All fields required.
+ */
 interface SandboxConfig {
     embedded: boolean;
     auth: AuthConfig;
@@ -36,8 +62,18 @@ declare function hasTimebackCredentials(): boolean;
 declare function hasTimebackFullConfig(): boolean;
 declare function requireTimebackCredentials(): TimebackConfig;
 declare function configureTimeback(options: Partial<TimebackConfig>): void;
+/**
+ * Get the effective Timeback mode for display.
+ * Returns null if timeback is not configured, otherwise 'mock', 'remote', or 'local'.
+ *
+ * Logic:
+ * - No timebackId → null (timeback disabled)
+ * - timebackId='mock' or no credentials → 'mock'
+ * - timebackId=real + credentials → actual mode ('remote' or 'local')
+ */
+declare function getTimebackDisplayMode(): 'mock' | 'remote' | 'local' | null;
 
 declare const config: SandboxConfig;
 
-export { config, configureTimeback, hasTimebackCredentials, hasTimebackFullConfig, isTimebackEnabled, requireTimebackCredentials, setEmbeddedMode };
+export { config, configureTimeback, getTimebackDisplayMode, hasTimebackCredentials, hasTimebackFullConfig, isTimebackEnabled, requireTimebackCredentials, setEmbeddedMode };
 export type { AuthConfig, SandboxConfig, TimebackConfig, TimebackMode };

package/dist/config.js

@@ -53,7 +53,7 @@ function hasTimebackCredentials() {
   return false;
 }
 function hasTimebackFullConfig() {
-  return hasTimebackCredentials() && !!(config.timeback.courseId && config.timeback.studentId);
+  return hasTimebackCredentials() && !!(config.timeback.courseId && config.timeback.timebackId);
 }
 function requireTimebackCredentials() {
   if (hasTimebackCredentials())
@@ -107,10 +107,35 @@ function configureTimeback(options) {
     config.timeback.courseId = options.courseId;
     process.env.SANDBOX_TIMEBACK_COURSE_ID = options.courseId;
   }
-  if (options.studentId) {
-    config.timeback.studentId = options.studentId;
-    process.env.SANDBOX_TIMEBACK_STUDENT_ID = options.studentId;
+  if (options.timebackId) {
+    config.timeback.timebackId = options.timebackId;
+    process.env.SANDBOX_TIMEBACK_STUDENT_ID = options.timebackId;
+    const isMockMode = options.timebackId === "mock";
+    process.env.SANDBOX_TIMEBACK_MOCK_MODE = isMockMode ? "true" : "false";
   }
+  if (options.organization) {
+    config.timeback.organization = options.organization;
+    process.env.SANDBOX_TIMEBACK_ORG_ID = options.organization.id;
+    if (options.organization.name) {
+      process.env.SANDBOX_TIMEBACK_ORG_NAME = options.organization.name;
+    }
+    if (options.organization.type) {
+      process.env.SANDBOX_TIMEBACK_ORG_TYPE = options.organization.type;
+    }
+  }
+  if (options.role) {
+    config.timeback.role = options.role;
+    process.env.SANDBOX_TIMEBACK_ROLE = options.role;
+  }
+}
+function getTimebackDisplayMode() {
+  const { timebackId, mode } = config.timeback;
+  if (!timebackId)
+    return null;
+  if (timebackId === "mock" || !hasTimebackCredentials()) {
+    return "mock";
+  }
+  return mode;
 }
 
 // src/config/mutators.ts
@@ -134,7 +159,7 @@ var config = {
     clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET,
     authUrl: process.env.TIMEBACK_API_AUTH_URL,
     courseId: process.env.SANDBOX_TIMEBACK_COURSE_ID,
-    studentId: process.env.SANDBOX_TIMEBACK_STUDENT_ID
+    timebackId: process.env.SANDBOX_TIMEBACK_STUDENT_ID
   }
 };
 process.env.BETTER_AUTH_SECRET = config.auth.betterAuthSecret;
@@ -146,6 +171,7 @@ export {
   isTimebackEnabled,
   hasTimebackFullConfig,
   hasTimebackCredentials,
+  getTimebackDisplayMode,
   configureTimeback,
   config
 };

package/dist/constants.d.ts

@@ -0,0 +1,193 @@
+import { Item } from '@playcademy/data/types';
+
+/**
+ * Demo user data for sandbox testing
+ */
+declare const DEMO_USER_IDS: {
+    readonly player: "00000000-0000-0000-0000-000000000001";
+    readonly developer: "00000000-0000-0000-0000-000000000002";
+    readonly admin: "00000000-0000-0000-0000-000000000003";
+    readonly pendingDeveloper: "00000000-0000-0000-0000-000000000004";
+    readonly unverifiedPlayer: "00000000-0000-0000-0000-000000000005";
+};
+declare const DEMO_USERS: {
+    readonly admin: {
+        readonly id: "00000000-0000-0000-0000-000000000003";
+        readonly name: "Admin User";
+        readonly username: "admin_user";
+        readonly email: "admin@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "admin";
+        readonly developerStatus: "approved";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly player: {
+        readonly id: "00000000-0000-0000-0000-000000000001";
+        readonly name: "Player User";
+        readonly username: "player_user";
+        readonly email: "player@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "player";
+        readonly developerStatus: "none";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly developer: {
+        readonly id: "00000000-0000-0000-0000-000000000002";
+        readonly name: "Developer User";
+        readonly username: "developer_user";
+        readonly email: "developer@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "developer";
+        readonly developerStatus: "approved";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly pendingDeveloper: {
+        readonly id: "00000000-0000-0000-0000-000000000004";
+        readonly name: "Pending Developer";
+        readonly username: "pending_dev";
+        readonly email: "pending@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "developer";
+        readonly developerStatus: "pending";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly unverifiedPlayer: {
+        readonly id: "00000000-0000-0000-0000-000000000005";
+        readonly name: "Unverified Player";
+        readonly username: "unverified_player";
+        readonly email: "unverified@playcademy.com";
+        readonly emailVerified: false;
+        readonly image: null;
+        readonly role: "player";
+        readonly developerStatus: "none";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+};
+declare const DEMO_USER: {
+    readonly id: "00000000-0000-0000-0000-000000000001";
+    readonly name: "Player User";
+    readonly username: "player_user";
+    readonly email: "player@playcademy.com";
+    readonly emailVerified: true;
+    readonly image: null;
+    readonly role: "player";
+    readonly developerStatus: "none";
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+};
+
+/**
+ * Demo token mappings for sandbox authentication
+ */
+declare const DEMO_TOKENS: {
+    readonly 'sandbox-demo-token': {
+        readonly id: "00000000-0000-0000-0000-000000000001";
+        readonly name: "Player User";
+        readonly username: "player_user";
+        readonly email: "player@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "player";
+        readonly developerStatus: "none";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly 'sandbox-admin-token': {
+        readonly id: "00000000-0000-0000-0000-000000000003";
+        readonly name: "Admin User";
+        readonly username: "admin_user";
+        readonly email: "admin@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "admin";
+        readonly developerStatus: "approved";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly 'sandbox-player-token': {
+        readonly id: "00000000-0000-0000-0000-000000000001";
+        readonly name: "Player User";
+        readonly username: "player_user";
+        readonly email: "player@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "player";
+        readonly developerStatus: "none";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly 'sandbox-developer-token': {
+        readonly id: "00000000-0000-0000-0000-000000000002";
+        readonly name: "Developer User";
+        readonly username: "developer_user";
+        readonly email: "developer@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "developer";
+        readonly developerStatus: "approved";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly 'sandbox-pending-dev-token': {
+        readonly id: "00000000-0000-0000-0000-000000000004";
+        readonly name: "Pending Developer";
+        readonly username: "pending_dev";
+        readonly email: "pending@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "developer";
+        readonly developerStatus: "pending";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly 'sandbox-unverified-token': {
+        readonly id: "00000000-0000-0000-0000-000000000005";
+        readonly name: "Unverified Player";
+        readonly username: "unverified_player";
+        readonly email: "unverified@playcademy.com";
+        readonly emailVerified: false;
+        readonly image: null;
+        readonly role: "player";
+        readonly developerStatus: "none";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+    readonly 'mock-game-token-for-local-dev': {
+        readonly id: "00000000-0000-0000-0000-000000000001";
+        readonly name: "Player User";
+        readonly username: "player_user";
+        readonly email: "player@playcademy.com";
+        readonly emailVerified: true;
+        readonly image: null;
+        readonly role: "player";
+        readonly developerStatus: "none";
+        readonly createdAt: Date;
+        readonly updatedAt: Date;
+    };
+};
+declare const DEMO_TOKEN = "sandbox-demo-token";
+declare const MOCK_GAME_ID = "mock-game-id-from-template";
+
+/**
+ * Demo items and inventory data for sandbox testing
+ */
+
+declare const PLAYCADEMY_CREDITS_ID: string;
+declare const SAMPLE_ITEMS: Omit<Item, 'createdAt'>[];
+declare const SAMPLE_INVENTORY: {
+    id: string;
+    userId: "00000000-0000-0000-0000-000000000001";
+    itemId: string;
+    quantity: number;
+}[];
+
+export { DEMO_TOKEN, DEMO_TOKENS, DEMO_USER, DEMO_USERS, DEMO_USER_IDS, MOCK_GAME_ID, PLAYCADEMY_CREDITS_ID, SAMPLE_INVENTORY, SAMPLE_ITEMS };

package/dist/constants.js

@@ -0,0 +1,231 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/constants/demo-users.ts
+var now = new Date;
+var DEMO_USER_IDS = {
+  player: "00000000-0000-0000-0000-000000000001",
+  developer: "00000000-0000-0000-0000-000000000002",
+  admin: "00000000-0000-0000-0000-000000000003",
+  pendingDeveloper: "00000000-0000-0000-0000-000000000004",
+  unverifiedPlayer: "00000000-0000-0000-0000-000000000005"
+};
+var DEMO_USERS = {
+  admin: {
+    id: DEMO_USER_IDS.admin,
+    name: "Admin User",
+    username: "admin_user",
+    email: "admin@playcademy.com",
+    emailVerified: true,
+    image: null,
+    role: "admin",
+    developerStatus: "approved",
+    createdAt: now,
+    updatedAt: now
+  },
+  player: {
+    id: DEMO_USER_IDS.player,
+    name: "Player User",
+    username: "player_user",
+    email: "player@playcademy.com",
+    emailVerified: true,
+    image: null,
+    role: "player",
+    developerStatus: "none",
+    createdAt: now,
+    updatedAt: now
+  },
+  developer: {
+    id: DEMO_USER_IDS.developer,
+    name: "Developer User",
+    username: "developer_user",
+    email: "developer@playcademy.com",
+    emailVerified: true,
+    image: null,
+    role: "developer",
+    developerStatus: "approved",
+    createdAt: now,
+    updatedAt: now
+  },
+  pendingDeveloper: {
+    id: DEMO_USER_IDS.pendingDeveloper,
+    name: "Pending Developer",
+    username: "pending_dev",
+    email: "pending@playcademy.com",
+    emailVerified: true,
+    image: null,
+    role: "developer",
+    developerStatus: "pending",
+    createdAt: now,
+    updatedAt: now
+  },
+  unverifiedPlayer: {
+    id: DEMO_USER_IDS.unverifiedPlayer,
+    name: "Unverified Player",
+    username: "unverified_player",
+    email: "unverified@playcademy.com",
+    emailVerified: false,
+    image: null,
+    role: "player",
+    developerStatus: "none",
+    createdAt: now,
+    updatedAt: now
+  }
+};
+var DEMO_USER = DEMO_USERS.player;
+// src/constants/demo-tokens.ts
+var DEMO_TOKENS = {
+  "sandbox-demo-token": DEMO_USERS.player,
+  "sandbox-admin-token": DEMO_USERS.admin,
+  "sandbox-player-token": DEMO_USERS.player,
+  "sandbox-developer-token": DEMO_USERS.developer,
+  "sandbox-pending-dev-token": DEMO_USERS.pendingDeveloper,
+  "sandbox-unverified-token": DEMO_USERS.unverifiedPlayer,
+  "mock-game-token-for-local-dev": DEMO_USERS.player
+};
+var DEMO_TOKEN = "sandbox-demo-token";
+var MOCK_GAME_ID = "mock-game-id-from-template";
+// src/constants/demo-items.ts
+var DEMO_ITEM_IDS = {
+  playcademyCredits: "10000000-0000-0000-0000-000000000001",
+  foundingMemberBadge: "10000000-0000-0000-0000-000000000002",
+  earlyAdopterBadge: "10000000-0000-0000-0000-000000000003",
+  firstGameBadge: "10000000-0000-0000-0000-000000000004",
+  commonSword: "10000000-0000-0000-0000-000000000005",
+  smallHealthPotion: "10000000-0000-0000-0000-000000000006",
+  smallBackpack: "10000000-0000-0000-0000-000000000007"
+};
+var PLAYCADEMY_CREDITS_ID = DEMO_ITEM_IDS.playcademyCredits;
+var SAMPLE_ITEMS = [
+  {
+    id: PLAYCADEMY_CREDITS_ID,
+    slug: "PLAYCADEMY_CREDITS",
+    gameId: null,
+    displayName: "PLAYCADEMY credits",
+    description: "The main currency used across PLAYCADEMY.",
+    type: "currency",
+    isPlaceable: false,
+    imageUrl: "http://playcademy-sandbox.local/playcademy-credit.png",
+    metadata: {
+      rarity: "common"
+    }
+  },
+  {
+    id: DEMO_ITEM_IDS.foundingMemberBadge,
+    slug: "FOUNDING_MEMBER_BADGE",
+    gameId: null,
+    displayName: "Founding Member Badge",
+    description: "Reserved for founding core team of the PLAYCADEMY platform.",
+    type: "badge",
+    isPlaceable: false,
+    imageUrl: null,
+    metadata: {
+      rarity: "legendary"
+    }
+  },
+  {
+    id: DEMO_ITEM_IDS.earlyAdopterBadge,
+    slug: "EARLY_ADOPTER_BADGE",
+    gameId: null,
+    displayName: "Early Adopter Badge",
+    description: "Awarded to users who joined during the beta phase.",
+    type: "badge",
+    isPlaceable: false,
+    imageUrl: null,
+    metadata: {
+      rarity: "epic"
+    }
+  },
+  {
+    id: DEMO_ITEM_IDS.firstGameBadge,
+    slug: "FIRST_GAME_BADGE",
+    gameId: null,
+    displayName: "First Game Played",
+    description: "Awarded for playing your first game in the Playcademy platform.",
+    type: "badge",
+    isPlaceable: false,
+    imageUrl: "http://playcademy-sandbox.local/first-game-badge.png",
+    metadata: {
+      rarity: "uncommon"
+    }
+  },
+  {
+    id: DEMO_ITEM_IDS.commonSword,
+    slug: "COMMON_SWORD",
+    gameId: null,
+    displayName: "Common Sword",
+    description: "A basic sword, good for beginners.",
+    type: "unlock",
+    isPlaceable: false,
+    imageUrl: "http://playcademy-sandbox.local/common-sword.png",
+    metadata: undefined
+  },
+  {
+    id: DEMO_ITEM_IDS.smallHealthPotion,
+    slug: "SMALL_HEALTH_POTION",
+    gameId: null,
+    displayName: "Small Health Potion",
+    description: "Restores a small amount of health.",
+    type: "other",
+    isPlaceable: false,
+    imageUrl: "http://playcademy-sandbox.local/small-health-potion.png",
+    metadata: undefined
+  },
+  {
+    id: DEMO_ITEM_IDS.smallBackpack,
+    slug: "SMALL_BACKPACK",
+    gameId: null,
+    displayName: "Small Backpack",
+    description: "Increases your inventory capacity by 5 slots.",
+    type: "upgrade",
+    isPlaceable: false,
+    imageUrl: "http://playcademy-sandbox.local/small-backpack.png",
+    metadata: undefined
+  }
+];
+var SAMPLE_INVENTORY = [
+  {
+    id: "20000000-0000-0000-0000-000000000001",
+    userId: DEMO_USER.id,
+    itemId: PLAYCADEMY_CREDITS_ID,
+    quantity: 1000
+  }
+];
+export {
+  SAMPLE_ITEMS,
+  SAMPLE_INVENTORY,
+  PLAYCADEMY_CREDITS_ID,
+  MOCK_GAME_ID,
+  DEMO_USER_IDS,
+  DEMO_USERS,
+  DEMO_USER,
+  DEMO_TOKENS,
+  DEMO_TOKEN
+};

package/dist/mocks/timeback.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TimeBack Mock Data
+ *
+ * Pure mock data generators for local development.
+ * Used by route handlers when mock mode is enabled.
+ */
+import type { AuthenticatedUser, GameUser, TimebackStudentProfile, User, UserEnrollment, UserTimebackData } from '@playcademy/data/types';
+import type { DatabaseInstance } from '../types';
+/**
+ * Check if TimeBack should return mock data instead of calling real APIs.
+ * True when timebackId is 'mock' (auto-generated IDs in sandbox).
+ */
+export declare function shouldMockTimeback(): boolean;
+/**
+ * Generate mock student profile from sandbox config.
+ */
+export declare function getMockStudentProfile(): TimebackStudentProfile;
+/**
+ * Generate mock enrollments from seeded game integrations.
+ */
+export declare function getMockEnrollments(db: DatabaseInstance): Promise<UserEnrollment[]>;
+/**
+ * Generate complete mock TimeBack data for a user.
+ */
+export declare function getMockTimebackData(db: DatabaseInstance, timebackId: string, gameId?: string): Promise<UserTimebackData>;
+/**
+ * Build a complete user response with mock timeback data.
+ * Used to bypass api-core when in mock mode (avoids real API calls).
+ */
+export declare function buildMockUserResponse(db: DatabaseInstance, user: User, gameId?: string): Promise<AuthenticatedUser | GameUser>;

package/dist/server.d.ts

@@ -1,11 +1,26 @@
 import * as _playcademy_realtime_server_sandbox from '@playcademy/realtime/server/sandbox';
 import * as _playcademy_realtime_server from '@playcademy/realtime/server';
 import * as _hono_node_server from '@hono/node-server';
+import { TimebackOrgType, TimebackUserRole } from '@playcademy/data/types';
 
 /**
  * Configuration Type Definitions
  */
+
 type TimebackMode = 'local' | 'remote' | 'disabled';
+/**
+ * Organization configuration input for sandbox.
+ * All fields optional since they can be derived from defaults.
+ */
+interface TimebackOrganizationInput {
+    id?: string;
+    name?: string;
+    type?: TimebackOrgType;
+}
+/**
+ * Timeback configuration input for sandbox.
+ * All fields optional since they can be derived from defaults.
+ */
 interface TimebackConfig {
     mode: TimebackMode;
     onerosterApiUrl?: string;
@@ -14,7 +29,9 @@ interface TimebackConfig {
     clientSecret?: string;
     authUrl?: string;
     courseId?: string;
-    studentId?: string;
+    timebackId?: string;
+    organization?: TimebackOrganizationInput;
+    role?: TimebackUserRole;
 }
 
 /**
@@ -296,7 +313,9 @@ declare const version: string;
 declare function startServer(port: number, project?: ProjectInfo, options?: Omit<ServerOptions, 'port' | 'project'>): Promise<{
     main: _hono_node_server.ServerType;
     realtime: Bun.Server<_playcademy_realtime_server.WebSocketData> | _playcademy_realtime_server_sandbox.SandboxRealtimeServer | null;
-    stop: () => void;
+    timebackMode: "local" | "remote" | "mock" | null;
+    setRole: (role: TimebackUserRole) => void;
+    stop: () => Promise<void>;
 }>;
 
 export { startServer, version };