playcademy 0.14.19 → 0.14.20

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 = {};
@@ -2637,7 +2636,7 @@ import colors3 from "yoctocolors-cjs";
 
 // src/lib/core/error.ts
 import { bold as bold2, dim as dim2, redBright } from "colorette";
-import { ApiError, extractApiErrorInfo } from "@playcademy/sdk";
+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;
 }
@@ -2749,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);
@@ -2770,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);

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
 }
 

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { UserInfo, ApiKey } from '@playcademy/data/types';
+export { TimebackCourseConfig } from '@playcademy/data/types';
 import { SchemaInfo } from '@playcademy/cloudflare';
-import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
-export { ComponentConfig, ComponentResourceConfig, CourseConfig, DerivedComponentConfig, DerivedComponentResourceConfig, DerivedCourseConfig, DerivedOrganizationConfig, DerivedResourceConfig, DerivedTimebackConfig, OrganizationConfig, ResourceConfig, TimebackGrade, TimebackSourcedIds, TimebackSubject } from '@playcademy/timeback/types';
-import { PlaycademyClient } from '@playcademy/sdk';
+import { CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
+export { ComponentConfig, ComponentResourceConfig, OrganizationConfig, ResourceConfig, TimebackGrade, TimebackSourcedIds, TimebackSubject } from '@playcademy/timeback/types';
+import { PlaycademyClient } from '@playcademy/sdk/internal';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 
 /**
@@ -243,6 +244,20 @@ interface BulkCollectionResult {
     totalSize: number;
 }
 
+/**
+ * Minimal course configuration for TimeBack integration (used in user-facing config).
+ *
+ * NOTE: Per-course overrides (title, courseCode, level, metadata) are defined
+ * in @playcademy/sdk/server as TimebackCourseConfigWithOverrides.
+ * This base type only includes the minimal required fields.
+ *
+ * For totalXp, use metadata.metrics.totalXp (aligns with upstream TimeBack structure).
+ */
+type TimebackCourseConfig = {
+    subject: string;
+    grade: number;
+};
+
 /**
  * @fileoverview Server SDK Type Definitions
  *
@@ -251,20 +266,50 @@ interface BulkCollectionResult {
  */
 
 /**
- * TimeBack integration configuration for Playcademy config file
+ * Base configuration for TimeBack integration (shared across all courses).
+ * References upstream TimeBack types from @playcademy/timeback.
+ *
+ * All fields are optional and support template variables: {grade}, {subject}, {gameSlug}
  */
-interface TimebackIntegrationConfig {
-    /** Organization overrides */
+interface TimebackBaseConfig {
+    /** Organization configuration (shared across all courses) */
     organization?: Partial<OrganizationConfig>;
-    /** Course configuration (subjects and grades REQUIRED) */
-    course: CourseConfig;
-    /** Component overrides */
+    /** Course defaults (can be overridden per-course) */
+    course?: Partial<CourseConfig>;
+    /** Component defaults */
     component?: Partial<ComponentConfig>;
-    /** Resource overrides */
+    /** Resource defaults */
     resource?: Partial<ResourceConfig>;
-    /** Component-Resource link overrides */
+    /** ComponentResource defaults */
     componentResource?: Partial<ComponentResourceConfig>;
 }
+/**
+ * Extended course configuration that merges TimebackCourseConfig with per-course overrides.
+ * Used in playcademy.config.* to allow per-course customization.
+ */
+interface TimebackCourseConfigWithOverrides extends TimebackCourseConfig {
+    title?: string;
+    courseCode?: string;
+    level?: string;
+    metadata?: CourseConfig['metadata'];
+    totalXp?: number | null;
+    masterableUnits?: number | null;
+}
+/**
+ * TimeBack integration configuration for Playcademy config file.
+ *
+ * Supports two levels of customization:
+ * 1. `base`: Shared defaults for all courses (organization, course, component, resource, componentResource)
+ * 2. Per-course overrides in the `courses` array (title, courseCode, level, gradingScheme, metadata)
+ *
+ * Template variables ({grade}, {subject}, {gameSlug}) can be used in string fields.
+ */
+interface TimebackIntegrationConfig {
+    /** Multi-grade course configuration (array of grade/subject/totalXp with optional per-course overrides) */
+    courses: TimebackCourseConfigWithOverrides[];
+    /** Optional base configuration (shared across all courses, can be overridden per-course) */
+    base?: TimebackBaseConfig;
+}
 /**
  * Custom API routes integration
  */
@@ -285,7 +330,7 @@ interface DatabaseIntegration {
  */
 interface IntegrationsConfig {
     /** TimeBack integration (optional) */
-    timeback?: TimebackIntegrationConfig;
+    timeback?: TimebackIntegrationConfig | null;
     /** Custom API routes (optional) */
     customRoutes?: CustomRoutesIntegration | boolean;
     /** Database (optional) */
@@ -653,7 +698,7 @@ interface IntegrationChangeDetector<TConfig = unknown> {
      * Called automatically during deployment when metadata has changed
      * Implementation should: fetch current config, detect changes, update if needed
      *
-     * @param gameId - The game ID
+     * @param gameId - The project ID
      * @param client - Playcademy API client
      * @param localConfig - Full local PlaycademyConfig
      * @param verbose - Verbose logging flag
@@ -801,17 +846,17 @@ interface DeploymentResult {
 /**
  * Deployment configuration
  *
- * Configuration for deploying a game to Playcademy.
+ * Configuration for deploying a project to Playcademy.
  * Can be provided via CLI options, playcademy.json file, or package.json.
  */
 interface DeployConfig {
-    /** Game slug (URL-friendly identifier) */
+    /** Project slug (URL-friendly identifier) */
     slug?: string;
-    /** Display name for the game */
+    /** Display name for the project */
     displayName?: string;
-    /** Game description */
+    /** Project description */
     description?: string;
-    /** Emoji icon for the game */
+    /** Emoji icon for the project */
     emoji?: string;
     /** Path to the build directory or zip file */
     buildPath?: string;
@@ -935,6 +980,21 @@ interface CallbackServerResult {
     error?: string;
 }
 
+/**
+ * @fileoverview Config Loader Types
+ *
+ * Types for the config loader functionality.
+ */
+
+/**
+ * Result of loading config with path information
+ */
+interface LoadConfigResult {
+    config: PlaycademyConfig;
+    configPath: string;
+    configDir: string;
+}
+
 /**
  * Preview options
  */
@@ -1083,4 +1143,4 @@ interface KeyMetadata {
     valueType?: 'json' | 'string';
 }
 
-export type { ApiConfig, ApiErrorResponse, ApiKeyListItem, ApiKeyWithSecret, ApiRequestOptions, AuthProfile, AuthStore, AuthStrategy, BackendBundle, BackendDeploymentMetadata, BackendDiff, BackendFeatures, BucketBulkOptions, BucketDeleteOptions, BucketGetOptions, BucketListOptions, BucketPutOptions, BuildDiff, BulkCollectionResult, BundleOptions, CallbackServerResult, CollectedFile, ConfigDiff, CreateApiKeyResponse, CustomRoutesIntegrationOptions, DatabaseIntegrationOptions, DeployConfig, DeployNewGameOptions, DeployedGameInfo, DeploymentChanges, DeploymentContext, DeploymentDiffOptions, DeploymentPlan, DeploymentResult, DevServerOptions, EmbeddedSourcePaths, EnvironmentAuthProfiles, GameStore, IntegrationChangeDetector, IntegrationChangeDetectors, IntegrationConfigChange, IntegrationsConfig, IntegrationsDiff, KeyMetadata, KeyStats, LoginCredentials, LoginResponse, PlaycademyConfig, PluginLogger, PreviewOptions, PreviewResponse, SecretsDiff, SignInResponse, SsoCallbackData, TimebackIntegrationConfig, TokenType, UpdateExistingGameOptions };
+export type { ApiConfig, ApiErrorResponse, ApiKeyListItem, ApiKeyWithSecret, ApiRequestOptions, AuthProfile, AuthStore, AuthStrategy, BackendBundle, BackendDeploymentMetadata, BackendDiff, BackendFeatures, BucketBulkOptions, BucketDeleteOptions, BucketGetOptions, BucketListOptions, BucketPutOptions, BuildDiff, BulkCollectionResult, BundleOptions, CallbackServerResult, CollectedFile, ConfigDiff, CreateApiKeyResponse, CustomRoutesIntegrationOptions, DatabaseIntegrationOptions, DeployConfig, DeployNewGameOptions, DeployedGameInfo, DeploymentChanges, DeploymentContext, DeploymentDiffOptions, DeploymentPlan, DeploymentResult, DevServerOptions, EmbeddedSourcePaths, EnvironmentAuthProfiles, GameStore, IntegrationChangeDetector, IntegrationChangeDetectors, IntegrationConfigChange, IntegrationsConfig, IntegrationsDiff, KeyMetadata, KeyStats, LoadConfigResult, LoginCredentials, LoginResponse, PlaycademyConfig, PluginLogger, PreviewOptions, PreviewResponse, SecretsDiff, SignInResponse, SsoCallbackData, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackIntegrationConfig, TokenType, UpdateExistingGameOptions };