@playcademy/sdk 0.24.0 → 0.24.1-beta.2

package/dist/index.d.ts

@@ -225,132 +225,6 @@ declare const ASSESSMENT_PURPOSES: readonly ['end_of_course', 'diagnostic', 'rev
  */
 declare const PLAYCADEMY_ASSESSMENT_CONTRACT_VERSION: 2;
 
-/**
- * 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 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`).
- */
-interface UserTimebackProfile extends TimebackStudentProfile {
-    id: string;
-}
-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 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;
-}
-
-/**
- * Leaderboard Types
- *
- * @module types/leaderboard
- */
-type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
-interface LeaderboardOptions {
-    timeframe?: LeaderboardTimeframe;
-    limit?: number;
-    offset?: number;
-    gameId?: 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;
-}
-
 /**
  * TimeBack Enums & Literal Types
  *
@@ -423,8 +297,18 @@ interface ActivityData {
     subject: CaliperSubject;
     /** Activity display name (optional) */
     activityName?: string;
-    /** Course identifier (auto-filled from config if not provided) */
+    /**
+     * Optional course to report against. When omitted, the SDK fills it from
+     * the student's enrollment for this grade/subject (preferring a
+     * hole-filling course). The platform uses it if it's the base course or one
+     * of that grade/subject's hole-filling courses, otherwise the base course.
+     */
     courseId?: string;
+    /**
+     * The student's enrollment in `courseId`. Filled by the SDK alongside an
+     * automatic `courseId`; recorded on hole-filling Caliper events.
+     */
+    enrollmentId?: string;
     /** Course display name (auto-filled from config if not provided) */
     courseName?: string;
     /** Student email address (optional) */
@@ -494,6 +378,12 @@ interface EndActivityScoreData {
  * @module types/timeback/api
  */
 
+/**
+ * `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 HeartbeatRequestBase {
     gameId: string;
     studentId: string;
@@ -515,6 +405,8 @@ interface HeartbeatRequestBase {
         appName?: string;
         sensorUrl?: string;
         courseId?: string;
+        /** The student's enrollment in `courseId`, sent by the SDK with the course hint. */
+        enrollmentId?: string;
         courseName?: string;
         studentEmail?: string;
     };
@@ -568,6 +460,8 @@ interface EndActivityRequest {
         appName?: string;
         sensorUrl?: string;
         courseId?: string;
+        /** The student's enrollment in `courseId`, sent by the SDK with the course hint. */
+        enrollmentId?: string;
         courseName?: string;
         studentEmail?: string;
     };
@@ -597,7 +491,14 @@ interface TimebackPromotionResult {
 }
 interface EndActivityResponse {
     status: 'ok';
+    /** The course the activity was recorded against. */
     courseId: string;
+    /**
+     * `'hole_filling'` when the activity was recorded against a hole-filling
+     * course (the student is enrolled there, or the game passed its
+     * `courseId`); `'base'` otherwise.
+     */
+    courseKind?: GameTimebackIntegrationKind;
     xpAwarded: number;
     masteredUnits?: number;
     pctCompleteApp?: number;
@@ -1353,6 +1254,146 @@ interface FinalizeAssessmentInput extends AssessmentMasteryAward {
     xpAwarded: number;
 }
 
+/**
+ * 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 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;
+}
+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 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;
+}
+
+/**
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
+ */
+type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
+interface LeaderboardOptions {
+    timeframe?: LeaderboardTimeframe;
+    limit?: number;
+    offset?: number;
+    gameId?: 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;
+}
+
 /**
  * Cache configuration types for runtime customization
  */
@@ -3020,6 +3061,8 @@ interface EmbedTimebackRecording {
     subject: TimebackSubject;
     /** Course id hint, same semantics as `startActivity()`. */
     courseId?: string;
+    /** The student's enrollment in `courseId`; filled with it automatically. */
+    enrollmentId?: string;
 }
 /**
  * Everything a parent needs to resume an interrupted launch later. The

package/dist/index.js

@@ -2289,6 +2289,23 @@ function createTimebackActivityTracker(client) {
   };
 }
 
+// src/core/timeback/course-hint.ts
+function withEnrollmentCourseHint(metadata, enrollments) {
+  if (metadata.courseId !== undefined) {
+    return metadata;
+  }
+  const matching = enrollments.filter((enrollment) => enrollment.grade === metadata.grade && enrollment.subject === metadata.subject);
+  const enrollment = matching.find((candidate) => candidate.kind === "hole_filling") ?? matching[0];
+  if (!enrollment) {
+    return metadata;
+  }
+  return {
+    ...metadata,
+    courseId: enrollment.courseId,
+    ...enrollment.id && { enrollmentId: enrollment.id }
+  };
+}
+
 // src/namespaces/game/embed.ts
 function createEmbedNamespace(client) {
   return {
@@ -2325,7 +2342,7 @@ function createEmbedNamespace(client) {
       const session = new ChildSession({
         slug: options.slug,
         container: options.container,
-        timeback: options.timeback,
+        timeback: options.timeback && withEnrollmentCourseHint(options.timeback, client.timeback.user?.enrollments ?? []),
         resume: resume.envelope,
         resumeStore: resume.store,
         reporter: {
@@ -3023,7 +3040,7 @@ function createTimebackEngine(client) {
     activity: {
       currentRunId: activityTracker.currentRunId,
       isManuallyPaused: activityTracker.isActivityManuallyPaused,
-      start: activityTracker.startActivity,
+      start: (metadata, options) => activityTracker.startActivity(withEnrollmentCourseHint(metadata, userStore.snapshot()?.enrollments ?? []), options),
       tryStartAssessment: activityTracker.tryStartAssessmentTracking,
       pause: activityTracker.pauseActivity,
       resume: activityTracker.resumeActivity,
@@ -3765,7 +3782,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.24.0";
+var SDK_VERSION = "0.24.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {