@playcademy/sdk 0.3.7-beta.1 → 0.4.0-beta.1

package/dist/server/edge.d.ts

@@ -0,0 +1,701 @@
+import { SchemaInfo } from '@playcademy/cloudflare';
+
+/**
+ * TimeBack Enums & Literal Types
+ *
+ * Basic type definitions used throughout the TimeBack integration.
+ *
+ * @module types/timeback/types
+ */
+/**
+ * Valid TimeBack subject values for course configuration.
+ * These are the supported subject values for OneRoster courses.
+ */
+type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+/**
+ * Valid Caliper subject values.
+ * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ */
+type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * OneRoster organization types.
+ */
+type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * Lesson types for PowerPath integration.
+ */
+type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
+
+/**
+ * TimeBack Configuration Types
+ *
+ * Configuration interfaces for Organization, Course, Component,
+ * Resource, and complete TimeBack setup.
+ *
+ * @module types/timeback/config
+ */
+
+/**
+ * Organization configuration for TimeBack (user input - optionals allowed)
+ */
+interface OrganizationConfig {
+    /** Display name for your organization */
+    name?: string;
+    /** Organization type */
+    type?: OrganizationType;
+    /** Unique identifier (defaults to Playcademy's org) */
+    identifier?: string;
+}
+/**
+ * Course goals for daily student targets
+ */
+interface CourseGoals {
+    /** Target XP students should earn per day */
+    dailyXp?: number;
+    /** Target lessons per day */
+    dailyLessons?: number;
+    /** Target active minutes per day */
+    dailyActiveMinutes?: number;
+    /** Target accuracy percentage */
+    dailyAccuracy?: number;
+    /** Target mastered units per day */
+    dailyMasteredUnits?: number;
+}
+/**
+ * Course metrics and totals
+ */
+interface CourseMetrics {
+    /** Total XP available in the course */
+    totalXp?: number;
+    /** Total lessons/activities in the course */
+    totalLessons?: number;
+    /** Total number of grade levels covered by this course */
+    totalGrades?: number;
+    /** The type of course (e.g. 'optional', 'hole-filling', 'base') */
+    courseType?: 'base' | 'hole-filling' | 'optional' | 'Base' | 'Hole-Filling' | 'Optional';
+    /** Indicates whether the course is supplemental content */
+    isSupplemental?: boolean;
+}
+/**
+ * Complete course metadata structure
+ */
+interface CourseMetadata {
+    /** Define the type of course and priority for the student */
+    courseType?: 'base' | 'hole-filling' | 'optional';
+    /** Boolean value to determine if a course is supplemental to a base course */
+    isSupplemental?: boolean;
+    /** Boolean value to determine if a course is custom to an individual student */
+    isCustom?: boolean;
+    /** Signals whether a course is in production with students */
+    publishStatus?: 'draft' | 'testing' | 'published' | 'deactivated';
+    /** Who to contact when issues reported with questions */
+    contactEmail?: string;
+    /** Primary app identifier */
+    primaryApp?: string;
+    /** Learning goals for students */
+    goals?: CourseGoals;
+    /** Course metrics and totals */
+    metrics?: CourseMetrics;
+    /** Vendor-specific metadata (e.g., AlphaLearn) */
+    [key: string]: unknown;
+}
+/**
+ * Course configuration for TimeBack (user input)
+ */
+interface CourseConfig {
+    /** Allocated OneRoster sourcedId (set after creation) */
+    sourcedId?: string;
+    /** Course title (defaults to game name) */
+    title?: string;
+    /** Subjects (REQUIRED for TimeBack integration) */
+    subjects: TimebackSubject[];
+    /** Used when recording progress/sessions if not explicitly specified per event. */
+    defaultSubject?: TimebackSubject;
+    /** Grade levels (REQUIRED for TimeBack integration) */
+    grades: TimebackGrade[];
+    /** Short course code (optional, auto-generated) */
+    courseCode?: string;
+    /** Course level (auto-derived from grades) */
+    level?: 'Elementary' | 'Middle' | 'High' | 'AP' | string;
+    /** Grading system */
+    gradingScheme?: 'STANDARD';
+    /** Total XP available in this course (REQUIRED before setup) */
+    totalXp?: number | null;
+    /** Total masterable units in this course (REQUIRED before setup) */
+    masterableUnits?: number | null;
+    /** Custom Playcademy metadata */
+    metadata?: CourseMetadata;
+}
+/**
+ * Component configuration for TimeBack (user input)
+ */
+interface ComponentConfig {
+    /** Component title (defaults to "{course.title} Activities") */
+    title?: string;
+    /** Display order */
+    sortOrder?: number;
+    /** Required prior components */
+    prerequisites?: string[];
+    /** How prerequisites work */
+    prerequisiteCriteria?: 'ALL' | 'ANY';
+}
+/**
+ * Playcademy-specific resource extensions
+ */
+interface PlaycademyResourceMetadata {
+    /** Mastery configuration for tracking discrete learning units */
+    mastery?: {
+        /** Total number of masterable units in the resource */
+        masterableUnits: number;
+        /** Type of mastery unit for semantic clarity */
+        unitType?: 'level' | 'rank' | 'skill' | 'module';
+    };
+}
+/**
+ * Resource configuration for TimeBack (user input)
+ */
+interface ResourceConfig {
+    /** Resource title (defaults to "{course.title} Game") */
+    title?: string;
+    /** Internal resource ID (auto-generated from package.json) */
+    vendorResourceId?: string;
+    /** Vendor identifier */
+    vendorId?: string;
+    /** Application identifier */
+    applicationId?: string;
+    /** Resource roles */
+    roles?: ('primary' | 'secondary')[];
+    /** Resource importance */
+    importance?: 'primary' | 'secondary';
+    /** Interactive resource metadata */
+    metadata?: {
+        /** Resource type */
+        type?: 'interactive';
+        /** Launch URL (defaults to Playcademy game URL) */
+        launchUrl?: string;
+        /** Platform name */
+        toolProvider?: string;
+        /** Teaching method */
+        instructionalMethod?: 'exploratory' | 'direct-instruction';
+        /** Subject area */
+        subject?: TimebackSubject;
+        /** Target grades */
+        grades?: TimebackGrade[];
+        /** Content language */
+        language?: string;
+        /** Base XP for completion */
+        xp?: number;
+        /** Playcademy-specific extensions */
+        playcademy?: PlaycademyResourceMetadata;
+    };
+}
+/**
+ * Component Resource link configuration (user input)
+ */
+interface ComponentResourceConfig {
+    /** Link title (defaults to "{resource.title} Activity") */
+    title?: string;
+    /** Display order */
+    sortOrder?: number;
+    /** Lesson type for PowerPath integration */
+    lessonType?: LessonType;
+}
+interface TimebackCourseConfig {
+    subject: string;
+    grade: number;
+}
+
+/**
+ * TimeBack Client SDK DTOs
+ *
+ * Data transfer objects for the TimeBack client SDK including
+ * progress tracking, session management, and activity completion.
+ *
+ * Note: TimebackClientConfig lives in @playcademy/timeback as it's
+ * SDK configuration, not a DTO.
+ *
+ * @module types/timeback/client
+ */
+
+/**
+ * Known extensions for TimeBack Activity Metrics Collection
+ */
+interface TimebackActivityExtensions {
+    /** Percentage complete (0-100) for the app course */
+    pctCompleteApp?: number;
+    /** Allow other arbitrary extensions */
+    [key: string]: unknown;
+}
+/**
+ * Activity data for ending an activity
+ */
+interface ActivityData {
+    /** Unique activity identifier (required) */
+    activityId: string;
+    /** Grade level for this activity (required for multi-grade course routing) */
+    grade: number;
+    /** Subject area (required for multi-grade course routing) */
+    subject: CaliperSubject;
+    /** Activity display name (optional) */
+    activityName?: string;
+    /** Course identifier (auto-filled from config if not provided) */
+    courseId?: string;
+    /** Course display name (auto-filled from config if not provided) */
+    courseName?: string;
+    /** Student email address (optional) */
+    studentEmail?: string;
+    /** Application name for Caliper events (defaults to 'Game') */
+    appName?: string;
+    /** Sensor URL for Caliper events (defaults to baseUrl) */
+    sensorUrl?: string;
+}
+/**
+ * Score data for activity completion
+ */
+interface ScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
+}
+/**
+ * Timing data for activity completion
+ */
+interface TimingData {
+    /** Duration of the activity in seconds */
+    durationSeconds: number;
+}
+/**
+ * Complete payload for ending an activity
+ */
+interface EndActivityPayload {
+    /** Activity metadata */
+    activityData: ActivityData;
+    /** Score information */
+    scoreData: ScoreData;
+    /** Timing information */
+    timingData: TimingData;
+    /** Explicit XP value to override automatic calculation */
+    xpEarned?: number;
+    /** Number of learning units mastered */
+    masteredUnits?: number;
+    /** Optional arbitrary extensions to include in the Caliper event */
+    extensions?: TimebackActivityExtensions;
+}
+
+/**
+ * TimeBack API Request/Response Types
+ *
+ * Types for TimeBack API endpoints including XP tracking,
+ * setup, verification, and activity completion.
+ *
+ * @module types/timeback/api
+ */
+
+interface EndActivityResponse {
+    status: 'ok';
+    courseId: string;
+    xpAwarded: number;
+    masteredUnits?: number;
+    pctCompleteApp?: number;
+    scoreStatus?: string;
+    inProgress?: string;
+}
+/**
+ * XP data for a single course.
+ */
+interface StudentCourseXp {
+    grade: number;
+    subject: string;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from student XP query.
+ */
+interface StudentXpResponse {
+    /** Total XP across all queried courses */
+    totalXp: number;
+    /** Today's XP (if requested) */
+    todayXp?: number;
+    /** Per-course XP breakdown (if requested) */
+    courses?: StudentCourseXp[];
+}
+
+/**
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
+ */
+
+/**
+ * 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 TimebackBaseConfig {
+    /** Organization configuration (shared across all courses) */
+    organization?: Partial<OrganizationConfig>;
+    /** Course defaults (can be overridden per-course) */
+    course?: Partial<CourseConfig>;
+    /** Component defaults */
+    component?: Partial<ComponentConfig>;
+    /** Resource defaults */
+    resource?: Partial<ResourceConfig>;
+    /** 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
+ */
+interface CustomRoutesIntegration {
+    /** Directory for custom API routes (defaults to 'server/api') */
+    directory?: string;
+}
+/**
+ * Database integration
+ */
+interface DatabaseIntegration {
+    /** Database directory (defaults to 'db') */
+    directory?: string;
+    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
+     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
+    strategy?: 'push' | 'migrate';
+}
+interface QueueConfig {
+    maxBatchSize?: number;
+    maxRetries?: number;
+    maxBatchTimeout?: number;
+    maxConcurrency?: number;
+    retryDelay?: number;
+    deadLetterQueue?: string;
+}
+/**
+ * Integrations configuration
+ * All backend features (database, custom routes, external services) are configured here
+ */
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig | null;
+    /** Custom API routes (optional) */
+    customRoutes?: CustomRoutesIntegration | boolean;
+    /** Database (optional) */
+    database?: DatabaseIntegration | boolean;
+    /** Key-Value storage (optional) */
+    kv?: boolean;
+    /** Bucket storage (optional) */
+    bucket?: boolean;
+    /** Authentication (optional) */
+    auth?: boolean;
+    /** Queues (optional) */
+    queues?: Record<string, QueueConfig | boolean>;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Integrations (database, custom routes, external services) */
+    integrations?: IntegrationsConfig;
+}
+
+/**
+ * Configuration options for initializing a PlaycademyClient instance.
+ *
+ * @example
+ * ```typescript
+ * const config: PlaycademyServerClientConfig = {
+ *   apiKey: process.env.PLAYCADEMY_API_KEY!,
+ *   gameId: 'my-math-game',
+ *   configPath: './playcademy.config.js'
+ * }
+ * ```
+ */
+interface PlaycademyServerClientConfig {
+    /**
+     * Playcademy API key for server-to-server authentication.
+     * Obtain from the Playcademy developer dashboard.
+     */
+    apiKey: string;
+    /**
+     * Optional path to playcademy.config.js file.
+     * If not provided, searches current directory and up to 3 parent directories.
+     * Ignored if `config` is provided directly.
+     *
+     * @example './config/playcademy.config.js'
+     */
+    configPath?: string;
+    /**
+     * Optional config object (for edge environments without filesystem).
+     * If provided, skips filesystem-based config loading.
+     *
+     * @example { name: 'My Game', integrations: { timeback: {...} } }
+     */
+    config?: PlaycademyConfig;
+    /**
+     * Optional base URL for Playcademy API.
+     * Defaults to environment variables or 'https://hub.playcademy.net'.
+     *
+     * @example 'http://localhost:3000' for local development
+     */
+    baseUrl?: string;
+    /**
+     * Optional game ID.
+     * If not provided, will attempt to fetch from API using the API token.
+     *
+     * @example 'my-math-game'
+     */
+    gameId?: string;
+}
+/**
+ * Internal state maintained by the PlaycademyClient instance.
+ *
+ * @internal
+ */
+interface PlaycademyServerClientState {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API requests */
+    baseUrl: string;
+    /** Game identifier */
+    gameId: string;
+    /** Loaded game configuration from playcademy.config.js */
+    config: PlaycademyConfig;
+    /**
+     * TimeBack course ID fetched from the Playcademy API.
+     * Used for all TimeBack event recording.
+     */
+    courseId?: string;
+}
+
+/**
+ * Resource bindings for backend deployment
+ * Provider-agnostic abstraction for cloud resources
+ */
+interface BackendResourceBindings {
+    /** SQL database instances to create and bind (maps to D1 on Cloudflare) */
+    database?: string[];
+    /** Key-value store namespaces to create and bind (maps to KV on Cloudflare) */
+    keyValue?: string[];
+    /** Object storage buckets to bind (maps to R2 on Cloudflare) */
+    bucket?: string[];
+    /** Queue bindings to create and bind */
+    queues?: Record<string, QueueConfig | boolean>;
+}
+/**
+ * Backend deployment bundle for uploading to Playcademy platform
+ */
+interface BackendDeploymentBundle {
+    /** Bundled JavaScript code ready for deployment */
+    code: string;
+    /** Game configuration */
+    config: PlaycademyConfig;
+    /** Optional resource bindings (database, storage, etc.) */
+    bindings?: BackendResourceBindings;
+    /** Optional schema information for database setup */
+    schema?: SchemaInfo;
+    /** Optional Cloudflare Worker compatibility flags */
+    compatibilityFlags?: string[];
+}
+
+/**
+ * OpenID Connect UserInfo claims (NOT a database row).
+ */
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+
+/**
+ * Server-side Playcademy client for recording student activity to TimeBack.
+ *
+ * This client works in any edge runtime. Config must be provided directly
+ * via the `config` option — there is no filesystem-based config discovery.
+ *
+ * @example
+ * ```typescript
+ * const client = await PlaycademyClient.init({
+ *   apiKey: env.PLAYCADEMY_API_KEY,
+ *   gameId: env.GAME_ID,
+ *   config: { name: 'My Game', integrations: { timeback: {...} } }
+ * })
+ *
+ * await client.timeback.endActivity(studentId, { ... })
+ * ```
+ */
+declare class PlaycademyClient {
+    private state;
+    protected constructor(state: PlaycademyServerClientState);
+    /**
+     * Initialize a new PlaycademyClient instance.
+     *
+     * Requires `config` to be provided directly. For automatic config file
+     * discovery from the filesystem, use `PlaycademyClient` from `@playcademy/sdk/server`.
+     *
+     * @param config - Client configuration options
+     * @param config.apiKey - Playcademy API key for authentication
+     * @param config.config - Game configuration object (required)
+     * @param config.gameId - Optional game ID (will be fetched from API if not provided)
+     * @param config.baseUrl - Optional base URL for Playcademy API (defaults to production)
+     * @returns Promise resolving to initialized PlaycademyClient instance
+     * @throws {Error} If apiKey is missing or invalid
+     * @throws {Error} If config is not provided
+     */
+    static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient>;
+    private fetchGameId;
+    /**
+     * Makes an authenticated HTTP request to the API.
+     *
+     * @param path - API endpoint path
+     * @param method - HTTP method
+     * @param body - Request body (optional)
+     * @returns Promise resolving to the response data
+     * @protected
+     */
+    protected request<T>(path: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
+    /**
+     * Gets the current game ID.
+     *
+     * @returns The game ID
+     */
+    get gameId(): string;
+    /**
+     * Gets the loaded game configuration.
+     *
+     * Returns the configuration loaded from playcademy.config.js during
+     * client initialization.
+     *
+     * @returns The loaded configuration object
+     */
+    get config(): PlaycademyServerClientState['config'];
+    /** TimeBack integration methods (endActivity) */
+    timeback: {
+        endActivity: (studentId: string, payload: EndActivityPayload) => Promise<EndActivityResponse>;
+        getStudentXp: (studentId: string, options?: {
+            grade?: number | undefined;
+            subject?: string | undefined;
+            include?: ("perCourse" | "today")[] | undefined;
+        } | undefined) => Promise<StudentXpResponse>;
+    };
+}
+
+/**
+ * @fileoverview Game Token Verification Utilities
+ *
+ * Utilities for verifying Playcademy game tokens sent from external games.
+ */
+
+interface VerifyGameTokenResponse {
+    claims: Record<string, unknown>;
+    gameId: string;
+    user: UserInfo;
+}
+/**
+ * Verifies a short-lived Playcademy Game Token and returns verified identity claims.
+ *
+ * Game tokens are JWT tokens minted by Playcademy and sent to external games
+ * running in iframes. They contain verified user identity information and can
+ * be validated server-side to securely identify players.
+ *
+ * This function calls the Playcademy API's `/api/games/verify` endpoint to
+ * cryptographically verify the token and extract the user information.
+ *
+ * @param gameToken - The game JWT token string to verify
+ * @param options - Optional configuration
+ * @param options.baseUrl - Optional base URL override (defaults to env vars or production)
+ * @returns Promise resolving to verified token payload
+ * @returns claims - Arbitrary claims from the JWT payload
+ * @returns gameId - The game ID this token was issued for
+ * @returns user - Verified user information (id, email, name, etc.)
+ * @throws {Error} If gameToken is not a valid string
+ * @throws {Error} If PLAYCADEMY_BASE_URL is not set and no baseUrl provided
+ * @throws {Error} If token verification fails (invalid/expired token)
+ * @throws {Error} If network request fails
+ *
+ * @example
+ * ```typescript
+ * // In your game server
+ * import { verifyGameToken } from '@playcademy/sdk/server'
+ *
+ * app.post('/api/auth/playcademy', async (req, res) => {
+ *   const { gameToken } = req.body
+ *
+ *   try {
+ *     const { user, gameId, claims } = await verifyGameToken(gameToken)
+ *
+ *     // Create session for the verified user
+ *     const session = await createSession(user.id)
+ *
+ *     res.json({ success: true, user, session })
+ *   } catch (error) {
+ *     res.status(401).json({ error: 'Invalid token' })
+ *   }
+ * })
+ * ```
+ */
+declare function verifyGameToken(gameToken: string, options?: {
+    baseUrl?: string;
+}): Promise<VerifyGameTokenResponse>;
+
+export { PlaycademyClient, verifyGameToken };
+export type { ActivityData, BackendDeploymentBundle, BackendResourceBindings, ComponentConfig, ComponentResourceConfig, EndActivityPayload, IntegrationsConfig, OrganizationConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, QueueConfig, ResourceConfig, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackGrade, TimebackIntegrationConfig, TimebackSubject, UserInfo };