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

package/dist/index.d.ts

@@ -297,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) */
@@ -395,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;
     };
@@ -448,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;
     };
@@ -477,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;
@@ -3040,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.1-beta.1";
+var SDK_VERSION = "0.24.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -349,8 +349,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) */
@@ -909,6 +919,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;
     };
@@ -962,6 +974,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;
     };
@@ -983,7 +997,14 @@ interface EndActivityRequest {
 }
 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;
@@ -6079,6 +6100,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/internal.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,
@@ -4685,7 +4702,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.24.1-beta.1";
+var SDK_VERSION = "0.24.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.d.ts

@@ -319,8 +319,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) */
@@ -382,9 +392,22 @@ interface EndActivityPayload {
  * @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 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;

package/dist/server/edge.js

@@ -361,7 +361,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.24.1-beta.1";
+var SDK_VERSION = "0.24.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.d.ts

@@ -319,8 +319,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) */
@@ -382,9 +392,22 @@ interface EndActivityPayload {
  * @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 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;

package/dist/server.js

@@ -557,7 +557,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.24.1-beta.1";
+var SDK_VERSION = "0.24.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/types.d.ts

@@ -356,8 +356,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) */
@@ -533,6 +543,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;
     };
@@ -586,6 +598,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;
     };
@@ -615,7 +629,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;
@@ -4013,6 +4034,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.24.1-beta.1",
+    "version": "0.24.1-beta.2",
     "type": "module",
     "exports": {
         ".": {