@lessonkit/core 1.2.0 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +254 -58
- package/dist/index.d.cts +38 -10
- package/dist/index.d.ts +38 -10
- package/dist/index.js +251 -58
- package/package.json +1 -1
- package/telemetry-catalog.v3.json +8 -0
package/dist/index.d.cts
CHANGED
|
@@ -92,7 +92,7 @@ type AssessmentBaseProps = AssessmentBehaviour & {
|
|
|
92
92
|
passingScore?: number;
|
|
93
93
|
};
|
|
94
94
|
|
|
95
|
-
type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
|
|
95
|
+
type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
|
|
96
96
|
type TelemetryUser = {
|
|
97
97
|
id?: string;
|
|
98
98
|
email?: string;
|
|
@@ -150,6 +150,11 @@ type BookPageViewedData = {
|
|
|
150
150
|
pageIndex: number;
|
|
151
151
|
pageTitle?: string;
|
|
152
152
|
};
|
|
153
|
+
type SlideViewedData = {
|
|
154
|
+
blockId: BlockId;
|
|
155
|
+
slideIndex: number;
|
|
156
|
+
slideTitle?: string;
|
|
157
|
+
};
|
|
153
158
|
type CompoundPageViewedData = {
|
|
154
159
|
blockId: BlockId;
|
|
155
160
|
pageIndex: number;
|
|
@@ -217,6 +222,10 @@ type TelemetryEvent = (TelemetryEventBase & {
|
|
|
217
222
|
name: "book_page_viewed";
|
|
218
223
|
lessonId: LessonId;
|
|
219
224
|
data: BookPageViewedData;
|
|
225
|
+
}) | (TelemetryEventBase & {
|
|
226
|
+
name: "slide_viewed";
|
|
227
|
+
lessonId: LessonId;
|
|
228
|
+
data: SlideViewedData;
|
|
220
229
|
}) | (TelemetryEventBase & {
|
|
221
230
|
name: "compound_page_viewed";
|
|
222
231
|
lessonId: LessonId;
|
|
@@ -248,7 +257,10 @@ type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
|
|
|
248
257
|
type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
|
|
249
258
|
type TrackingClient = {
|
|
250
259
|
track: (event: TelemetryEvent) => void;
|
|
251
|
-
|
|
260
|
+
/** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
|
|
261
|
+
flush?: () => void | Promise<boolean>;
|
|
262
|
+
/** Best-effort synchronous flush for pagehide (keepalive batch sink when configured). */
|
|
263
|
+
flushOnExit?: () => void;
|
|
252
264
|
dispose?: () => void | Promise<void>;
|
|
253
265
|
};
|
|
254
266
|
|
|
@@ -289,7 +301,8 @@ type CompoundBaseProps = {
|
|
|
289
301
|
|
|
290
302
|
type StoragePort = {
|
|
291
303
|
getItem: (key: string) => string | null;
|
|
292
|
-
|
|
304
|
+
/** Returns false when the value could not be durably persisted (e.g. sessionStorage quota). */
|
|
305
|
+
setItem: (key: string, value: string) => boolean;
|
|
293
306
|
removeItem?: (key: string) => void;
|
|
294
307
|
/** @internal Test helper to clear in-memory fallback state. */
|
|
295
308
|
resetForTests?: () => void;
|
|
@@ -310,14 +323,17 @@ declare function createGlobalTimer(): TimerPort;
|
|
|
310
323
|
|
|
311
324
|
declare function compoundStateStorageKey(courseId: CourseId, compoundId: BlockId): string;
|
|
312
325
|
declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): CompoundResumeState | null;
|
|
313
|
-
declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState):
|
|
326
|
+
declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): boolean;
|
|
314
327
|
declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
|
|
315
328
|
|
|
316
329
|
/** Canonical compound child allowlists (H5P sub-content curation). */
|
|
317
330
|
declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "ProgressTracker"];
|
|
318
331
|
declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
|
|
332
|
+
/** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
|
|
333
|
+
declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider"];
|
|
334
|
+
declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
|
|
319
335
|
declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots"];
|
|
320
|
-
type CompoundParentType = "Page" | "InteractiveBook" | "AssessmentSequence";
|
|
336
|
+
type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "AssessmentSequence";
|
|
321
337
|
declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
|
|
322
338
|
declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
|
|
323
339
|
declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
|
|
@@ -349,7 +365,7 @@ declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
|
|
|
349
365
|
declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
|
|
350
366
|
|
|
351
367
|
declare const telemetryCatalogV3Version: 3;
|
|
352
|
-
type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
|
|
368
|
+
type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
|
|
353
369
|
type TelemetryCatalogV3Entry = {
|
|
354
370
|
name: TelemetryCatalogV3EventName;
|
|
355
371
|
description: string;
|
|
@@ -369,6 +385,10 @@ declare function createTrackingClient(opts?: {
|
|
|
369
385
|
maxBatchSize?: number;
|
|
370
386
|
};
|
|
371
387
|
batchSink?: TelemetryBatchSink;
|
|
388
|
+
/** Called when an event is dropped because the batch buffer is at cap (including in production). */
|
|
389
|
+
onBufferDrop?: () => void;
|
|
390
|
+
/** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
|
|
391
|
+
exitBatchSink?: TelemetryBatchSink;
|
|
372
392
|
}): TrackingClient;
|
|
373
393
|
|
|
374
394
|
declare function createSessionId(): string;
|
|
@@ -426,6 +446,10 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
|
|
|
426
446
|
name: "book_page_viewed";
|
|
427
447
|
lessonId?: LessonId;
|
|
428
448
|
data: BookPageViewedData;
|
|
449
|
+
}) | (BuildTelemetryEventContext & {
|
|
450
|
+
name: "slide_viewed";
|
|
451
|
+
lessonId?: LessonId;
|
|
452
|
+
data: SlideViewedData;
|
|
429
453
|
}) | (BuildTelemetryEventContext & {
|
|
430
454
|
name: "compound_page_viewed";
|
|
431
455
|
lessonId?: LessonId;
|
|
@@ -501,11 +525,13 @@ declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
|
|
|
501
525
|
declare function getTabSessionId(storage: StoragePort): string | null;
|
|
502
526
|
declare function resolveSessionId(storage: StoragePort, provided?: string): string;
|
|
503
527
|
declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
504
|
-
declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId):
|
|
528
|
+
declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
505
529
|
declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
506
|
-
declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId):
|
|
530
|
+
declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
507
531
|
declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
508
|
-
declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId):
|
|
532
|
+
declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
533
|
+
/** @internal Reset shared volatile session id between tests. */
|
|
534
|
+
declare function resetSharedVolatileSessionIdForTests(): void;
|
|
509
535
|
declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
|
|
510
536
|
|
|
511
537
|
/** Plugin category — aligns with roadmap extension areas. */
|
|
@@ -623,6 +649,8 @@ type HeadlessLessonkitConfig = {
|
|
|
623
649
|
};
|
|
624
650
|
/** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
|
|
625
651
|
plugins?: HeadlessLessonkitPlugins;
|
|
652
|
+
/** When true, skip initial {@link PluginHost.setupAll}; host caller runs setup (React v2 provider). */
|
|
653
|
+
deferPluginSetup?: boolean;
|
|
626
654
|
};
|
|
627
655
|
type HeadlessRuntimePorts = {
|
|
628
656
|
storage?: StoragePort;
|
|
@@ -668,4 +696,4 @@ declare function buildPluginContext(opts: {
|
|
|
668
696
|
user?: TelemetryUser;
|
|
669
697
|
}): LessonkitPluginContext;
|
|
670
698
|
|
|
671
|
-
export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
|
|
699
|
+
export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, type SlideViewedData, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetSharedVolatileSessionIdForTests, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
|
package/dist/index.d.ts
CHANGED
|
@@ -92,7 +92,7 @@ type AssessmentBaseProps = AssessmentBehaviour & {
|
|
|
92
92
|
passingScore?: number;
|
|
93
93
|
};
|
|
94
94
|
|
|
95
|
-
type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
|
|
95
|
+
type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
|
|
96
96
|
type TelemetryUser = {
|
|
97
97
|
id?: string;
|
|
98
98
|
email?: string;
|
|
@@ -150,6 +150,11 @@ type BookPageViewedData = {
|
|
|
150
150
|
pageIndex: number;
|
|
151
151
|
pageTitle?: string;
|
|
152
152
|
};
|
|
153
|
+
type SlideViewedData = {
|
|
154
|
+
blockId: BlockId;
|
|
155
|
+
slideIndex: number;
|
|
156
|
+
slideTitle?: string;
|
|
157
|
+
};
|
|
153
158
|
type CompoundPageViewedData = {
|
|
154
159
|
blockId: BlockId;
|
|
155
160
|
pageIndex: number;
|
|
@@ -217,6 +222,10 @@ type TelemetryEvent = (TelemetryEventBase & {
|
|
|
217
222
|
name: "book_page_viewed";
|
|
218
223
|
lessonId: LessonId;
|
|
219
224
|
data: BookPageViewedData;
|
|
225
|
+
}) | (TelemetryEventBase & {
|
|
226
|
+
name: "slide_viewed";
|
|
227
|
+
lessonId: LessonId;
|
|
228
|
+
data: SlideViewedData;
|
|
220
229
|
}) | (TelemetryEventBase & {
|
|
221
230
|
name: "compound_page_viewed";
|
|
222
231
|
lessonId: LessonId;
|
|
@@ -248,7 +257,10 @@ type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
|
|
|
248
257
|
type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
|
|
249
258
|
type TrackingClient = {
|
|
250
259
|
track: (event: TelemetryEvent) => void;
|
|
251
|
-
|
|
260
|
+
/** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
|
|
261
|
+
flush?: () => void | Promise<boolean>;
|
|
262
|
+
/** Best-effort synchronous flush for pagehide (keepalive batch sink when configured). */
|
|
263
|
+
flushOnExit?: () => void;
|
|
252
264
|
dispose?: () => void | Promise<void>;
|
|
253
265
|
};
|
|
254
266
|
|
|
@@ -289,7 +301,8 @@ type CompoundBaseProps = {
|
|
|
289
301
|
|
|
290
302
|
type StoragePort = {
|
|
291
303
|
getItem: (key: string) => string | null;
|
|
292
|
-
|
|
304
|
+
/** Returns false when the value could not be durably persisted (e.g. sessionStorage quota). */
|
|
305
|
+
setItem: (key: string, value: string) => boolean;
|
|
293
306
|
removeItem?: (key: string) => void;
|
|
294
307
|
/** @internal Test helper to clear in-memory fallback state. */
|
|
295
308
|
resetForTests?: () => void;
|
|
@@ -310,14 +323,17 @@ declare function createGlobalTimer(): TimerPort;
|
|
|
310
323
|
|
|
311
324
|
declare function compoundStateStorageKey(courseId: CourseId, compoundId: BlockId): string;
|
|
312
325
|
declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): CompoundResumeState | null;
|
|
313
|
-
declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState):
|
|
326
|
+
declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): boolean;
|
|
314
327
|
declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
|
|
315
328
|
|
|
316
329
|
/** Canonical compound child allowlists (H5P sub-content curation). */
|
|
317
330
|
declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "ProgressTracker"];
|
|
318
331
|
declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
|
|
332
|
+
/** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
|
|
333
|
+
declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider"];
|
|
334
|
+
declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
|
|
319
335
|
declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots"];
|
|
320
|
-
type CompoundParentType = "Page" | "InteractiveBook" | "AssessmentSequence";
|
|
336
|
+
type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "AssessmentSequence";
|
|
321
337
|
declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
|
|
322
338
|
declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
|
|
323
339
|
declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
|
|
@@ -349,7 +365,7 @@ declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
|
|
|
349
365
|
declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
|
|
350
366
|
|
|
351
367
|
declare const telemetryCatalogV3Version: 3;
|
|
352
|
-
type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
|
|
368
|
+
type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
|
|
353
369
|
type TelemetryCatalogV3Entry = {
|
|
354
370
|
name: TelemetryCatalogV3EventName;
|
|
355
371
|
description: string;
|
|
@@ -369,6 +385,10 @@ declare function createTrackingClient(opts?: {
|
|
|
369
385
|
maxBatchSize?: number;
|
|
370
386
|
};
|
|
371
387
|
batchSink?: TelemetryBatchSink;
|
|
388
|
+
/** Called when an event is dropped because the batch buffer is at cap (including in production). */
|
|
389
|
+
onBufferDrop?: () => void;
|
|
390
|
+
/** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
|
|
391
|
+
exitBatchSink?: TelemetryBatchSink;
|
|
372
392
|
}): TrackingClient;
|
|
373
393
|
|
|
374
394
|
declare function createSessionId(): string;
|
|
@@ -426,6 +446,10 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
|
|
|
426
446
|
name: "book_page_viewed";
|
|
427
447
|
lessonId?: LessonId;
|
|
428
448
|
data: BookPageViewedData;
|
|
449
|
+
}) | (BuildTelemetryEventContext & {
|
|
450
|
+
name: "slide_viewed";
|
|
451
|
+
lessonId?: LessonId;
|
|
452
|
+
data: SlideViewedData;
|
|
429
453
|
}) | (BuildTelemetryEventContext & {
|
|
430
454
|
name: "compound_page_viewed";
|
|
431
455
|
lessonId?: LessonId;
|
|
@@ -501,11 +525,13 @@ declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
|
|
|
501
525
|
declare function getTabSessionId(storage: StoragePort): string | null;
|
|
502
526
|
declare function resolveSessionId(storage: StoragePort, provided?: string): string;
|
|
503
527
|
declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
504
|
-
declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId):
|
|
528
|
+
declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
505
529
|
declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
506
|
-
declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId):
|
|
530
|
+
declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
507
531
|
declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
508
|
-
declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId):
|
|
532
|
+
declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
|
|
533
|
+
/** @internal Reset shared volatile session id between tests. */
|
|
534
|
+
declare function resetSharedVolatileSessionIdForTests(): void;
|
|
509
535
|
declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
|
|
510
536
|
|
|
511
537
|
/** Plugin category — aligns with roadmap extension areas. */
|
|
@@ -623,6 +649,8 @@ type HeadlessLessonkitConfig = {
|
|
|
623
649
|
};
|
|
624
650
|
/** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
|
|
625
651
|
plugins?: HeadlessLessonkitPlugins;
|
|
652
|
+
/** When true, skip initial {@link PluginHost.setupAll}; host caller runs setup (React v2 provider). */
|
|
653
|
+
deferPluginSetup?: boolean;
|
|
626
654
|
};
|
|
627
655
|
type HeadlessRuntimePorts = {
|
|
628
656
|
storage?: StoragePort;
|
|
@@ -668,4 +696,4 @@ declare function buildPluginContext(opts: {
|
|
|
668
696
|
user?: TelemetryUser;
|
|
669
697
|
}): LessonkitPluginContext;
|
|
670
698
|
|
|
671
|
-
export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
|
|
699
|
+
export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, type SlideViewedData, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetSharedVolatileSessionIdForTests, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
|