@playcademy/sdk 0.23.1-beta.1 → 0.24.1-beta.1

package/dist/types.d.ts

@@ -96,442 +96,92 @@ declare const ASSESSMENT_PURPOSES: readonly ['end_of_course', 'diagnostic', 'rev
 declare const PLAYCADEMY_ASSESSMENT_CONTRACT_VERSION: 2;
 
 /**
- * User Types
+ * TimeBack Enums & Literal Types
  *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/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/user
+ * @module types/timeback/types
  */
 
-type UserRoleEnumType = UserRole;
-type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
-type DeveloperStatusValue = DeveloperStatusEnumType;
-type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
-type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-interface UserEnrollment {
-    gameId?: string;
-    courseId: string;
-    id?: string;
-    grade: number;
-    subject: string;
-    orgId?: string;
-}
-interface UserOrganization {
-    id: string;
-    name: string | null;
-    type: TimebackOrgType | string;
-    isPrimary: boolean;
-}
-interface TimebackStudentProfile {
-    role: TimebackUserRole;
-    organizations: UserOrganization[];
-}
 /**
- * Timeback identity on `/users/me`: who the student is, without enrollments.
- * Enrollments come from `/timeback/user` (or `client.timeback.user`).
+ * The TimeBack subject vocabulary. 'None' is canonical: TimeBack accepts it
+ * on courses and uses it as the fallback for unknown or missing subjects.
  */
-interface UserTimebackProfile extends TimebackStudentProfile {
-    id: string;
-}
-interface UserTimebackData extends UserTimebackProfile {
-    enrollments: UserEnrollment[];
-}
-type LocalDaySource = 'browser_last_seen' | 'platform_default';
-interface LocalDayContext {
-    timeZone: string;
-    source: LocalDaySource;
-    /** ISO 8601 timestamp for the last persisted timezone observation. */
-    observedAt: string | null;
-}
+type TimebackSubject = (typeof TIMEBACK_SUBJECTS)[number];
 /**
- * OpenID Connect UserInfo claims (NOT a database row).
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
  */
-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;
-}
-interface DeveloperStatusResponse {
-    status: DeveloperStatusEnumType;
-}
-interface DemoProfile {
-    displayName: string;
-    isDefault: boolean;
-}
+type TimebackGrade = (typeof TIMEBACK_GRADES)[number];
 /**
- * Update shape for `client.demo.profile.update(...)`.
- *
- * Kept as a named type so callers typed against it pick up new fields
- * automatically, but `displayName` is the only updatable field today and
- * the server's `DemoProfileSchema` requires it — a no-field payload would
- * 400 at runtime, so we model that at the type level too. When additional
- * fields land, make them required/optional individually based on server
- * validation, rather than blanket-optional.
+ * Platform pedagogy levels for a single lesson of instruction.
+ * E1 teaches, E2/E3 practice and remediate, E4 is the mastery check.
  */
-interface DemoProfileUpdate {
-    displayName: string;
-}
+type ELevel = 'E1' | 'E2' | 'E3' | 'E4';
 /**
- * Authenticated user for API responses.
- * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ * Valid Caliper subject values. The same vocabulary as OneRoster subjects.
  */
-interface AuthenticatedUser {
-    id: string;
-    email: string;
-    emailVerified: boolean;
-    name: string | null;
-    image: string | null;
-    username: string | null;
-    role: UserRoleEnumType;
-    developerStatus: DeveloperStatusEnumType;
-    createdAt: Date;
-    updatedAt: Date;
-    hasTimebackAccount: boolean;
-    localDay: LocalDayContext;
-    timeback?: UserTimebackProfile;
-}
-interface GameUser {
-    id: string;
-    name: string | null;
-    role: UserRoleEnumType;
-    username: string | null;
-    email: string | null;
-    localDay: LocalDayContext;
-    timeback?: UserTimebackProfile;
-}
+type CaliperSubject = (typeof TIMEBACK_SUBJECTS)[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;
 
 /**
- * Game Types
+ * TimeBack Configuration Types
  *
- * Literal types and API DTOs. Database row types are in @playcademy/data/types.
+ * Configuration interfaces for Organization, Course, Component,
+ * Resource, and complete TimeBack setup.
  *
- * @module types/game
+ * @module types/timeback/config
  */
 
-type GameType = 'hosted' | 'external';
-type GamePlatform = 'web' | 'godot' | (string & {});
 /**
- * Game manifest file format (manifest.json).
- * Note: createdAt is a string here because it's parsed from JSON file.
+ * Organization configuration for TimeBack (user input - optionals allowed)
  */
-interface ManifestV1 {
-    version: '1';
-    platform: string;
-    createdAt: string;
-}
-interface ManifestVersions {
-    vitePlugin?: string;
-    sdk?: string;
-    cli?: string;
-    vite?: string;
-    godotSdk?: string;
-    godot?: string;
-}
-interface ManifestV2 {
-    version: '2';
-    platform: string;
-    createdAt: string;
-    gameVersion?: string;
-    versions: ManifestVersions;
+interface OrganizationConfig {
+    /** Display name for your organization */
+    name?: string;
+    /** Organization type */
+    type?: OrganizationType;
+    /** Unique identifier (defaults to Playcademy's org) */
+    identifier?: string;
 }
-type GameManifest = ManifestV1 | ManifestV2;
 /**
- * Git provenance of the working tree a deploy was run from (PLA-294).
- *
- * Captured by the CLI at deploy time and persisted verbatim on the deploy
- * job, so "which commit is running" is answerable from the platform record.
- * Every field is nullable: a tree with no git, no remote, or a detached HEAD
- * is recorded honestly rather than refused. Recorded per deploy, never
- * pinned to the game — a fork deployed under the same slug shows the fork.
+ * Course goals for daily student targets
  */
-interface DeploySource {
-    /** Normalized `https://github.com/<org>/<repo>`; null when no remote or unparseable */
-    repository: string | null;
-    /** Full 40-char SHA of HEAD; null when not in a git tree */
-    commit: string | null;
-    /** Current branch name; null on detached HEAD outside CI */
-    branch: string | null;
-    /** True when the tree had uncommitted changes — the SHA does not describe what shipped */
-    dirty: boolean;
-    /**
-     * True when the uploaded build artifact lives outside the git tree the
-     * other fields describe (`--build ~/Downloads/game.zip`). The commit is
-     * still the deployer's tree, but it may not be what produced the artifact.
-     */
-    externalBuild: boolean;
+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;
 }
 /**
- * One successful deploy of a game's worker, as the open releases surface
- * describes it: what is running and which commit produced it.
- *
- * This shape is parsed by external automation. Every field is present on
- * every entry — nullable, never absent — and nothing from the deploy job
- * beyond its git provenance and completion time is exposed. No deployer
- * identity, no schema state, no secrets manifest.
+ * Course metrics and totals
  */
-interface Release {
-    slug: string;
-    /** Where the game is served; null when the platform has no URL for it */
-    url: string | null;
-    /**
-     * Git provenance the deploying CLI captured. Null for deploys that
-     * predate provenance capture, so the fleet list is complete on day one
-     * and a consumer can tell "unknown" from "not in git".
-     */
-    source: DeploySource | null;
-    /** When the deploy succeeded, ISO 8601 */
-    deployedAt: string;
-}
-/** GET /api/releases — the current release of every game */
-interface ReleasesResponse {
-    releases: Release[];
-}
-/** GET /api/releases/:slug — one game's current release and, on request, its recent history */
-interface GameReleaseResponse {
-    /** The current release; null when the game has never deployed successfully */
-    current: Release | null;
-    /**
-     * The last N successful deploys, newest first, current included. Only
-     * present when `?history=N` was requested.
-     */
-    history?: Release[];
-}
-interface DomainValidationRecords {
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    ssl?: {
-        txt_name?: string;
-        txt_value?: string;
-    }[];
-}
-
-/**
- * Leaderboard Types
- *
- * @module types/leaderboard
- */
-type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
-interface LeaderboardOptions {
-    timeframe?: LeaderboardTimeframe;
-    limit?: number;
-    offset?: number;
-    gameId?: string;
-}
-interface LeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId?: string;
-    gameTitle?: string;
-    gameSlug?: string;
-}
-interface UserRank {
-    rank: number;
-    totalPlayers: number;
-    score: number;
-    percentile: number;
-}
-interface UserRankResponse {
-    rank: number;
-    score: number;
-    userId: string;
-}
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
-}
-/**
- * Leaderboard entry with required game context.
- * Used when fetching leaderboards for a specific game.
- */
-interface GameLeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
-}
-
-/**
- * Skill Status Types
- *
- * Contract for cross-game skill status queries. An answering game exports
- * `getSkillStatus` from `server/lib/skills.ts`; the platform calls its
- * reserved `/__playcademy/skills/status` route on behalf of another game.
- *
- * @module types/skills
- */
-
-/**
- * Current status of one skill for one student, as judged by the answering game.
- *
- * - `locked`: the student can't work on the skill yet in this game.
- * - `unlocked`: available to the student, but no progress yet.
- * - `in_progress`: started, not mastered.
- * - `mastered`: currently meets this game's mastery bar, including by placement.
- * - `unknown_skill`: the skill ID isn't recognized. Never report an unrecognized
- *   skill as `locked`.
- */
-type SkillStatus = (typeof SKILL_STATUSES)[number];
-/** How a `mastered` status was reached. */
-type SkillMasterySource = (typeof SKILL_MASTERY_SOURCES)[number];
-interface SkillStatusResult {
-    /** Skill ID, lowercase. */
-    skill: string;
-    /** Current status. */
-    status: SkillStatus;
-    /** How mastery was reached. Only allowed when `status` is `mastered`. */
-    source?: SkillMasterySource;
-    /** ISO 8601 time of the evidence behind this status. */
-    asOf?: string;
-}
-/** Response returned by an answering game's `getSkillStatus` handler. */
-interface SkillStatusResponse {
-    /** Student identifier (Playcademy user ID). Must match the requested student. */
-    studentId: string;
-    /** One result per skill the handler was asked about. */
-    results: SkillStatusResult[];
-}
-/** The game asking for skill status, as identified by the platform. */
-interface SkillStatusRequestingGame {
-    id: string;
-    slug: string;
-}
-/** Body of `POST /api/skills/status`, sent by the asking game's worker. */
-interface SkillStatusRequest {
-    /** Slug of the game to ask. */
-    game: string;
-    /** Playcademy user ID of the student. */
-    studentId: string;
-    /** Skill IDs to ask about. Normalized (trimmed, lowercased) and de-duplicated. */
-    skills: string[];
-}
-/** Why the answering game couldn't answer. */
-type SkillStatusUnsupportedReason = 'not_implemented' | 'no_active_deployment' | 'timeout' | 'fetch_failed' | 'invalid_response';
-/**
- * What the asking game gets back. When `supported` is false, fall back to
- * the game's own default (usually: treat the skills as not mastered).
- */
-type SkillStatusLookupResult = {
-    supported: true;
-    results: SkillStatusResult[];
-} | {
-    supported: false;
-    reason: SkillStatusUnsupportedReason;
-};
-
-/**
- * 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];
-/**
- * Platform pedagogy levels for a single lesson of instruction.
- * E1 teaches, E2/E3 practice and remediate, E4 is the mastery check.
- */
-type ELevel = 'E1' | 'E2' | 'E3' | 'E4';
-/**
- * Valid Caliper subject values. The same vocabulary as OneRoster subjects.
- */
-type CaliperSubject = (typeof TIMEBACK_SUBJECTS)[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;
+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
@@ -838,12 +488,22 @@ interface PopulateStudentResponse {
     status: string;
     message?: string;
 }
+/**
+ * `base` courses form a game's grade ladder (one active per grade and subject).
+ * `hole_filling` courses are remediation courses Timeback enrolls students into
+ * after a failed test; each sits beside a base course.
+ */
+type GameTimebackIntegrationKind = 'base' | 'hole_filling';
 interface GameTimebackIntegration {
     id: string;
     gameId: string;
     courseId: string;
     grade: number;
     subject: string;
+    /** Defaults to `base` when absent (responses from older servers). */
+    kind?: GameTimebackIntegrationKind;
+    /** The base course a hole-filling course belongs to; null for base courses. */
+    baseIntegrationId?: string | null;
     status?: 'active' | 'deactivated';
     totalXp?: number | null;
     lastVerifiedAt?: Date | null;
@@ -1735,6 +1395,370 @@ interface AssessmentAwardRecord extends AssessmentMasteryAward {
     warnings?: MasteryWriteWarning[];
 }
 
+/**
+ * User Types
+ *
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
+ */
+
+type UserRoleEnumType = UserRole;
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type DeveloperStatusValue = DeveloperStatusEnumType;
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface UserEnrollment {
+    gameId?: string;
+    courseId: string;
+    id?: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+    /**
+     * `base` for the game's grade courses, `hole_filling` for a remediation
+     * course Timeback enrolled the student in. Absent means `base`.
+     */
+    kind?: GameTimebackIntegrationKind;
+    /** For hole-filling enrollments: the course ID of the base course it belongs to. */
+    baseCourseId?: string;
+    /** For hole-filling enrollments: when the enrollment started (ISO 8601). */
+    beginDate?: string | null;
+    /**
+     * For hole-filling enrollments: enrollment metadata as set by Timeback
+     * (e.g. `assignmentId`, `testType`). Every field is optional.
+     */
+    enrollmentMetadata?: Record<string, unknown>;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+/**
+ * Timeback identity on `/users/me`: who the student is, without enrollments.
+ * Enrollments come from `/timeback/user` (or `client.timeback.user`).
+ */
+interface UserTimebackProfile extends TimebackStudentProfile {
+    id: string;
+}
+interface UserTimebackData extends UserTimebackProfile {
+    enrollments: UserEnrollment[];
+}
+type LocalDaySource = 'browser_last_seen' | 'platform_default';
+interface LocalDayContext {
+    timeZone: string;
+    source: LocalDaySource;
+    /** ISO 8601 timestamp for the last persisted timezone observation. */
+    observedAt: string | null;
+}
+/**
+ * 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;
+}
+interface DeveloperStatusResponse {
+    status: DeveloperStatusEnumType;
+}
+interface DemoProfile {
+    displayName: string;
+    isDefault: boolean;
+}
+/**
+ * Update shape for `client.demo.profile.update(...)`.
+ *
+ * Kept as a named type so callers typed against it pick up new fields
+ * automatically, but `displayName` is the only updatable field today and
+ * the server's `DemoProfileSchema` requires it — a no-field payload would
+ * 400 at runtime, so we model that at the type level too. When additional
+ * fields land, make them required/optional individually based on server
+ * validation, rather than blanket-optional.
+ */
+interface DemoProfileUpdate {
+    displayName: string;
+}
+/**
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ */
+interface AuthenticatedUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    username: string | null;
+    role: UserRoleEnumType;
+    developerStatus: DeveloperStatusEnumType;
+    createdAt: Date;
+    updatedAt: Date;
+    hasTimebackAccount: boolean;
+    localDay: LocalDayContext;
+    timeback?: UserTimebackProfile;
+}
+interface GameUser {
+    id: string;
+    name: string | null;
+    role: UserRoleEnumType;
+    username: string | null;
+    email: string | null;
+    localDay: LocalDayContext;
+    timeback?: UserTimebackProfile;
+}
+
+/**
+ * Game Types
+ *
+ * Literal types and API DTOs. Database row types are in @playcademy/data/types.
+ *
+ * @module types/game
+ */
+
+type GameType = 'hosted' | 'external';
+type GamePlatform = 'web' | 'godot' | (string & {});
+/**
+ * Game manifest file format (manifest.json).
+ * Note: createdAt is a string here because it's parsed from JSON file.
+ */
+interface ManifestV1 {
+    version: '1';
+    platform: string;
+    createdAt: string;
+}
+interface ManifestVersions {
+    vitePlugin?: string;
+    sdk?: string;
+    cli?: string;
+    vite?: string;
+    godotSdk?: string;
+    godot?: string;
+}
+interface ManifestV2 {
+    version: '2';
+    platform: string;
+    createdAt: string;
+    gameVersion?: string;
+    versions: ManifestVersions;
+}
+type GameManifest = ManifestV1 | ManifestV2;
+/**
+ * Git provenance of the working tree a deploy was run from (PLA-294).
+ *
+ * Captured by the CLI at deploy time and persisted verbatim on the deploy
+ * job, so "which commit is running" is answerable from the platform record.
+ * Every field is nullable: a tree with no git, no remote, or a detached HEAD
+ * is recorded honestly rather than refused. Recorded per deploy, never
+ * pinned to the game — a fork deployed under the same slug shows the fork.
+ */
+interface DeploySource {
+    /** Normalized `https://github.com/<org>/<repo>`; null when no remote or unparseable */
+    repository: string | null;
+    /** Full 40-char SHA of HEAD; null when not in a git tree */
+    commit: string | null;
+    /** Current branch name; null on detached HEAD outside CI */
+    branch: string | null;
+    /** True when the tree had uncommitted changes — the SHA does not describe what shipped */
+    dirty: boolean;
+    /**
+     * True when the uploaded build artifact lives outside the git tree the
+     * other fields describe (`--build ~/Downloads/game.zip`). The commit is
+     * still the deployer's tree, but it may not be what produced the artifact.
+     */
+    externalBuild: boolean;
+}
+/**
+ * One successful deploy of a game's worker, as the open releases surface
+ * describes it: what is running and which commit produced it.
+ *
+ * This shape is parsed by external automation. Every field is present on
+ * every entry — nullable, never absent — and nothing from the deploy job
+ * beyond its git provenance and completion time is exposed. No deployer
+ * identity, no schema state, no secrets manifest.
+ */
+interface Release {
+    slug: string;
+    /** Where the game is served; null when the platform has no URL for it */
+    url: string | null;
+    /**
+     * Git provenance the deploying CLI captured. Null for deploys that
+     * predate provenance capture, so the fleet list is complete on day one
+     * and a consumer can tell "unknown" from "not in git".
+     */
+    source: DeploySource | null;
+    /** When the deploy succeeded, ISO 8601 */
+    deployedAt: string;
+}
+/** GET /api/releases — the current release of every game */
+interface ReleasesResponse {
+    releases: Release[];
+}
+/** GET /api/releases/:slug — one game's current release and, on request, its recent history */
+interface GameReleaseResponse {
+    /** The current release; null when the game has never deployed successfully */
+    current: Release | null;
+    /**
+     * The last N successful deploys, newest first, current included. Only
+     * present when `?history=N` was requested.
+     */
+    history?: Release[];
+}
+interface DomainValidationRecords {
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
+}
+
+/**
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
+ */
+type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
+interface LeaderboardOptions {
+    timeframe?: LeaderboardTimeframe;
+    limit?: number;
+    offset?: number;
+    gameId?: string;
+}
+interface LeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId?: string;
+    gameTitle?: string;
+    gameSlug?: string;
+}
+interface UserRank {
+    rank: number;
+    totalPlayers: number;
+    score: number;
+    percentile: number;
+}
+interface UserRankResponse {
+    rank: number;
+    score: number;
+    userId: string;
+}
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+/**
+ * Leaderboard entry with required game context.
+ * Used when fetching leaderboards for a specific game.
+ */
+interface GameLeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+
+/**
+ * Skill Status Types
+ *
+ * Contract for cross-game skill status queries. An answering game exports
+ * `getSkillStatus` from `server/lib/skills.ts`; the platform calls its
+ * reserved `/__playcademy/skills/status` route on behalf of another game.
+ *
+ * @module types/skills
+ */
+
+/**
+ * Current status of one skill for one student, as judged by the answering game.
+ *
+ * - `locked`: the student can't work on the skill yet in this game.
+ * - `unlocked`: available to the student, but no progress yet.
+ * - `in_progress`: started, not mastered.
+ * - `mastered`: currently meets this game's mastery bar, including by placement.
+ * - `unknown_skill`: the skill ID isn't recognized. Never report an unrecognized
+ *   skill as `locked`.
+ */
+type SkillStatus = (typeof SKILL_STATUSES)[number];
+/** How a `mastered` status was reached. */
+type SkillMasterySource = (typeof SKILL_MASTERY_SOURCES)[number];
+interface SkillStatusResult {
+    /** Skill ID, lowercase. */
+    skill: string;
+    /** Current status. */
+    status: SkillStatus;
+    /** How mastery was reached. Only allowed when `status` is `mastered`. */
+    source?: SkillMasterySource;
+    /** ISO 8601 time of the evidence behind this status. */
+    asOf?: string;
+}
+/** Response returned by an answering game's `getSkillStatus` handler. */
+interface SkillStatusResponse {
+    /** Student identifier (Playcademy user ID). Must match the requested student. */
+    studentId: string;
+    /** One result per skill the handler was asked about. */
+    results: SkillStatusResult[];
+}
+/** The game asking for skill status, as identified by the platform. */
+interface SkillStatusRequestingGame {
+    id: string;
+    slug: string;
+}
+/** Body of `POST /api/skills/status`, sent by the asking game's worker. */
+interface SkillStatusRequest {
+    /** Slug of the game to ask. */
+    game: string;
+    /** Playcademy user ID of the student. */
+    studentId: string;
+    /** Skill IDs to ask about. Normalized (trimmed, lowercased) and de-duplicated. */
+    skills: string[];
+}
+/** Why the answering game couldn't answer. */
+type SkillStatusUnsupportedReason = 'not_implemented' | 'no_active_deployment' | 'timeout' | 'fetch_failed' | 'invalid_response';
+/**
+ * What the asking game gets back. When `supported` is false, fall back to
+ * the game's own default (usually: treat the skills as not mastered).
+ */
+type SkillStatusLookupResult = {
+    supported: true;
+    results: SkillStatusResult[];
+} | {
+    supported: false;
+    reason: SkillStatusUnsupportedReason;
+};
+
 /**
  * Base error class for Cademy SDK specific errors.
  */