@playcademy/sdk 0.24.0 → 0.24.1-beta.2

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,
@@ -4334,6 +4351,8 @@ function createTimebackNamespace2(client) {
       get: (gameId) => client["request"](`/timeback/integrations/${gameId}`, "GET"),
       getRemovedIntegrations: (gameId) => client["request"](`/timeback/integrations/${gameId}/removed`, "GET"),
       createIntegration: (gameId, request) => client["request"](`/timeback/integrations/${gameId}`, "POST", { body: request }),
+      getHoleFillingCourses: (gameId) => client["request"](`/timeback/integrations/${gameId}/hole-filling`, "GET"),
+      createHoleFillingCourse: (gameId, request) => client["request"](`/timeback/integrations/${gameId}/hole-filling`, "POST", { body: request }),
       updateIntegration: (gameId, courseId, request) => client["request"](`/timeback/integrations/${gameId}/${courseId}`, "PATCH", { body: request }),
       deactivateCourse: (gameId, courseId) => client["request"](`/timeback/integrations/${gameId}/${courseId}`, "DELETE"),
       reactivateCourse: (gameId, courseId) => client["request"](`/timeback/integrations/${gameId}/${courseId}/reactivate`, "POST"),
@@ -4683,7 +4702,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 {

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.0";
+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.0";
+var SDK_VERSION = "0.24.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {