playcademy 0.18.0 → 0.18.2

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

@@ -1,3 +0,0 @@
-export * from './errors'
-export * from './self-dispatch'
-export * from './validation'

package/dist/edge-play/src/lib/self-dispatch.test.ts

@@ -1,244 +0,0 @@
-import { beforeEach, describe, expect, it, mock } from 'bun:test'
-
-import {
-    normalizeSelfFetchInput,
-    resolveRawSelfWorker,
-    wrapSelfWorkerWithPathResolution,
-} from './self-dispatch'
-
-import type { HonoEnv, SelfWorker } from '../types'
-
-describe('normalizeSelfFetchInput', () => {
-    const requestUrl = 'https://vocabulon-staging.playcademy.gg/api/admin/genai/sprint'
-
-    it('resolves root-relative paths to the current origin', () => {
-        const input = normalizeSelfFetchInput('/api/internal/process-batch', requestUrl)
-
-        expect(input).toBeInstanceOf(URL)
-        expect((input as URL).toString()).toBe(
-            'https://vocabulon-staging.playcademy.gg/api/internal/process-batch',
-        )
-    })
-
-    it('treats bare paths as root-relative', () => {
-        const input = normalizeSelfFetchInput('api/internal/process-batch', requestUrl)
-
-        expect(input).toBeInstanceOf(URL)
-        expect((input as URL).toString()).toBe(
-            'https://vocabulon-staging.playcademy.gg/api/internal/process-batch',
-        )
-    })
-
-    it('preserves absolute URL strings', () => {
-        const input = normalizeSelfFetchInput(
-            'https://vocabulon-staging.playcademy.gg/api/internal/process-batch',
-            requestUrl,
-        )
-
-        expect(input).toBeInstanceOf(URL)
-        expect((input as URL).toString()).toBe(
-            'https://vocabulon-staging.playcademy.gg/api/internal/process-batch',
-        )
-    })
-
-    it('preserves query and hash on normalized paths', () => {
-        const input = normalizeSelfFetchInput('/api/internal/process-batch?attempt=2#step', requestUrl)
-
-        expect(input).toBeInstanceOf(URL)
-        expect((input as URL).toString()).toBe(
-            'https://vocabulon-staging.playcademy.gg/api/internal/process-batch?attempt=2#step',
-        )
-    })
-
-    it('passes through URL objects unchanged', () => {
-        const url = new URL('https://vocabulon-staging.playcademy.gg/api/internal/process-batch')
-        const input = normalizeSelfFetchInput(url, requestUrl)
-
-        expect(input).toBe(url)
-    })
-
-    it('supports non-http absolute schemes', () => {
-        const input = normalizeSelfFetchInput('mailto:test@example.com', requestUrl)
-
-        expect(input).toBeInstanceOf(URL)
-        expect((input as URL).toString()).toBe('mailto:test@example.com')
-    })
-
-    it('does not allow protocol-relative input to escape origin', () => {
-        const input = normalizeSelfFetchInput('//evil.example.com/path', requestUrl)
-
-        expect(input).toBeInstanceOf(URL)
-        expect((input as URL).toString()).toBe('https://vocabulon-staging.playcademy.gg/evil.example.com/path')
-    })
-
-    it('passes through Request objects unchanged', () => {
-        const request = new Request('https://vocabulon-staging.playcademy.gg/api/internal/process-batch')
-        const input = normalizeSelfFetchInput(request, requestUrl)
-
-        expect(input).toBe(request)
-    })
-})
-
-describe('wrapSelfWorkerWithPathResolution', () => {
-    const requestUrl = 'https://vocabulon-staging.playcademy.gg/api/admin/genai/sprint'
-
-    it('normalizes string path inputs before delegating to raw self worker', async () => {
-        const calls: { input: RequestInfo | URL; init?: RequestInit }[] = []
-        const raw: SelfWorker = {
-            fetch: (input, init) => {
-                calls.push({ input, init })
-
-                return Promise.resolve(new Response(null, { status: 202 }))
-            },
-        }
-
-        const self = wrapSelfWorkerWithPathResolution(raw, requestUrl)
-        const init = { method: 'POST' }
-        const response = await self.fetch('api/internal/process-batch', init)
-
-        expect(response.status).toBe(202)
-        expect(calls).toHaveLength(1)
-        expect(calls[0]?.input).toBeInstanceOf(URL)
-        expect((calls[0]!.input as URL).toString()).toBe(
-            'https://vocabulon-staging.playcademy.gg/api/internal/process-batch',
-        )
-        expect(calls[0]?.init).toEqual(init)
-    })
-
-    it('passes Request objects through to the raw self worker', async () => {
-        const calls: { input: RequestInfo | URL; init?: RequestInit }[] = []
-        const raw: SelfWorker = {
-            fetch: (input, init) => {
-                calls.push({ input, init })
-
-                return Promise.resolve(new Response(null, { status: 204 }))
-            },
-        }
-        const self = wrapSelfWorkerWithPathResolution(raw, requestUrl)
-        const req = new Request('https://vocabulon-staging.playcademy.gg/api/internal/process-batch')
-
-        await self.fetch(req)
-
-        expect(calls).toHaveLength(1)
-        expect(calls[0]?.input).toBe(req)
-        expect(calls[0]?.init).toBeUndefined()
-    })
-})
-
-describe('concurrent request isolation (spread-then-mutate)', () => {
-    it('two spread copies resolve SELF paths using their own request URL', async () => {
-        const calls: (RequestInfo | URL)[] = []
-        const raw: SelfWorker = {
-            fetch: (input: RequestInfo | URL) => {
-                calls.push(input)
-
-                return Promise.resolve(new Response('ok', { status: 200 }))
-            },
-        }
-
-        const sharedEnv = {
-            __PLAYCADEMY_DISPATCH: { get: (_name: string) => raw },
-            __PLAYCADEMY_WORKER_NAME: 'staging-vocabulon',
-        } as unknown as HonoEnv['Bindings']
-
-        const env1 = { ...sharedEnv } as HonoEnv['Bindings']
-
-        env1.SELF = wrapSelfWorkerWithPathResolution(resolveRawSelfWorker(env1), 'https://one.example.com/api/a')
-
-        const env2 = { ...sharedEnv } as HonoEnv['Bindings']
-
-        env2.SELF = wrapSelfWorkerWithPathResolution(resolveRawSelfWorker(env2), 'https://two.example.com/api/b')
-
-        await env1.SELF!.fetch('api/test/ping')
-        await env2.SELF!.fetch('api/test/ping')
-        await env1.SELF!.fetch('api/test/ping')
-
-        expect(sharedEnv.SELF).toBeUndefined()
-        expect(calls).toHaveLength(3)
-        expect((calls[0] as URL).toString()).toBe('https://one.example.com/api/test/ping')
-        expect((calls[1] as URL).toString()).toBe('https://two.example.com/api/test/ping')
-        expect((calls[2] as URL).toString()).toBe('https://one.example.com/api/test/ping')
-    })
-})
-
-describe('resolveRawSelfWorker', () => {
-    beforeEach(() => {
-        mock.restore()
-    })
-
-    it('uses dispatch namespace binding when available', async () => {
-        const targetWorker: SelfWorker = {
-            fetch: () => Promise.resolve(new Response('ok')),
-        }
-
-        const env = {
-            __PLAYCADEMY_DISPATCH: {
-                get: (name: string) => {
-                    expect(name).toBe('staging-vocabulon')
-
-                    return targetWorker
-                },
-            },
-            __PLAYCADEMY_WORKER_NAME: 'staging-vocabulon',
-        } as unknown as HonoEnv['Bindings']
-
-        const resolved = resolveRawSelfWorker(env)
-        const response = await resolved.fetch('https://vocabulon-staging.playcademy.gg/api/internal/process')
-
-        expect(response.status).toBe(200)
-    })
-
-    it('falls back to global fetch when dispatch binding is unavailable', async () => {
-        const fetchMock = mock(() => Promise.resolve(new Response('fallback', { status: 204 })))
-        const originalFetch = globalThis.fetch
-
-        globalThis.fetch = fetchMock as unknown as typeof fetch
-
-        try {
-            const env = {} as HonoEnv['Bindings']
-            const resolved = resolveRawSelfWorker(env)
-            const response = await resolved.fetch(
-                'https://vocabulon-staging.playcademy.gg/api/internal/process',
-            )
-
-            expect(response.status).toBe(204)
-            expect(fetchMock).toHaveBeenCalledTimes(1)
-
-            const firstCall = fetchMock.mock.calls[0] as unknown[] | undefined
-
-            expect(firstCall).toBeDefined()
-
-            const arg = firstCall?.[0]
-
-            expect(arg).toBeInstanceOf(Request)
-        } finally {
-            globalThis.fetch = originalFetch
-        }
-    })
-
-    it('falls back to global fetch when worker name is missing', async () => {
-        const fetchMock = mock(() => Promise.resolve(new Response('fallback', { status: 206 })))
-        const originalFetch = globalThis.fetch
-
-        globalThis.fetch = fetchMock as unknown as typeof fetch
-
-        try {
-            const env = {
-                __PLAYCADEMY_DISPATCH: {
-                    get: () => {
-                        throw new Error('should not be called when worker name is missing')
-                    },
-                },
-            } as unknown as HonoEnv['Bindings']
-            const resolved = resolveRawSelfWorker(env)
-            const response = await resolved.fetch(
-                'https://vocabulon-staging.playcademy.gg/api/internal/process',
-            )
-
-            expect(response.status).toBe(206)
-            expect(fetchMock).toHaveBeenCalledTimes(1)
-        } finally {
-            globalThis.fetch = originalFetch
-        }
-    })
-})

package/dist/edge-play/src/lib/self-dispatch.ts

@@ -1,41 +0,0 @@
-import type { HonoEnv, SelfWorker } from '../types'
-
-function isAbsoluteUrl(value: string): boolean {
-    return /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(value)
-}
-
-export function normalizeSelfFetchInput(
-    input: RequestInfo | URL,
-    requestUrl: string,
-): RequestInfo | URL {
-    if (typeof input !== 'string') {
-        return input
-    }
-
-    if (isAbsoluteUrl(input)) {
-        return new URL(input)
-    }
-
-    const origin = new URL(requestUrl).origin
-    const sanitized = input.startsWith('//') ? `/${input.replace(/^\/+/, '')}` : input
-    const pathname = sanitized.startsWith('/') ? sanitized : `/${sanitized}`
-
-    return new URL(pathname, origin)
-}
-
-export function wrapSelfWorkerWithPathResolution(raw: SelfWorker, requestUrl: string): SelfWorker {
-    return {
-        fetch: (input, init) => raw.fetch(normalizeSelfFetchInput(input, requestUrl), init),
-    }
-}
-
-export function resolveRawSelfWorker(env: HonoEnv['Bindings']): SelfWorker {
-    const dispatchBinding = env.__PLAYCADEMY_DISPATCH
-    const workerName = env.__PLAYCADEMY_WORKER_NAME
-
-    if (dispatchBinding && workerName) {
-        return dispatchBinding.get(workerName)
-    }
-
-    return { fetch: (input, init) => fetch(new Request(input, init)) }
-}

package/dist/edge-play/src/lib/validation.test.ts

@@ -1,190 +0,0 @@
-import { describe, expect, it } from 'bun:test'
-
-import {
-    isValidGrade,
-    isValidSubject,
-    validateCourseConfig,
-    VALID_GRADES,
-    VALID_SUBJECTS,
-} from './validation'
-
-import type { PlaycademyConfig } from '@playcademy/sdk/server'
-
-describe('isValidGrade', () => {
-    it('accepts valid grade levels', () => {
-        for (const grade of VALID_GRADES) {
-            expect(isValidGrade(grade)).toBe(true)
-        }
-    })
-
-    it('accepts Pre-K (-1), Kindergarten (0), and AP (13)', () => {
-        expect(isValidGrade(-1)).toBe(true) // Pre-K
-        expect(isValidGrade(0)).toBe(true) // Kindergarten
-        expect(isValidGrade(13)).toBe(true) // AP
-    })
-
-    it('rejects invalid grade levels', () => {
-        expect(isValidGrade(-2)).toBe(false)
-        expect(isValidGrade(14)).toBe(false)
-        expect(isValidGrade(100)).toBe(false)
-    })
-
-    it('rejects non-integer values', () => {
-        expect(isValidGrade(3.5)).toBe(false)
-        expect(isValidGrade(NaN)).toBe(false)
-        expect(isValidGrade(Infinity)).toBe(false)
-    })
-
-    it('rejects non-number values', () => {
-        expect(isValidGrade('3')).toBe(false)
-        expect(isValidGrade(null)).toBe(false)
-        expect(isValidGrade(undefined)).toBe(false)
-        expect(isValidGrade({})).toBe(false)
-    })
-})
-
-describe('isValidSubject', () => {
-    it('accepts valid subjects', () => {
-        for (const subject of VALID_SUBJECTS) {
-            expect(isValidSubject(subject)).toBe(true)
-        }
-    })
-
-    it('accepts common subjects', () => {
-        expect(isValidSubject('Math')).toBe(true)
-        expect(isValidSubject('FastMath')).toBe(true)
-        expect(isValidSubject('Reading')).toBe(true)
-        expect(isValidSubject('Science')).toBe(true)
-    })
-
-    it('rejects invalid subjects', () => {
-        expect(isValidSubject('History')).toBe(false)
-        expect(isValidSubject('Art')).toBe(false)
-        expect(isValidSubject('math')).toBe(false) // case-sensitive
-        expect(isValidSubject('MATH')).toBe(false)
-    })
-
-    it('rejects non-string values', () => {
-        expect(isValidSubject(123)).toBe(false)
-        expect(isValidSubject(null)).toBe(false)
-        expect(isValidSubject(undefined)).toBe(false)
-        expect(isValidSubject({})).toBe(false)
-    })
-})
-
-describe('validateCourseConfig', () => {
-    /**
-     * Simulates a typical playcademy.config.js for a math game
-     * covering grades 3-5.
-     */
-    const mathGameConfig: PlaycademyConfig = {
-        name: 'Math Adventure',
-        integrations: {
-            timeback: {
-                courses: [
-                    { subject: 'Math', grade: 3, totalXp: 1000, masterableUnits: 10 },
-                    { subject: 'Math', grade: 4, totalXp: 1200, masterableUnits: 12 },
-                    { subject: 'Math', grade: 5, totalXp: 1500, masterableUnits: 15 },
-                ],
-            },
-        },
-    }
-
-    /**
-     * Simulates a multi-subject game config.
-     */
-    const multiSubjectConfig: PlaycademyConfig = {
-        name: 'Learning Hub',
-        integrations: {
-            timeback: {
-                courses: [
-                    { subject: 'Math', grade: 3, totalXp: 500, masterableUnits: 5 },
-                    { subject: 'Reading', grade: 3, totalXp: 500, masterableUnits: 5 },
-                    { subject: 'Science', grade: 4, totalXp: 600, masterableUnits: 6 },
-                ],
-            },
-        },
-    }
-
-    it('returns null for configured grade/subject combinations', () => {
-        expect(validateCourseConfig({ grade: 3, subject: 'Math', config: mathGameConfig })).toBeNull()
-        expect(validateCourseConfig({ grade: 4, subject: 'Math', config: mathGameConfig })).toBeNull()
-        expect(validateCourseConfig({ grade: 5, subject: 'Math', config: mathGameConfig })).toBeNull()
-    })
-
-    it('returns error for unconfigured grade', () => {
-        const result = validateCourseConfig({ grade: 6, subject: 'Math', config: mathGameConfig })
-
-        expect(result).not.toBeNull()
-        expect(result?.error).toContain('Invalid grade/subject combination')
-        expect(result?.error).toContain('Math (Grade 6)')
-        expect(result?.error).toContain('Configured courses:')
-    })
-
-    it('returns error for unconfigured subject', () => {
-        const result = validateCourseConfig({ grade: 3, subject: 'Reading', config: mathGameConfig })
-
-        expect(result).not.toBeNull()
-        expect(result?.error).toContain('Invalid grade/subject combination')
-        expect(result?.error).toContain('Reading (Grade 3)')
-    })
-
-    it('lists all configured courses in error message', () => {
-        const result = validateCourseConfig({ grade: 1, subject: 'Math', config: mathGameConfig })
-
-        expect(result?.error).toContain('Math (Grade 3)')
-        expect(result?.error).toContain('Math (Grade 4)')
-        expect(result?.error).toContain('Math (Grade 5)')
-    })
-
-    it('validates multi-subject configs correctly', () => {
-        // Configured combinations
-        expect(
-            validateCourseConfig({ grade: 3, subject: 'Math', config: multiSubjectConfig }),
-        ).toBeNull()
-        expect(
-            validateCourseConfig({ grade: 3, subject: 'Reading', config: multiSubjectConfig }),
-        ).toBeNull()
-        expect(
-            validateCourseConfig({ grade: 4, subject: 'Science', config: multiSubjectConfig }),
-        ).toBeNull()
-
-        // Not configured: Math grade 4 (only Science is grade 4)
-        const result = validateCourseConfig({
-            grade: 4,
-            subject: 'Math',
-            config: multiSubjectConfig,
-        })
-
-        expect(result).not.toBeNull()
-        expect(result?.error).toContain('Math (Grade 4)')
-    })
-
-    it('handles config with no courses', () => {
-        const emptyConfig: PlaycademyConfig = {
-            name: 'Empty Game',
-            integrations: {
-                timeback: {
-                    courses: [],
-                },
-            },
-        }
-
-        const result = validateCourseConfig({ grade: 3, subject: 'Math', config: emptyConfig })
-
-        expect(result).not.toBeNull()
-        expect(result?.error).toContain('Configured courses: none')
-    })
-
-    it('handles config with no timeback integration', () => {
-        const noTimebackConfig: PlaycademyConfig = {
-            name: 'No Timeback',
-            integrations: {},
-        }
-
-        const result = validateCourseConfig({ grade: 3, subject: 'Math', config: noTimebackConfig })
-
-        expect(result).not.toBeNull()
-        expect(result?.error).toContain('Configured courses: none')
-    })
-})

package/dist/edge-play/src/lib/validation.ts

@@ -1,64 +0,0 @@
-/**
- * Shared validation utilities for edge-play routes.
- */
-
-import type { PlaycademyConfig } from '@playcademy/sdk/server'
-
-/** Valid grade levels: -1 (Pre-K), 0 (Kindergarten), 1-12 (Grades), 13 (AP) */
-export const VALID_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13] as const
-
-/** Valid TimeBack subject values */
-export const VALID_SUBJECTS = [
-    'Reading',
-    'Language',
-    'Vocabulary',
-    'Social Studies',
-    'Writing',
-    'Science',
-    'FastMath',
-    'Math',
-    'None',
-] as const
-
-export type ValidGrade = (typeof VALID_GRADES)[number]
-export type ValidSubject = (typeof VALID_SUBJECTS)[number]
-
-export function isValidGrade(value: unknown): value is ValidGrade {
-    return (
-        typeof value === 'number' &&
-        Number.isInteger(value) &&
-        VALID_GRADES.includes(value as ValidGrade)
-    )
-}
-
-export function isValidSubject(value: unknown): value is ValidSubject {
-    return typeof value === 'string' && VALID_SUBJECTS.includes(value as ValidSubject)
-}
-
-/**
- * Validate that a grade/subject combination is configured for this game.
- * Returns an error object if invalid, null if valid.
- */
-export function validateCourseConfig(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
-}

package/dist/edge-play/src/polyfills.js

@@ -1,54 +0,0 @@
-/**
- * Polyfills for Node.js modules in edge runtimes
- *
- * Provides minimal implementations to allow bundling.
- * These should NOT be called at runtime (config is provided directly).
- */
-
-const notAvailable = name => {
-    throw new Error(`${name} not available in Worker runtime - config should be provided directly`)
-}
-
-// fs exports
-export const existsSync = () => notAvailable('fs.existsSync')
-export const readdirSync = () => notAvailable('fs.readdirSync')
-export const statSync = () => notAvailable('fs.statSync')
-export const readFile = () => notAvailable('fs/promises.readFile')
-
-// path exports
-export const resolve = (...args) => args.join('/')
-export const dirname = p => p.split('/').slice(0, -1).join('/')
-export const parse = p => ({
-    dir: dirname(p),
-    name: p.split('/').pop(),
-    base: p.split('/').pop(),
-    ext: '',
-    root: '/',
-})
-export const join = (...args) => args.join('/')
-
-// os exports
-export const tmpdir = () => '/tmp'
-export const homedir = () => notAvailable('os.homedir')
-
-// Default export for 'process' module
-export default {
-    env: {
-        // These will be set by the Worker environment
-        // Cloudflare Workers uses env bindings, but we access via process.env
-        PLAYCADEMY_API_KEY: globalThis.PLAYCADEMY_API_KEY || '',
-        GAME_ID: globalThis.GAME_ID || '',
-        PLAYCADEMY_BASE_URL: globalThis.PLAYCADEMY_BASE_URL || '',
-    },
-    cwd: () => '/',
-}
-
-// Named export as well for compatibility
-export const process = {
-    env: {
-        PLAYCADEMY_API_KEY: globalThis.PLAYCADEMY_API_KEY || '',
-        GAME_ID: globalThis.GAME_ID || '',
-        PLAYCADEMY_BASE_URL: globalThis.PLAYCADEMY_BASE_URL || '',
-    },
-    cwd: () => '/',
-}

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

@@ -1,59 +0,0 @@
-/**
- * Route Registration Helper
- *
- * Conditionally registers built-in integration routes based on enabled integrations.
- * Uses dynamic imports to enable tree-shaking (unused integrations are removed from bundle).
- */
-
-import { ROUTES } from './constants'
-
-import type { Hono } from 'hono'
-
-import type { HonoEnv, Integrations } from './types'
-
-/**
- * Registers all enabled built-in integration routes
- *
- * @param app - Hono application instance
- * @param integrations - Enabled integrations from config
- */
-export async function registerBuiltinRoutes(app: Hono<HonoEnv>, integrations?: Integrations) {
-    // Route discovery (always included)
-    const routesIndex = await import('./routes/index')
-
-    app.get(ROUTES.INDEX, routesIndex.GET)
-
-    // Health check (always included)
-    const health = await import('./routes/health')
-
-    app.get(ROUTES.HEALTH, health.GET)
-
-    // TimeBack integration
-    if (integrations?.timeback) {
-        const [endActivity, getXp] = await Promise.all([
-            import('./routes/integrations/timeback/end-activity'),
-            import('./routes/integrations/timeback/get-xp'),
-        ])
-
-        app.post(ROUTES.TIMEBACK.END_ACTIVITY, endActivity.POST)
-        app.get(ROUTES.TIMEBACK.GET_XP, getXp.GET)
-    } else if (integrations?.timeback === null) {
-        app.post('/api/integrations/timeback/end-activity', async c =>
-            c.json({
-                status: 'ok',
-                __playcademyDevWarning: 'timeback-not-configured',
-            }),
-        )
-        app.get('/api/integrations/timeback/xp', async c =>
-            c.json({
-                timebackId: '',
-                totalXp: 0,
-                __playcademyDevWarning: 'timeback-not-configured',
-            }),
-        )
-    }
-
-    // TODO: Auth integration
-    // TODO: Storage integration
-    // TODO: Realtime integration
-}