playcademy 0.18.0 → 0.18.2

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

@@ -1,104 +0,0 @@
-/**
- * Health check endpoint
- * Route: GET /api/health
- * Always included in deployed backends
- */
-
-import type { Context } from 'hono'
-
-import type { PlaycademyConfig } from '@playcademy/sdk/server'
-
-import type { RouteMetadata } from '../entry/types'
-import type { HonoEnv, ServerEnv } from '../types'
-
-/**
- * Check if all required environment variables are configured
- */
-function isEnvConfigured(env: ServerEnv): boolean {
-    return (
-        Boolean(env.PLAYCADEMY_API_KEY) && Boolean(env.GAME_ID) && Boolean(env.PLAYCADEMY_BASE_URL)
-    )
-}
-
-/**
- * Get count of configured secrets
- */
-function getSecretsCount(env: ServerEnv): number {
-    return env.secrets ? Object.keys(env.secrets).length : 0
-}
-
-/**
- * Build list of enabled integration names
- */
-function getEnabledIntegrations(config?: PlaycademyConfig): string[] {
-    const enabled: string[] = []
-
-    if (config?.integrations?.timeback) {
-        enabled.push('timeback')
-    }
-
-    if (config?.integrations?.customRoutes) {
-        enabled.push('customRoutes')
-    }
-
-    if (config?.integrations?.database) {
-        enabled.push('database')
-    }
-
-    if (config?.integrations?.kv) {
-        enabled.push('kv')
-    }
-
-    if (config?.integrations?.bucket) {
-        enabled.push('bucket')
-    }
-
-    return enabled
-}
-
-/**
- * Format routes into readable objects with separate path and methods
- */
-function formatRoutes(routes: RouteMetadata[]): { path: string; methods: string[] }[] {
-    return routes.map(r => ({
-        path: r.path,
-        methods: r.methods || ['*'],
-    }))
-}
-
-/**
- * Get TimeBack debug info if applicable
- */
-function getTimebackDebugInfo(config?: PlaycademyConfig) {
-    const timeback = config?.integrations?.timeback
-
-    if (!timeback || !timeback.courses || timeback.courses.length === 0) {
-        return {}
-    }
-
-    const grades = [...new Set(timeback.courses.map(c => c.grade))].toSorted()
-    const subjects = [...new Set(timeback.courses.map(c => c.subject))].toSorted()
-
-    return {
-        timeback: {
-            courseCount: timeback.courses.length,
-            grades,
-            subjects,
-        },
-    }
-}
-
-export async function GET(c: Context<HonoEnv>): Promise<Response> {
-    const config = c.get('config')
-    const routeMetadata = c.get('routeMetadata')
-
-    return c.json({
-        status: 'ok',
-        timestamp: new Date().toISOString(),
-        env: { configured: isEnvConfigured(c.env) },
-        secrets: getSecretsCount(c.env),
-        integrations: getEnabledIntegrations(config),
-        routes: formatRoutes(routeMetadata),
-        ...getTimebackDebugInfo(config),
-    })
-}

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

@@ -1,66 +0,0 @@
-/**
- * Route discovery endpoint
- * Route: GET /api
- * Always included - lists all available routes
- */
-
-import { ROUTES } from '../constants'
-
-import type { Context } from 'hono'
-
-import type { PlaycademyConfig } from '@playcademy/sdk/server'
-
-import type { RouteMetadata } from '../entry/types'
-import type { HonoEnv } from '../types'
-
-interface RouteInfo {
-    path: string
-    methods: string[]
-}
-
-/**
- * Get built-in routes that are always available
- */
-function getBuiltinRoutes(): RouteInfo[] {
-    return [
-        { path: ROUTES.INDEX, methods: ['GET'] },
-        { path: ROUTES.HEALTH, methods: ['GET'] },
-    ]
-}
-
-/**
- * Get TimeBack integration routes if enabled
- */
-function getTimebackRoutes(config?: PlaycademyConfig): RouteInfo[] {
-    if (config?.integrations?.timeback) {
-        return [{ path: ROUTES.TIMEBACK.END_ACTIVITY, methods: ['POST'] }]
-    }
-
-    return []
-}
-
-/**
- * Format custom routes from build-time metadata
- */
-function formatCustomRoutes(routes: RouteMetadata[]): RouteInfo[] {
-    return routes.map(r => ({
-        path: r.path,
-        methods: r.methods || ['*'],
-    }))
-}
-
-export async function GET(c: Context<HonoEnv>): Promise<Response> {
-    const config = c.get('config')
-    const routeMetadata = c.get('routeMetadata')
-
-    const routes = [
-        ...getBuiltinRoutes(),
-        ...getTimebackRoutes(config),
-        ...formatCustomRoutes(routeMetadata),
-    ]
-
-    return c.json({
-        name: config.name,
-        routes,
-    })
-}

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

@@ -1,181 +0,0 @@
-import {
-    buildErrorResponse,
-    isValidGrade,
-    isValidSubject,
-    logError,
-    VALID_GRADES,
-    VALID_SUBJECTS,
-    validateCourseConfig,
-} from '../../../lib'
-
-import type { Context } from 'hono'
-
-import type { PlaycademyConfig } from '@playcademy/sdk/server'
-import type { ActivityData } from '@playcademy/types/timeback'
-
-import type { HonoEnv } from '../../../types'
-
-/**
- * TimeBack integration - End activity and submit results
- * Route: POST /api/integrations/timeback/end-activity
- * Auto-generated when integrations.timeback is configured
- *
- * Flow:
- * 1. Game frontend calls this route on deployed backend ({slug}.playcademy.gg/api/integrations/timeback/end-activity)
- * 2. This route calls Playcademy platform API via SDK (hub.playcademy.net/api/timeback/end-activity)
- * 3. Platform API sends both ActivityEvent and TimeSpent Caliper events to TimeBack
- *
- * This acts as a secure proxy - game developers don't need TimeBack credentials or
- * their own backend infrastructure. The SDK handles config enrichment and metadata.
- */
-
-function getConfig(c: Context<HonoEnv>): PlaycademyConfig {
-    const config = c.get('config')
-    const timebackConfig = config?.integrations?.timeback
-
-    if (!timebackConfig) {
-        throw new Error('TimeBack integration not found')
-    }
-
-    return config
-}
-
-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 (!isValidGrade(body.activityData?.grade)) {
-        return { error: `grade must be a valid grade level (${VALID_GRADES.join(', ')})` }
-    }
-
-    if (!isValidSubject(body.activityData?.subject)) {
-        return { error: `subject must be a valid subject (${VALID_SUBJECTS.join(', ')})` }
-    }
-
-    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 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 sensorUrl = activityData.sensorUrl || new URL(c.req.url).origin
-
-    if (!appName) {
-        return { error: 'App name is required (missing from activityData and config)' }
-    }
-
-    if (!sensorUrl) {
-        return { error: 'Sensor URL is required' }
-    }
-
-    return { data: { ...activityData, appName, sensorUrl } }
-}
-
-export async function POST(c: Context<HonoEnv>): Promise<Response> {
-    try {
-        // 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) {
-            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, masteredUnits } = await c.req.json()
-
-        // 4. Validate required fields
-        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
-        const config = getConfig(c)
-
-        // 6. Validate grade/subject against configured courses
-        const { grade, subject } = activityData
-        const courseValidationError = validateCourseConfig({ 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')
-
-        // 9. End activity (SDK calculates XP server-side with attempt tracking)
-        const result = await sdk.timeback.endActivity(user.timeback_id, {
-            activityData: enrichResult.data,
-            scoreData,
-            timingData,
-            xpEarned,
-            masteredUnits,
-        })
-
-        return c.json(result)
-    } catch (error) {
-        logError('TimeBack End Activity', error)
-
-        return c.json(buildErrorResponse(c, error, 'Failed to end activity'), 500)
-    }
-}

package/dist/edge-play/src/routes/integrations/timeback/get-xp.ts

@@ -1,159 +0,0 @@
-import {
-    buildErrorResponse,
-    isValidGrade,
-    isValidSubject,
-    logError,
-    VALID_GRADES,
-    VALID_SUBJECTS,
-    validateCourseConfig,
-} from '../../../lib'
-
-import type { Context } from 'hono'
-
-import type { PlaycademyConfig } from '@playcademy/sdk/server'
-
-import type { HonoEnv } from '../../../types'
-
-/**
- * TimeBack integration - Get student XP
- * Route: GET /api/integrations/timeback/xp
- * Auto-generated when integrations.timeback is configured
- *
- * Flow:
- * 1. Game frontend calls this route on deployed backend ({slug}.playcademy.gg/api/integrations/timeback/xp)
- * 2. This route calls Playcademy platform API via SDK (hub.playcademy.net/api/timeback/student-xp/:timebackId)
- * 3. Platform API fetches XP data from TimeBack EduBridge analytics API
- *
- * By default, returns XP for all courses configured for this game/app.
- * Use `grade` and `subject` to query a specific course instead.
- *
- * Query Parameters:
- *
- * @param {number} [grade] - Grade level to filter (-1 to 13).
- *   Must be used together with `subject`.
- *   Example: `?grade=3&subject=Math`
- *
- * @param {string} [subject] - Subject to filter.
- *   Must be used together with `grade`.
- *   Valid values: Reading, Language, Vocabulary, Social Studies, Writing, Science, FastMath, Math, None
- *   Example: `?grade=3&subject=Math`
- *
- * @param {string} [include] - Comma-separated list of additional data to include.
- *   Available options:
- *   - `perCourse` - Include per-course XP breakdown with grade, subject, and xp
- *   - `today` - Include today's XP (both total and per-course if perCourse is set)
- *   Example: `?include=perCourse,today`
- *
- * Response:
- * ```json
- * {
- *   "totalXp": 1500,
- *   "todayXp": 50,           // Only if include contains 'today'
- *   "courses": [              // Only if include contains 'perCourse'
- *     {
- *       "grade": 3,
- *       "subject": "Math",
- *       "title": "Math Grade 3",
- *       "totalXp": 1000,
- *       "todayXp": 30        // Only if include contains 'today'
- *     }
- *   ]
- * }
- * ```
- */
-
-/**
- * Get config and validate that the game has TimeBack configured.
- */
-function getConfig(c: Context<HonoEnv>): PlaycademyConfig {
-    const config = c.get('config')
-    const timebackConfig = config?.integrations?.timeback
-
-    if (!timebackConfig) {
-        throw new Error('TimeBack integration not found')
-    }
-
-    return config
-}
-
-export async function GET(c: Context<HonoEnv>): Promise<Response> {
-    try {
-        // 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) {
-            const message = 'User does not have TimeBack integration'
-
-            console.error('[TimeBack Get XP] Error:', message)
-
-            return c.json({ error: message }, 400)
-        }
-
-        // 3. Validate TimeBack is configured for this game
-        const config = getConfig(c)
-
-        // 4. Parse query parameters
-        const url = new URL(c.req.url)
-        const gradeParam = url.searchParams.get('grade')
-        const subjectParam = url.searchParams.get('subject')
-        const includeParam = url.searchParams.get('include')
-        const include = includeParam
-            ? (includeParam.split(',').map(s => s.trim()) as ('perCourse' | 'today')[])
-            : undefined
-
-        let grade: number | undefined
-        let subject: string | undefined
-
-        if (gradeParam !== null || subjectParam !== null) {
-            if (gradeParam === null || subjectParam === null) {
-                return c.json({ error: 'Both grade and subject must be provided together' }, 400)
-            }
-
-            grade = parseInt(gradeParam, 10)
-            subject = subjectParam
-
-            if (!isValidGrade(grade)) {
-                return c.json(
-                    { error: `grade must be a valid grade level (${VALID_GRADES.join(', ')})` },
-                    400,
-                )
-            }
-
-            if (!isValidSubject(subject)) {
-                return c.json(
-                    { error: `subject must be a valid subject (${VALID_SUBJECTS.join(', ')})` },
-                    400,
-                )
-            }
-
-            // 5. Validate grade/subject against configured courses
-            const courseValidationError = validateCourseConfig({ grade, subject, config })
-
-            if (courseValidationError) {
-                return c.json({ error: courseValidationError.error }, 400)
-            }
-        }
-
-        // 6. Get SDK client from context
-        const sdk = c.get('sdk')
-
-        // 7. Fetch student XP from platform API
-        // The SDK automatically passes gameId, so XP is filtered to this game's courses
-        const result = await sdk.timeback.getStudentXp(user.timeback_id, {
-            grade,
-            subject,
-            include,
-        })
-
-        return c.json(result)
-    } catch (error) {
-        logError('TimeBack Get XP', error)
-
-        return c.json(buildErrorResponse(c, error, 'Failed to get XP'), 500)
-    }
-}