playcademy 0.14.18 → 0.14.19-alpha.2

package/README.md

@@ -213,6 +213,26 @@ Credentials are stored in `~/.playcademy/auth.json`:
 
 Set up TimeBack LTI integration for your game.
 
+**Note:** Before running this command, ensure that `totalXp` is configured for each course in your `playcademy.config.js`:
+
+```js
+integrations: {
+    timeback: {
+        courses: [
+            {
+                subject: 'Math',
+                grade: 3,
+                metadata: {
+                    metrics: {
+                        totalXp: 1000, // Required
+                    },
+                },
+            },
+        ]
+    }
+}
+```
+
 ```bash
 playcademy timeback setup
 playcademy timeback setup --dry-run

package/dist/constants.d.ts

@@ -278,7 +278,7 @@ declare const CLI_FILES: {
 declare const DEFAULT_PORTS: {
     /** Sandbox server (mock platform API) */
     readonly SANDBOX: 4321;
-    /** Backend dev server (game backend with HMR) */
+    /** Backend dev server (project backend with HMR) */
     readonly BACKEND: 8788;
 };
 

package/dist/constants.js

@@ -31,7 +31,6 @@ var package_default = {
     sharp: "^0.34.2",
     typedoc: "^0.28.5",
     "typedoc-plugin-markdown": "^4.7.0",
-    "typedoc-vitepress-theme": "^1.1.2",
     "typescript-eslint": "^8.30.1",
     "yocto-spinner": "^0.2.2"
   },
@@ -255,7 +254,7 @@ var CLI_FILES = {
 var DEFAULT_PORTS = {
   /** Sandbox server (mock platform API) */
   SANDBOX: 4321,
-  /** Backend dev server (game backend with HMR) */
+  /** Backend dev server (project backend with HMR) */
   BACKEND: 8788
 };
 

package/dist/db.js

@@ -1458,7 +1458,6 @@ var package_default = {
     sharp: "^0.34.2",
     typedoc: "^0.28.5",
     "typedoc-plugin-markdown": "^4.7.0",
-    "typedoc-vitepress-theme": "^1.1.2",
     "typescript-eslint": "^8.30.1",
     "yocto-spinner": "^0.2.2"
   },
@@ -2017,7 +2016,7 @@ function getRunCommand(pm, script) {
 }
 
 // src/lib/core/client.ts
-import { PlaycademyClient } from "@playcademy/sdk";
+import { PlaycademyClient } from "@playcademy/sdk/internal";
 
 // src/lib/core/context.ts
 var context = {};
@@ -2043,7 +2042,7 @@ import {
   gray,
   green,
   greenBright,
-  red as red2,
+  red,
   yellow,
   yellowBright
 } from "colorette";
@@ -2636,34 +2635,77 @@ var eraseLine = ESC + "2K";
 import colors3 from "yoctocolors-cjs";
 
 // src/lib/core/error.ts
-import { bold as bold2, dim as dim2, red } from "colorette";
-import { ApiError, extractApiErrorInfo } from "@playcademy/sdk";
+import { bold as bold2, dim as dim2, redBright } from "colorette";
+import { ApiError, extractApiErrorInfo } from "@playcademy/sdk/internal";
 function isConfigError(error) {
   return error !== null && typeof error === "object" && "name" in error && error.name === "ConfigError" && "message" in error;
 }
+function extractEmbeddedJson(message) {
+  const jsonMatch = message.match(/(\{.+\})$/);
+  if (!jsonMatch) {
+    return { cleanMessage: message };
+  }
+  try {
+    const json = JSON.parse(jsonMatch[1]);
+    const cleanMessage = message.slice(0, jsonMatch.index).trim();
+    return { cleanMessage, json };
+  } catch {
+    return { cleanMessage: message };
+  }
+}
+function cleanMessageSuffix(message) {
+  let cleaned = message.replace(/:\s*\d{3}\s*$/, "").trim();
+  if (cleaned.endsWith(":")) {
+    cleaned = cleaned.slice(0, -1).trim();
+  }
+  return cleaned;
+}
+function removeStatusPrefix(message, statusCode) {
+  if (message.startsWith(`${statusCode} `)) {
+    return message.slice(`${statusCode} `.length);
+  }
+  return message;
+}
 function displayApiError(error, indent) {
   const spaces = "  ".repeat(indent);
   const errorInfo = extractApiErrorInfo(error);
-  if (errorInfo) {
-    console.error(`${spaces}${red("\u2716")} ${bold2(`API Error: ${errorInfo.statusText}`)}`);
-    console.error("");
-    if (errorInfo.message) {
-      console.error(`${spaces}  ${errorInfo.message}`);
-    } else if (errorInfo.error) {
-      console.error(`${spaces}  ${errorInfo.error}`);
+  if (!errorInfo) {
+    console.error(`${spaces}${redBright("\u2716")} ${bold2(error.message)}`);
+    if (process.env.DEBUG && error.details) {
+      console.error("");
+      logger.json(error.details, indent + 1);
+    }
+    return;
+  }
+  const statusCode = errorInfo.status;
+  let displayMessage = errorInfo.statusText;
+  displayMessage = removeStatusPrefix(displayMessage, statusCode);
+  const { cleanMessage, json: embeddedJson } = extractEmbeddedJson(displayMessage);
+  displayMessage = cleanMessageSuffix(cleanMessage);
+  let errorCode;
+  if (error.details && typeof error.details === "object") {
+    const details = error.details;
+    if ("code" in details && typeof details.code === "string") {
+      errorCode = details.code;
     }
-    if (errorInfo.details) {
-      console.error(
-        `${spaces}  ${dim2("Details:")} ${JSON.stringify(errorInfo.details, null, 2)}`
-      );
+  }
+  let errorHeader = "API Error";
+  if (errorCode) {
+    errorHeader += ` ${redBright(`[${errorCode}]`)}`;
+  }
+  errorHeader += `: ${displayMessage} ${redBright(`[${statusCode}]`)}`;
+  console.error(`${spaces}${redBright("\u2716")} ${bold2(errorHeader)}`);
+  if (process.env.DEBUG) {
+    const detailsToShow = embeddedJson || error.details || errorInfo.details;
+    if (detailsToShow) {
+      console.error("");
+      logger.json(detailsToShow, indent + 1);
     }
-  } else {
-    console.error(`${spaces}${red("\u2716")} ${bold2(error.message)}`);
   }
 }
 function displayConfigError(error, indent) {
   const spaces = "  ".repeat(indent);
-  console.error(`${spaces}${red("\u2716")} ${bold2(error.message)}`);
+  console.error(`${spaces}${redBright("\u2716")} ${bold2(error.message)}`);
   if (error.field) {
     console.error(`${spaces}  ${dim2("Field:")} ${error.field}`);
   }
@@ -2673,7 +2715,7 @@ function displayConfigError(error, indent) {
 }
 function displayGenericError(error, indent) {
   const spaces = "  ".repeat(indent);
-  console.error(`${spaces}${red("\u2716")} ${bold2(error.message)}`);
+  console.error(`${spaces}${redBright("\u2716")} ${bold2(error.message)}`);
   if (error.stack && process.env.DEBUG) {
     console.error(`${spaces}  ${dim2("Stack:")}`);
     console.error(
@@ -2695,7 +2737,7 @@ function formatError(error, indent = 0) {
     displayGenericError(error, indent);
     return;
   }
-  console.error(`${spaces}${red("\u2716")} ${bold2(String(error))}`);
+  console.error(`${spaces}${redBright("\u2716")} ${bold2(String(error))}`);
 }
 
 // src/lib/core/logger.ts
@@ -2706,12 +2748,20 @@ function customTransform(text) {
   return result;
 }
 function formatTable(data, title) {
+  const ANSI_REGEX = /\u001B\[[0-9;]*m/g;
+  const stripAnsi2 = (value) => value.replace(ANSI_REGEX, "");
+  const visibleLength = (value) => stripAnsi2(value).length;
+  const padCell = (value, width) => {
+    const length = visibleLength(value);
+    if (length >= width) return value;
+    return value + " ".repeat(width - length);
+  };
   if (data.length === 0) return;
   const keys = Object.keys(data[0]);
   const rows = data.map((item) => keys.map((key) => String(item[key] ?? "")));
   const widths = keys.map((key, i) => {
-    const headerWidth = key.length;
-    const dataWidth = Math.max(...rows.map((row) => row[i].length));
+    const headerWidth = visibleLength(key);
+    const dataWidth = Math.max(...rows.map((row) => visibleLength(row[i])));
     return Math.max(headerWidth, dataWidth);
   });
   const totalWidth = widths.reduce((sum, w) => sum + w + 3, -1);
@@ -2727,11 +2777,11 @@ function formatTable(data, title) {
     console.log(titleRow);
     console.log(titleSeparator);
   }
-  const header = "\u2502 " + keys.map((key, i) => key.padEnd(widths[i])).join(" \u2502 ") + " \u2502";
+  const header = "\u2502 " + keys.map((key, i) => padCell(key, widths[i])).join(" \u2502 ") + " \u2502";
   console.log(header);
   console.log(separator);
   rows.forEach((row) => {
-    const dataRow = "\u2502 " + row.map((cell, i) => cell.padEnd(widths[i])).join(" \u2502 ") + " \u2502";
+    const dataRow = "\u2502 " + row.map((cell, i) => padCell(cell, widths[i])).join(" \u2502 ") + " \u2502";
     console.log(dataRow);
   });
   console.log(bottomBorder);
@@ -2790,7 +2840,7 @@ var logger = {
    */
   error: (message, indent = 0) => {
     const spaces = "  ".repeat(indent);
-    console.error(`${spaces}${red2("\u2716")} ${customTransform(message)}`);
+    console.error(`${spaces}${red("\u2716")} ${customTransform(message)}`);
   },
   bold: (message, indent = 0) => {
     const spaces = "  ".repeat(indent);
@@ -2858,7 +2908,7 @@ var logger = {
     const oldSize = formatSize(previousSize);
     const newSize = formatSize(currentSize);
     const delta = dim3(`(${formatDelta(currentSize - previousSize)})`);
-    const value = `${red2(oldSize)} \u2192 ${green(newSize)}  ${delta}`;
+    const value = `${red(oldSize)} \u2192 ${green(newSize)}  ${delta}`;
     console.log(`${spaces}${dim3(label + ":")} ${bold3(value)}`);
   },
   /**

package/dist/edge-play/src/register-routes.ts

@@ -33,6 +33,13 @@ export async function registerBuiltinRoutes(app: Hono<HonoEnv>, integrations?: I
         ])
         app.post(ROUTES.TIMEBACK.END_ACTIVITY, endActivity.POST)
         // ... other routes
+    } else if (integrations?.timeback === null) {
+        app.post('/api/integrations/timeback/end-activity', async c => {
+            return c.json({
+                status: 'ok',
+                __playcademyDevWarning: 'timeback-not-configured',
+            })
+        })
     }
 
     // TODO: Auth integration

package/dist/edge-play/src/routes/health.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Context } from 'hono'
-import type { PlaycademyClient, PlaycademyConfig } from '@playcademy/sdk/server'
+import type { PlaycademyConfig } from '@playcademy/sdk/server'
 import type { RouteMetadata } from '../entry/types'
 import type { HonoEnv, ServerEnv } from '../types'
 
@@ -49,16 +49,27 @@ function formatRoutes(routes: RouteMetadata[]): Array<{ path: string; methods: s
 /**
  * Get TimeBack debug info if applicable
  */
-function getTimebackDebugInfo(config?: PlaycademyConfig, sdk?: PlaycademyClient) {
-    if (config?.integrations?.timeback && sdk?.timeback?.courseId) {
-        return { timeback: { courseId: sdk.timeback.courseId } }
+function getTimebackDebugInfo(config?: PlaycademyConfig) {
+    const timeback = config?.integrations?.timeback
+
+    if (!timeback || !timeback.courses || timeback.courses.length === 0) {
+        return {}
+    }
+
+    const grades = Array.from(new Set(timeback.courses.map(c => c.grade))).sort()
+    const subjects = Array.from(new Set(timeback.courses.map(c => c.subject))).sort()
+
+    return {
+        timeback: {
+            courseCount: timeback.courses.length,
+            grades,
+            subjects,
+        },
     }
-    return {}
 }
 
 export async function GET(c: Context<HonoEnv>): Promise<Response> {
     const config = c.get('config')
-    const sdk = c.get('sdk')
     const routeMetadata = c.get('routeMetadata')
 
     return c.json({
@@ -68,6 +79,6 @@ export async function GET(c: Context<HonoEnv>): Promise<Response> {
         secrets: getSecretsCount(c.env),
         integrations: getEnabledIntegrations(config),
         routes: formatRoutes(routeMetadata),
-        ...getTimebackDebugInfo(config, sdk),
+        ...getTimebackDebugInfo(config),
     })
 }

package/dist/edge-play/src/routes/integrations/timeback/end-activity.ts

@@ -1,5 +1,3 @@
-import { verifyGameToken } from '@playcademy/sdk/server'
-
 import type { Context } from 'hono'
 import type { PlaycademyConfig } from '@playcademy/sdk/server'
 import type { ActivityData } from '@playcademy/timeback/types'
@@ -26,82 +24,148 @@ function getConfig(c: Context<HonoEnv>): PlaycademyConfig {
     return config
 }
 
-function enrichActivityData(
-    activityData: ActivityData,
-    config: PlaycademyConfig,
-    c: Context<HonoEnv>,
-): ActivityData {
+function validateRequestBody(body: {
+    activityData?: ActivityData
+    scoreData?: { correctQuestions?: number; totalQuestions?: number }
+    timingData?: { durationSeconds?: number }
+    masteredUnits?: number
+}): { error: string } | null {
+    if (!body.activityData?.activityId) {
+        return { error: 'activityId is required' }
+    }
+    if (!body.activityData?.grade) {
+        return { error: 'grade is required' }
+    }
+    if (!body.activityData?.subject) {
+        return { error: 'subject is required' }
+    }
+    if (
+        typeof body.scoreData?.correctQuestions !== 'number' ||
+        typeof body.scoreData?.totalQuestions !== 'number'
+    ) {
+        return { error: 'correctQuestions and totalQuestions are required' }
+    }
+    if (typeof body.timingData?.durationSeconds !== 'number') {
+        return { error: 'durationSeconds is required' }
+    }
+    if (
+        body.masteredUnits !== undefined &&
+        (typeof body.masteredUnits !== 'number' || body.masteredUnits < 0)
+    ) {
+        return { error: 'masteredUnits must be a non-negative number when provided' }
+    }
+    return null
+}
+
+function validateCourse(params: {
+    grade: number
+    subject: string
+    config: PlaycademyConfig
+}): { error: string } | null {
+    const { grade, subject, config } = params
+    const timebackConfig = config.integrations?.timeback
+    const configuredCourse = timebackConfig?.courses?.find(
+        course => course.grade === grade && course.subject === subject,
+    )
+    if (!configuredCourse) {
+        const configured = timebackConfig?.courses
+            ?.map(c => `${c.subject} (Grade ${c.grade})`)
+            .join(', ')
+        return {
+            error: `Invalid grade/subject combination: ${subject} (Grade ${grade}). Configured courses: ${configured || 'none'}`,
+        }
+    }
+    return null
+}
+
+function enrichActivityData(params: {
+    activityData: ActivityData
+    config: PlaycademyConfig
+    c: Context<HonoEnv>
+}): { data?: ActivityData; error?: string } {
+    const { activityData, config, c } = params
     const appName = activityData.appName || config?.name
-    const subject =
-        activityData.subject ||
-        config?.integrations?.timeback?.course?.defaultSubject ||
-        config?.integrations?.timeback?.course?.subjects?.[0]
     const sensorUrl = activityData.sensorUrl || new URL(c.req.url).origin
 
-    if (!appName) throw new Error('App name is required')
-    if (!subject) throw new Error('Subject is required')
-    if (!sensorUrl) throw new Error('Sensor URL is required')
+    if (!appName) {
+        return { error: 'App name is required (missing from activityData and config)' }
+    }
+    if (!sensorUrl) {
+        return { error: 'Sensor URL is required' }
+    }
 
-    return { ...activityData, appName, subject, sensorUrl }
+    return { data: { ...activityData, appName, sensorUrl } }
 }
 
 export async function POST(c: Context<HonoEnv>): Promise<Response> {
     try {
-        // 1. Verify game token from frontend (calls platform API for verification)
-        const token = c.req.header('Authorization')?.replace('Bearer ', '')
-        if (!token) {
-            return c.json({ error: 'Unauthorized' }, 401)
-        }
-
-        const { user } = await verifyGameToken(token, { baseUrl: c.env.PLAYCADEMY_BASE_URL })
+        // 1. Get authenticated user from middleware
+        const user = c.get('playcademyUser')
+        if (!user) return c.json({ error: 'Unauthorized' }, 401)
 
         // 2. Ensure user has TimeBack integration
         if (!user.timeback_id) {
-            return c.json({ error: 'User does not have TimeBack integration' }, 400)
+            const message = 'User does not have TimeBack integration'
+            console.error('[TimeBack End Activity] Error:', message)
+            return c.json({ error: message }, 400)
         }
 
         // 3. Parse request body
-        const { activityData, scoreData, timingData, xpEarned } = await c.req.json()
+        const { activityData, scoreData, timingData, xpEarned, masteredUnits } = await c.req.json()
 
         // 4. Validate required fields
-        if (!activityData?.activityId) {
-            return c.json({ error: 'activityId is required' }, 400)
-        }
-        if (
-            typeof scoreData?.correctQuestions !== 'number' ||
-            typeof scoreData?.totalQuestions !== 'number'
-        ) {
-            return c.json({ error: 'correctQuestions and totalQuestions are required' }, 400)
-        }
-        if (typeof timingData?.durationSeconds !== 'number') {
-            return c.json({ error: 'durationSeconds is required' }, 400)
+        const bodyValidationError = validateRequestBody({
+            activityData,
+            scoreData,
+            timingData,
+            masteredUnits,
+        })
+
+        if (bodyValidationError) {
+            const message = bodyValidationError.error
+            console.error('[TimeBack End Activity] Error:', message)
+            return c.json({ error: message }, 400)
         }
 
-        // 5. Get config and enrich activity data with required Caliper fields
+        // 5. Get config
         const config = getConfig(c)
-        const enrichedActivityData = enrichActivityData(activityData, config, c)
 
-        // 6. Get SDK client from context (initialized once per Worker, reused across requests)
+        // 6. Validate grade/subject against configured courses
+        const { grade, subject } = activityData
+        const courseValidationError = validateCourse({ grade, subject, config })
+
+        if (courseValidationError) {
+            const message = courseValidationError.error
+            console.error('[TimeBack End Activity] Error:', message)
+            return c.json({ error: message }, 400)
+        }
+
+        // 7. Enrich activity data with required Caliper fields
+        const enrichResult = enrichActivityData({ activityData, config, c })
+
+        if (!enrichResult.data) {
+            console.error('[TimeBack End Activity] Error:', enrichResult.error)
+            return c.json({ error: enrichResult.error }, 500)
+        }
+
+        // 8. Get SDK client from context (initialized once per Worker, reused across requests)
         const sdk = c.get('sdk')
 
-        // 7. End activity (SDK calculates XP server-side with attempt tracking)
+        // 9. End activity (SDK calculates XP server-side with attempt tracking)
         const result = await sdk.timeback.endActivity(user.timeback_id, {
-            activityData: enrichedActivityData,
+            activityData: enrichResult.data,
             scoreData,
             timingData,
             xpEarned,
+            masteredUnits,
         })
 
         return c.json(result)
     } catch (error) {
-        console.error('[TimeBack End Activity] Error:', error)
-        return c.json(
-            {
-                error: 'Failed to end activity',
-                message: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-            },
-            500,
-        )
+        const message = error instanceof Error ? error.message : String(error)
+        const stack = error instanceof Error ? error.stack : undefined
+        if (message) console.error('[TimeBack End Activity] Error:', message)
+        if (stack) console.error('[TimeBack End Activity] Stack:', stack)
+        return c.json({ error: 'Failed to end activity', message, stack }, 500)
     }
 }

package/dist/edge-play/src/types.ts

@@ -7,6 +7,7 @@
 
 /// <reference types="@cloudflare/workers-types" />
 
+import type { UserInfo } from '@playcademy/data/types'
 import type { PlaycademyClient, PlaycademyConfig } from '@playcademy/sdk/server'
 import type { RouteMetadata } from './entry/types'
 
@@ -70,6 +71,7 @@ export interface HonoVariables {
     sdk: PlaycademyClient
     config: PlaycademyConfig
     routeMetadata: Array<RouteMetadata>
+    playcademyUser?: UserInfo
     [key: string]: unknown
 }