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

package/dist/index.d.ts

@@ -535,6 +535,71 @@ interface UnenrollCourseResponse {
     status: 'ok';
     unenrollment: TimebackUnenrollmentResult;
 }
+/**
+ * The test result that sent a student into a hole-filling course: the
+ * assignment Timeback stamped on the hole-filling enrollment.
+ */
+interface HoleFillingTriggeringResult {
+    /** OneRoster assessment result id. */
+    resultId: string;
+    /** AlphaTest assignment id, always a string. */
+    assignmentId: string;
+    /** OneRoster assessment line item id of the test. */
+    lineItemId: string;
+    testName: string;
+    testType: 'end of course' | 'test out' | 'placement';
+    /** The QTI assessment test, when it could be found. */
+    qtiTestId?: string;
+    /**
+     * The result's score as Timeback recorded it, on the test's own scale
+     * (AlphaTest tests score 0-100). Not rescaled.
+     */
+    score: number | null;
+    scoreDate: string | null;
+    totalQuestions: number | null;
+    correctQuestions: number | null;
+}
+/** A curriculum standard the student missed questions on. */
+interface HoleFillingMissedStandard {
+    /** Standards framework as named by the QTI item's alignment (canonicalized). */
+    framework: string;
+    /** Standard code, e.g. `K.OA.A.2`. */
+    code: string;
+    /** 1-based positions of the missed questions in the test. */
+    questionNumbers: number[];
+    /** QTI items of the missed questions. */
+    qtiItemIds: string[];
+}
+/** What a game needs to tailor a student's hole-filling course. */
+interface HoleFillingContext {
+    enrollment: {
+        /** The hole-filling course. */
+        courseId: string;
+        /** The base course it belongs to. */
+        baseCourseId: string;
+        /** The student's hole-filling enrollment. */
+        enrollmentId?: string;
+        grade: TimebackGrade;
+        subject: TimebackSubject;
+        beginDate?: string | null;
+    };
+    /**
+     * Null when Timeback hasn't stamped an assignment on the enrollment, or the
+     * stamped assignment has no fully graded test result yet.
+     */
+    triggeringResult: HoleFillingTriggeringResult | null;
+    /** Missed questions grouped by standard, most-missed first. */
+    missedStandards: HoleFillingMissedStandard[];
+    /** Missed questions whose item has no standard tag. */
+    untaggedMissedQuestionNumbers: number[];
+}
+/**
+ * Response from the hole-filling context endpoint: one entry per active
+ * hole-filling enrollment the student has in this game (usually zero or one).
+ */
+interface HoleFillingContextResponse {
+    contexts: HoleFillingContext[];
+}
 
 declare const DIAGNOSTIC_TRACK_OUTCOMES: readonly ['provisional', 'unresolved', 'route-to-instruction', 'not-assessed'];
 type DiagnosticTrackOutcome = (typeof DIAGNOSTIC_TRACK_OUTCOMES)[number];
@@ -2431,6 +2496,41 @@ interface TimebackUser extends TimebackUserContext {
      * highest mastered grade for a subject.
      */
     highestGradeMastered: TimebackUserHighestGradeMastered;
+    /**
+     * Hole-filling context for the current user.
+     * Call `holeFilling.fetch()` to learn why the student is in a
+     * hole-filling course and which standards to target.
+     */
+    holeFilling: TimebackUserHoleFilling;
+}
+/**
+ * Hole-filling context access for the current user.
+ * Results are cached for 5 minutes.
+ */
+interface TimebackUserHoleFilling {
+    /**
+     * Fetch the test result that sent the student into each of their
+     * hole-filling courses in this game, and the curriculum standards of the
+     * questions they missed (most-missed first).
+     *
+     * Returns `{ contexts: [] }` when the student has no hole-filling
+     * enrollment. Results are cached for 5 minutes (use `force: true` to
+     * bypass, e.g. after `user.refresh()` picks up a new enrollment).
+     *
+     * @param options - Cache options
+     * @returns Promise resolving to one context per hole-filling enrollment
+     *
+     * @example
+     * ```typescript
+     * const { contexts } = await client.timeback.user.holeFilling.fetch()
+     * const context = contexts.find(c => c.enrollment.subject === 'Math')
+     *
+     * if (context) {
+     *   const targetCodes = context.missedStandards.map(s => s.code) // ['K.OA.A.2', ...]
+     * }
+     * ```
+     */
+    fetch(options?: TTLCacheConfig): Promise<HoleFillingContextResponse>;
 }
 /**
  * Mastery data access for the current user.

package/dist/index.js

@@ -2930,6 +2930,10 @@ function createTimebackEngine(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.highestGradeMastered"
   });
+  const holeFillingCache = createTTLCache({
+    ttl: 5 * 60 * 1000,
+    keyPrefix: "game.timeback.holeFilling"
+  });
   const enrollmentsCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.enrollments"
@@ -2940,6 +2944,7 @@ function createTimebackEngine(client) {
     xpCache.clear();
     masteryCache.clear();
     highestGradeMasteredCache.clear();
+    holeFillingCache.clear();
     try {
       await userStore.refresh();
     } catch {}
@@ -3035,6 +3040,9 @@ function createTimebackEngine(client) {
           const endpoint = `${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}?${params.toString()}`;
           return client["requestGameBackend"](endpoint, "GET");
         }, { force: options.force })
+      },
+      holeFilling: {
+        fetch: (options) => holeFillingCache.get("current", () => client["request"]("/timeback/user/hole-filling-context", "GET"), options)
       }
     },
     activity: {
@@ -3452,6 +3460,9 @@ function createTimebackNamespace(client) {
             }
             return engine.user.highestGradeMastered.fetch(options);
           }
+        },
+        holeFilling: {
+          fetch: (options) => engine.user.holeFilling.fetch(options)
         }
       };
     },
@@ -3782,7 +3793,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.24.1-beta.2";
+var SDK_VERSION = "0.24.1-beta.4";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -1208,6 +1208,71 @@ interface TimebackGradeLevelTestReviewResponse {
     questions: TimebackGradeLevelTestQuestionResult[];
     standards: TimebackGradeLevelTestStandardSummary[];
 }
+/**
+ * The test result that sent a student into a hole-filling course: the
+ * assignment Timeback stamped on the hole-filling enrollment.
+ */
+interface HoleFillingTriggeringResult {
+    /** OneRoster assessment result id. */
+    resultId: string;
+    /** AlphaTest assignment id, always a string. */
+    assignmentId: string;
+    /** OneRoster assessment line item id of the test. */
+    lineItemId: string;
+    testName: string;
+    testType: 'end of course' | 'test out' | 'placement';
+    /** The QTI assessment test, when it could be found. */
+    qtiTestId?: string;
+    /**
+     * The result's score as Timeback recorded it, on the test's own scale
+     * (AlphaTest tests score 0-100). Not rescaled.
+     */
+    score: number | null;
+    scoreDate: string | null;
+    totalQuestions: number | null;
+    correctQuestions: number | null;
+}
+/** A curriculum standard the student missed questions on. */
+interface HoleFillingMissedStandard {
+    /** Standards framework as named by the QTI item's alignment (canonicalized). */
+    framework: string;
+    /** Standard code, e.g. `K.OA.A.2`. */
+    code: string;
+    /** 1-based positions of the missed questions in the test. */
+    questionNumbers: number[];
+    /** QTI items of the missed questions. */
+    qtiItemIds: string[];
+}
+/** What a game needs to tailor a student's hole-filling course. */
+interface HoleFillingContext {
+    enrollment: {
+        /** The hole-filling course. */
+        courseId: string;
+        /** The base course it belongs to. */
+        baseCourseId: string;
+        /** The student's hole-filling enrollment. */
+        enrollmentId?: string;
+        grade: TimebackGrade;
+        subject: TimebackSubject;
+        beginDate?: string | null;
+    };
+    /**
+     * Null when Timeback hasn't stamped an assignment on the enrollment, or the
+     * stamped assignment has no fully graded test result yet.
+     */
+    triggeringResult: HoleFillingTriggeringResult | null;
+    /** Missed questions grouped by standard, most-missed first. */
+    missedStandards: HoleFillingMissedStandard[];
+    /** Missed questions whose item has no standard tag. */
+    untaggedMissedQuestionNumbers: number[];
+}
+/**
+ * Response from the hole-filling context endpoint: one entry per active
+ * hole-filling enrollment the student has in this game (usually zero or one).
+ */
+interface HoleFillingContextResponse {
+    contexts: HoleFillingContext[];
+}
 type TimebackDiscrepancyQueueWindow = 'all' | 'today' | 'yesterday' | 'this-week' | 'last-week' | 'custom';
 interface TimebackDiscrepancyQueueDateRange {
     startDate?: string;
@@ -5627,6 +5692,41 @@ interface TimebackUser extends TimebackUserContext {
      * highest mastered grade for a subject.
      */
     highestGradeMastered: TimebackUserHighestGradeMastered;
+    /**
+     * Hole-filling context for the current user.
+     * Call `holeFilling.fetch()` to learn why the student is in a
+     * hole-filling course and which standards to target.
+     */
+    holeFilling: TimebackUserHoleFilling;
+}
+/**
+ * Hole-filling context access for the current user.
+ * Results are cached for 5 minutes.
+ */
+interface TimebackUserHoleFilling {
+    /**
+     * Fetch the test result that sent the student into each of their
+     * hole-filling courses in this game, and the curriculum standards of the
+     * questions they missed (most-missed first).
+     *
+     * Returns `{ contexts: [] }` when the student has no hole-filling
+     * enrollment. Results are cached for 5 minutes (use `force: true` to
+     * bypass, e.g. after `user.refresh()` picks up a new enrollment).
+     *
+     * @param options - Cache options
+     * @returns Promise resolving to one context per hole-filling enrollment
+     *
+     * @example
+     * ```typescript
+     * const { contexts } = await client.timeback.user.holeFilling.fetch()
+     * const context = contexts.find(c => c.enrollment.subject === 'Math')
+     *
+     * if (context) {
+     *   const targetCodes = context.missedStandards.map(s => s.code) // ['K.OA.A.2', ...]
+     * }
+     * ```
+     */
+    fetch(options?: TTLCacheConfig): Promise<HoleFillingContextResponse>;
 }
 /**
  * Mastery data access for the current user.
@@ -7366,4 +7466,4 @@ interface BeginInitHandshakeOptions {
 declare function beginInitHandshake({ iframe, origin, payload, onTimeout, onSendError }: BeginInitHandshakeOptions): () => void;
 
 export { ApiError, HANDSHAKE_MAX_DURATION_MS, HANDSHAKE_RESEND_INTERVAL_MS, INIT_WAIT_TIMEOUT_MS, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, beginInitHandshake, extractApiErrorInfo, isTrustedIframeMessage, messaging };
-export type { ApiErrorCode, ApiErrorInfo, AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemOutcome, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentReviewStandard, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, AssessmentTranscript, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DeploySource, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, FinalizeAssessmentInput, Game, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameReleaseResponse, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MasteryAssessmentSubmitResult, MasteryResponse, MessageEventMap, ParentGameContext, ParentGameHandle, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlatformTimebackUser, PlatformTimebackUserContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableChoiceInteraction, PlayableContentNode, PlayableGapMatchChoice, PlayableGapMatchInteraction, PlayableInlineChoiceInteraction, PlayableMatchChoice, PlayableMatchInteraction, PlayableOrderInteraction, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PopulateStudentResponse, RecordAssessmentProgressInput, Release, ReleasesResponse, ResumeAssessmentInput, SaveAssessmentInput, ScoreSubmission, SettledAssessmentAttemptSnapshot, SkillMasterySource, SkillStatus, SkillStatusLookupResult, SkillStatusRequest, SkillStatusRequestingGame, SkillStatusResponse, SkillStatusResult, SkillStatusUnsupportedReason, StandardsReviewSelectionContext, StartActivityOptions, StartActivityResult, StartAssessmentInput, StartAssessmentOptions, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, UserTimebackProfile, XpResponse };
+export type { ApiErrorCode, ApiErrorInfo, AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemOutcome, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentReviewStandard, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, AssessmentTranscript, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DeploySource, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, FinalizeAssessmentInput, Game, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameReleaseResponse, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HoleFillingContext, HoleFillingContextResponse, HoleFillingMissedStandard, HoleFillingTriggeringResult, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MasteryAssessmentSubmitResult, MasteryResponse, MessageEventMap, ParentGameContext, ParentGameHandle, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlatformTimebackUser, PlatformTimebackUserContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableChoiceInteraction, PlayableContentNode, PlayableGapMatchChoice, PlayableGapMatchInteraction, PlayableInlineChoiceInteraction, PlayableMatchChoice, PlayableMatchInteraction, PlayableOrderInteraction, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PopulateStudentResponse, RecordAssessmentProgressInput, Release, ReleasesResponse, ResumeAssessmentInput, SaveAssessmentInput, ScoreSubmission, SettledAssessmentAttemptSnapshot, SkillMasterySource, SkillStatus, SkillStatusLookupResult, SkillStatusRequest, SkillStatusRequestingGame, SkillStatusResponse, SkillStatusResult, SkillStatusUnsupportedReason, StandardsReviewSelectionContext, StartActivityOptions, StartActivityResult, StartAssessmentInput, StartAssessmentOptions, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserHoleFilling, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, UserTimebackProfile, XpResponse };

package/dist/internal.js

@@ -2930,6 +2930,10 @@ function createTimebackEngine(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.highestGradeMastered"
   });
+  const holeFillingCache = createTTLCache({
+    ttl: 5 * 60 * 1000,
+    keyPrefix: "game.timeback.holeFilling"
+  });
   const enrollmentsCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.enrollments"
@@ -2940,6 +2944,7 @@ function createTimebackEngine(client) {
     xpCache.clear();
     masteryCache.clear();
     highestGradeMasteredCache.clear();
+    holeFillingCache.clear();
     try {
       await userStore.refresh();
     } catch {}
@@ -3035,6 +3040,9 @@ function createTimebackEngine(client) {
           const endpoint = `${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}?${params.toString()}`;
           return client["requestGameBackend"](endpoint, "GET");
         }, { force: options.force })
+      },
+      holeFilling: {
+        fetch: (options) => holeFillingCache.get("current", () => client["request"]("/timeback/user/hole-filling-context", "GET"), options)
       }
     },
     activity: {
@@ -3452,6 +3460,9 @@ function createTimebackNamespace(client) {
             }
             return engine.user.highestGradeMastered.fetch(options);
           }
+        },
+        holeFilling: {
+          fetch: (options) => engine.user.holeFilling.fetch(options)
         }
       };
     },
@@ -4702,7 +4713,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.24.1-beta.2";
+var SDK_VERSION = "0.24.1-beta.4";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.js

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

package/dist/server.js

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

package/dist/types.d.ts

@@ -673,6 +673,71 @@ interface UnenrollCourseResponse {
     status: 'ok';
     unenrollment: TimebackUnenrollmentResult;
 }
+/**
+ * The test result that sent a student into a hole-filling course: the
+ * assignment Timeback stamped on the hole-filling enrollment.
+ */
+interface HoleFillingTriggeringResult {
+    /** OneRoster assessment result id. */
+    resultId: string;
+    /** AlphaTest assignment id, always a string. */
+    assignmentId: string;
+    /** OneRoster assessment line item id of the test. */
+    lineItemId: string;
+    testName: string;
+    testType: 'end of course' | 'test out' | 'placement';
+    /** The QTI assessment test, when it could be found. */
+    qtiTestId?: string;
+    /**
+     * The result's score as Timeback recorded it, on the test's own scale
+     * (AlphaTest tests score 0-100). Not rescaled.
+     */
+    score: number | null;
+    scoreDate: string | null;
+    totalQuestions: number | null;
+    correctQuestions: number | null;
+}
+/** A curriculum standard the student missed questions on. */
+interface HoleFillingMissedStandard {
+    /** Standards framework as named by the QTI item's alignment (canonicalized). */
+    framework: string;
+    /** Standard code, e.g. `K.OA.A.2`. */
+    code: string;
+    /** 1-based positions of the missed questions in the test. */
+    questionNumbers: number[];
+    /** QTI items of the missed questions. */
+    qtiItemIds: string[];
+}
+/** What a game needs to tailor a student's hole-filling course. */
+interface HoleFillingContext {
+    enrollment: {
+        /** The hole-filling course. */
+        courseId: string;
+        /** The base course it belongs to. */
+        baseCourseId: string;
+        /** The student's hole-filling enrollment. */
+        enrollmentId?: string;
+        grade: TimebackGrade;
+        subject: TimebackSubject;
+        beginDate?: string | null;
+    };
+    /**
+     * Null when Timeback hasn't stamped an assignment on the enrollment, or the
+     * stamped assignment has no fully graded test result yet.
+     */
+    triggeringResult: HoleFillingTriggeringResult | null;
+    /** Missed questions grouped by standard, most-missed first. */
+    missedStandards: HoleFillingMissedStandard[];
+    /** Missed questions whose item has no standard tag. */
+    untaggedMissedQuestionNumbers: number[];
+}
+/**
+ * Response from the hole-filling context endpoint: one entry per active
+ * hole-filling enrollment the student has in this game (usually zero or one).
+ */
+interface HoleFillingContextResponse {
+    contexts: HoleFillingContext[];
+}
 
 declare const DIAGNOSTIC_TRACK_OUTCOMES: readonly ['provisional', 'unresolved', 'route-to-instruction', 'not-assessed'];
 type DiagnosticTrackOutcome = (typeof DIAGNOSTIC_TRACK_OUTCOMES)[number];
@@ -3395,6 +3460,41 @@ interface TimebackUser extends TimebackUserContext {
      * highest mastered grade for a subject.
      */
     highestGradeMastered: TimebackUserHighestGradeMastered;
+    /**
+     * Hole-filling context for the current user.
+     * Call `holeFilling.fetch()` to learn why the student is in a
+     * hole-filling course and which standards to target.
+     */
+    holeFilling: TimebackUserHoleFilling;
+}
+/**
+ * Hole-filling context access for the current user.
+ * Results are cached for 5 minutes.
+ */
+interface TimebackUserHoleFilling {
+    /**
+     * Fetch the test result that sent the student into each of their
+     * hole-filling courses in this game, and the curriculum standards of the
+     * questions they missed (most-missed first).
+     *
+     * Returns `{ contexts: [] }` when the student has no hole-filling
+     * enrollment. Results are cached for 5 minutes (use `force: true` to
+     * bypass, e.g. after `user.refresh()` picks up a new enrollment).
+     *
+     * @param options - Cache options
+     * @returns Promise resolving to one context per hole-filling enrollment
+     *
+     * @example
+     * ```typescript
+     * const { contexts } = await client.timeback.user.holeFilling.fetch()
+     * const context = contexts.find(c => c.enrollment.subject === 'Math')
+     *
+     * if (context) {
+     *   const targetCodes = context.missedStandards.map(s => s.code) // ['K.OA.A.2', ...]
+     * }
+     * ```
+     */
+    fetch(options?: TTLCacheConfig): Promise<HoleFillingContextResponse>;
 }
 /**
  * Mastery data access for the current user.
@@ -4490,4 +4590,4 @@ interface PlatformTimebackUser extends PlatformTimebackUserContext {
 }
 
 export { PlaycademyClient };
-export type { AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemOutcome, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentReviewStandard, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, AssessmentTranscript, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DeploySource, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, EventListeners, ExternalGame, FetchedGame, FinalizeAssessmentInput, Game, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameReleaseResponse, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MasteryAssessmentSubmitResult, MasteryResponse, ParentGameContext, ParentGameHandle, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlatformTimebackUser, PlatformTimebackUserContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableChoiceInteraction, PlayableContentNode, PlayableGapMatchChoice, PlayableGapMatchInteraction, PlayableInlineChoiceInteraction, PlayableMatchChoice, PlayableMatchInteraction, PlayableOrderInteraction, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PopulateStudentResponse, RecordAssessmentProgressInput, Release, ReleasesResponse, ResumeAssessmentInput, SaveAssessmentInput, ScoreSubmission, SettledAssessmentAttemptSnapshot, SkillMasterySource, SkillStatus, SkillStatusLookupResult, SkillStatusRequest, SkillStatusRequestingGame, SkillStatusResponse, SkillStatusResult, SkillStatusUnsupportedReason, StandardsReviewSelectionContext, StartActivityOptions, StartActivityResult, StartAssessmentInput, StartAssessmentOptions, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, UserTimebackProfile, XpResponse };
+export type { AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemOutcome, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentReviewStandard, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, AssessmentTranscript, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DeploySource, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, EventListeners, ExternalGame, FetchedGame, FinalizeAssessmentInput, Game, GameContextPayload, GameCourseMetrics, GameCustomHostname, GameInitUser, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRow as GameRecord, GameReleaseResponse, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HoleFillingContext, HoleFillingContextResponse, HoleFillingMissedStandard, HoleFillingTriggeringResult, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, LoginResponse, ManifestV1, ManifestV2, ManifestVersions, MasteryAssessmentSubmitResult, MasteryResponse, ParentGameContext, ParentGameHandle, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlatformTimebackUser, PlatformTimebackUserContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableChoiceInteraction, PlayableContentNode, PlayableGapMatchChoice, PlayableGapMatchInteraction, PlayableInlineChoiceInteraction, PlayableMatchChoice, PlayableMatchInteraction, PlayableOrderInteraction, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, PopulateStudentResponse, RecordAssessmentProgressInput, Release, ReleasesResponse, ResumeAssessmentInput, SaveAssessmentInput, ScoreSubmission, SettledAssessmentAttemptSnapshot, SkillMasterySource, SkillStatus, SkillStatusLookupResult, SkillStatusRequest, SkillStatusRequestingGame, SkillStatusResponse, SkillStatusResult, SkillStatusUnsupportedReason, StandardsReviewSelectionContext, StartActivityOptions, StartActivityResult, StartAssessmentInput, StartAssessmentOptions, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserHoleFilling, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, UserTimebackProfile, XpResponse };

package/package.json

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