playcademy 0.32.1-beta.2 → 0.33.0

package/dist/bucket.d.ts

@@ -1,7 +1,237 @@
-import { GamePermission } from '@playcademy/constants';
-import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
 import { Miniflare } from 'miniflare';
 
+/**
+ * Browser permissions a game may declare and the hub may delegate to its
+ * iframe. Opt-in per game because a delegated grant keys to the hub's
+ * top-level origin: one player grant would otherwise reach every embedded
+ * game. Baseline features (fullscreen, autoplay, gamepad) are delegated to
+ * all games and are not part of this set.
+ */
+declare const GAME_PERMISSIONS: readonly ['microphone', 'camera'];
+type GamePermission = (typeof GAME_PERMISSIONS)[number];
+
+/**
+ * Valid grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+declare const TIMEBACK_GRADES: readonly [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+/**
+ * The TimeBack subject vocabulary, carried on courses, activity data, and
+ * Caliper events alike. 'None' is canonical: TimeBack accepts it as a course
+ * subject and uses it as the fallback for unknown or missing subjects.
+ */
+declare const TIMEBACK_SUBJECTS: readonly ['Reading', 'Language', 'Vocabulary', 'Social Studies', 'Writing', 'Science', 'FastMath', 'Math', 'None'];
+
+/**
+ * TimeBack Enums & Literal Types
+ *
+ * Basic type definitions used throughout the TimeBack integration. Unions
+ * derive from the canonical value lists in @playcademy/constants (type-only
+ * imports, so this package ships no runtime code).
+ *
+ * @module types/timeback/types
+ */
+
+/**
+ * The TimeBack subject vocabulary. 'None' is canonical: TimeBack accepts it
+ * on courses and uses it as the fallback for unknown or missing subjects.
+ */
+type TimebackSubject = (typeof TIMEBACK_SUBJECTS)[number];
+/**
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+type TimebackGrade = (typeof TIMEBACK_GRADES)[number];
+/**
+ * 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';
+    /** Whether this course appears in the TimeBack catalog for teachers and parents */
+    timebackVisible?: boolean;
+    /** 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;
+}
+
 /**
  * @fileoverview Server SDK Type Definitions
  *

package/dist/bucket.js

@@ -42,7 +42,7 @@ var GAME_API_ROUTES_DIRECTORY = `${GAME_SERVER_ROOT_DIRECTORY}/api`;
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.25-beta.2",
+  version: "0.0.25",
   type: "module",
   exports: {
     "./server": {

package/dist/cli.js

@@ -1208,7 +1208,7 @@ var SAMPLE_BUCKET_FILENAME = "bucket.ts";
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.25-beta.2",
+  version: "0.0.25",
   type: "module",
   exports: {
     "./server": {
@@ -3045,7 +3045,7 @@ import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as re
 import { join as join12 } from "node:path";
 
 // src/version.ts
-var cliVersion = false ? "0.0.0-dev" : "0.32.1-beta.2";
+var cliVersion = false ? "0.0.0-dev" : "0.33.0";
 
 // src/lib/init/database.ts
 var drizzleConfigTemplate = loadTemplateString("database/drizzle-config.ts");

package/dist/constants.js

@@ -21,7 +21,7 @@ var SAMPLE_BUCKET_FILENAME = "bucket.ts";
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.25-beta.2",
+  version: "0.0.25",
   type: "module",
   exports: {
     "./server": {

package/dist/db.d.ts

@@ -1,4 +1,3 @@
-import { DeployMigration, DeploymentStateResponse, DeployBaseline, BaselineMigrationEvidence, DeploymentStateBaselineRequest, MigrationResolution, GameRestorePoint, DatabaseRestoreResponse, SeedLogEntry } from '@playcademy/types';
 import { Miniflare } from 'miniflare';
 
 /**
@@ -30,6 +29,244 @@ import { Miniflare } from 'miniflare';
  */
 declare function getDevDbPath(): string;
 
+/**
+ * Game Types
+ *
+ * Literal types and API DTOs. Database row types are in @playcademy/data/types.
+ *
+ * @module types/game
+ */
+
+/** One migration in a migrate-mode deploy payload */
+interface DeployMigration {
+    /** Journal tag, e.g. '0042_brave_hulk' */
+    tag: string;
+    /** Pre-split SQL statements (the CLI splits on drizzle statement-breakpoints) */
+    statements: string[];
+    /** sha-256 of the normalized migration SQL (sha256-v1) */
+    checksum: string;
+}
+/** Journal entry in a baseline adoption block */
+interface DeployBaselineJournalEntry {
+    tag: string;
+    checksum: string;
+}
+/**
+ * Baseline adoption block (PLA-217 D7 seed-on-deploy): the client's claimed
+ * starting state for a game that predates server-side deployment state.
+ * Consumed by the deploy itself — an unadopted game gets its claimed ledger
+ * rows, snapshot/hash, and live fingerprint recorded before the database
+ * step runs; adopted games skip the block.
+ */
+interface DeployBaseline {
+    lastAppliedMigrationTag?: string;
+    journal?: DeployBaselineJournalEntry[];
+    /**
+     * Per-migration snapshot deltas for content validation (D7): the
+     * seed claim is judged against the live database exactly like a
+     * manual `db baseline` claim — the side door uses the front door's
+     * checkpoint.
+     */
+    evidence?: BaselineMigrationEvidence[];
+    schemaSnapshot?: unknown;
+    schemaHash?: string;
+    integrationsHash?: string;
+    buildHash?: string;
+}
+/** Active game worker state served by the deployment-state endpoint */
+interface DeploymentStateGame {
+    /** Backend bundle hash from the active deployment row */
+    codeHash: string | null;
+    /** Frontend zip hash from game_deployment_state (null when unseeded) */
+    buildHash: string | null;
+    url: string;
+    deployedAt: string;
+}
+/** Active dashboard worker state served by the deployment-state endpoint */
+interface DeploymentStateDashboard {
+    url: string;
+    deployedAt: string;
+}
+/** Details of the last failed migration, from the failed deploy job */
+interface DeploymentStateDatabaseFailure {
+    tag: string;
+    error: string;
+    /**
+     * Set only when the failing statement is known exactly (the size
+     * preflight names the statement it measured). Execution failures are
+     * null: D1's byte offset has an unverified reference frame for the
+     * batch array form, so it is never mapped to an index.
+     */
+    statementIndex: number | null;
+    at: string;
+}
+/** A ledger entry from the game database's applied-migrations ledger */
+interface DeploymentStateAppliedMigration {
+    tag: string;
+    /** Checksum recorded at apply time (normalized SQL, see checksumAlgo) */
+    checksum: string;
+    /** Hash algorithm the checksum was recorded under (e.g. 'sha256-v1') */
+    checksumAlgo: string;
+}
+/** Database schema state served by the deployment-state endpoint */
+interface DeploymentStateDatabase {
+    /** Applied migrations from the live in-D1 ledger (null when the game has no database) */
+    appliedMigrations: DeploymentStateAppliedMigration[] | null;
+    lastFailure: DeploymentStateDatabaseFailure | null;
+    /** Hash of the drizzle snapshot (push-mode baseline) */
+    schemaHash: string | null;
+    /** Hash of the normalized live sqlite_master */
+    schemaFingerprint: string | null;
+    /**
+     * Stored drizzle snapshot (push-mode diffing only). Present only when
+     * the request asked for it with `?include=schemaSnapshot` (D4).
+     */
+    schemaSnapshot?: unknown;
+}
+/** Secret key names partitioned by ownership — names only, never hashes */
+interface DeploymentStateSecrets {
+    /** Keys recorded in the server-side secrets manifest */
+    managedKeys: string[];
+    /**
+     * Remote keys not in the manifest (set by SST, wrangler, or hand).
+     * Null when the server has no Cloudflare provider to list remote keys.
+     */
+    unmanagedKeys: string[] | null;
+}
+interface DeploymentStateLastDeploy {
+    at: string;
+    /** Who deployed: their email, or the raw user id when the account no longer resolves */
+    by: string;
+}
+/**
+ * Server-side deployment state for a game.
+ *
+ * Everything CLI deploy prep diffs against, fetched from
+ * GET /api/games/:slug/deployment-state so deploys never depend on
+ * local state for correctness.
+ */
+interface DeploymentStateResponse {
+    gameId: string;
+    /** True iff a game_deployment_state row exists for the game */
+    seeded: boolean;
+    game: DeploymentStateGame | null;
+    dashboard: DeploymentStateDashboard | null;
+    database: DeploymentStateDatabase;
+    secrets: DeploymentStateSecrets;
+    /** Hash of the declared integrations config (null when unseeded) */
+    integrationsHash: string | null;
+    /** Last deployed compatibility date (null when unseeded) */
+    compatibilityDate: string | null;
+    lastDeploy: DeploymentStateLastDeploy | null;
+}
+/**
+ * Manual baseline adoption request (PLA-217 D7): the fresh-machine path for
+ * a game that predates server-side deployment state. Carries the claimed
+ * migrate-mode history (tag + journal), the push-mode snapshot, or both.
+ */
+interface DeploymentStateBaselineRequest {
+    lastAppliedMigrationTag?: string;
+    journal?: DeployBaselineJournalEntry[];
+    schemaSnapshot?: unknown;
+    schemaHash?: string;
+    /**
+     * Per-migration schema-object evidence (creates AND drops) derived
+     * from drizzle's snapshot files. The server replays it up to the
+     * claimed tag into the expected schema and validates that against the
+     * live database (D7): surviving claimed objects must exist,
+     * beyond-claim objects must be absent unless claimed history already
+     * explains them. Absent evidence downgrades every migration to
+     * no-signal.
+     */
+    evidence?: BaselineMigrationEvidence[];
+    /**
+     * Waive refusals for no-signal migrations only (content contradictions
+     * are never waivable). Recorded server-side for audit.
+     */
+    allowUnverified?: boolean;
+}
+/**
+ * Schema objects one journal migration introduced and removed (snapshot
+ * delta). Drops are as load-bearing as creates: an object created by one
+ * migration and dropped by a later one must not be demanded of the live
+ * database, and its live presence beyond the claim must not convict a
+ * migration whose object is already explained by claimed history.
+ */
+interface BaselineMigrationEvidence {
+    tag: string;
+    /** Journal generation timestamp (drizzle `when`), ISO 8601 */
+    generatedAt: string;
+    createsTables: {
+        name: string;
+        columns: string[];
+    }[];
+    addsColumns: {
+        table: string;
+        column: string;
+    }[];
+    createsIndexes: string[];
+    createsViews: string[];
+    dropsTables: string[];
+    dropsColumns: {
+        table: string;
+        column: string;
+    }[];
+    dropsIndexes: string[];
+    dropsViews: string[];
+}
+/** How a ledger escape-hatch resolution lands: record the row, or remove it */
+type MigrationResolution = 'applied' | 'rolled-back';
+/**
+ * A restorable pre-deploy database state (D1 Time Travel bookmark).
+ *
+ * Each schema-bearing deploy captures a bookmark of the database as it was
+ * the moment before that deploy's schema changes ran. Only bookmarks
+ * belonging to the CURRENT database and within Time Travel's retention
+ * window are served — a `db reset` creates a new database (bookmarks do
+ * not cross that boundary), and Cloudflare expires bookmarks after the
+ * account plan's retention period.
+ */
+interface GameRestorePoint {
+    /** Deployment row id — pass to the restore endpoint (or a unique prefix to the CLI) */
+    id: string;
+    /**
+     * When the bookmark was captured (the exact state a restore rewinds
+     * to), ISO 8601. Rows from before capture times were recorded fall
+     * back to the deploy completion time.
+     */
+    capturedAt: string;
+    /** Whether the capturing deployment is the currently active one */
+    active: boolean;
+}
+/** Outcome of a Time Travel restore (PLA-217 D10) */
+interface DatabaseRestoreResponse {
+    restorePointId: string;
+    /** The moment the database was rewound to (the bookmark's capture time), ISO 8601 */
+    restoredTo: string;
+    /**
+     * Live schema fingerprint captured after the restore: the developer's
+     * audited attestation that the rewound state is intended, so the next
+     * deploy verifies against it.
+     */
+    schemaFingerprint: string;
+    /** False when the game has no deployment-state row to re-attest */
+    fingerprintRecorded: boolean;
+    /**
+     * Bookmark of the database as it was just before this restore — the
+     * undo handle. Null only if Cloudflare omits it from the response.
+     */
+    previousBookmark: string | null;
+}
+/** Log entry captured from seed worker console output */
+interface SeedLogEntry {
+    /** Log level (log, warn, error, info) */
+    level: 'log' | 'warn' | 'error' | 'info';
+    /** Log message content */
+    message: string;
+    /** Milliseconds since seed execution started */
+    timestamp: number;
+}
+
 /**
  * Schema deployment planning (PLA-217 D5)
  *

package/dist/db.js

@@ -2333,7 +2333,7 @@ var GAME_API_ROUTES_DIRECTORY = `${GAME_SERVER_ROOT_DIRECTORY}/api`;
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.25-beta.2",
+  version: "0.0.25",
   type: "module",
   exports: {
     "./server": {