@timeback/sdk 0.1.8 → 0.1.10

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.
Files changed (159) hide show
  1. package/README.md +6 -6
  2. package/dist/chunk-3mqpr9vx.js +2 -0
  3. package/dist/chunk-92nnwa7t.js +2 -0
  4. package/dist/{chunk-ewsp6v3b.js → chunk-af3xwwsv.js} +5 -5
  5. package/dist/{chunk-07j8zre9.js → chunk-b8649tw4.js} +1 -1
  6. package/dist/{chunk-3886xy48.js → chunk-bd09q1fw.js} +6 -6
  7. package/dist/chunk-js665z11.js +1 -0
  8. package/dist/chunk-nsr7a2dv.js +2 -0
  9. package/dist/chunk-sgcwg4j6.js +1 -0
  10. package/dist/{chunk-9se82640.js → chunk-txwjkpfz.js} +1 -1
  11. package/dist/client/adapters/react/hooks/types.d.ts +34 -27
  12. package/dist/client/adapters/react/hooks/types.d.ts.map +1 -1
  13. package/dist/client/adapters/react/hooks/useTimebackVerification.d.ts +17 -5
  14. package/dist/client/adapters/react/hooks/useTimebackVerification.d.ts.map +1 -1
  15. package/dist/client/adapters/react/index.d.ts +1 -1
  16. package/dist/client/adapters/react/index.d.ts.map +1 -1
  17. package/dist/client/adapters/react/index.js +2 -2
  18. package/dist/client/adapters/react/provider.d.ts.map +1 -1
  19. package/dist/client/adapters/solid/primitives/createTimebackVerification.d.ts +3 -1
  20. package/dist/client/adapters/solid/primitives/createTimebackVerification.d.ts.map +1 -1
  21. package/dist/client/adapters/solid/primitives/createTimebackVerification.ts +55 -15
  22. package/dist/client/adapters/solid/types.d.ts +25 -29
  23. package/dist/client/adapters/solid/types.d.ts.map +1 -1
  24. package/dist/client/adapters/solid/types.ts +27 -18
  25. package/dist/client/adapters/svelte/stores/client.d.ts.map +1 -1
  26. package/dist/client/adapters/svelte/stores/client.ts +2 -9
  27. package/dist/client/adapters/svelte/stores/profile.d.ts +1 -1
  28. package/dist/client/adapters/svelte/stores/profile.d.ts.map +1 -1
  29. package/dist/client/adapters/svelte/stores/profile.ts +4 -11
  30. package/dist/client/adapters/svelte/stores/verification.d.ts +1 -1
  31. package/dist/client/adapters/svelte/stores/verification.d.ts.map +1 -1
  32. package/dist/client/adapters/svelte/stores/verification.ts +90 -17
  33. package/dist/client/adapters/svelte/types.d.ts +1 -29
  34. package/dist/client/adapters/svelte/types.d.ts.map +1 -1
  35. package/dist/client/adapters/vue/composables/useTimebackVerification.d.ts +3 -1
  36. package/dist/client/adapters/vue/composables/useTimebackVerification.d.ts.map +1 -1
  37. package/dist/client/adapters/vue/composables/useTimebackVerification.ts +59 -18
  38. package/dist/client/adapters/vue/provider.d.ts.map +1 -1
  39. package/dist/client/adapters/vue/provider.ts +4 -11
  40. package/dist/client/adapters/vue/types.d.ts +25 -29
  41. package/dist/client/adapters/vue/types.d.ts.map +1 -1
  42. package/dist/client/adapters/vue/types.ts +27 -18
  43. package/dist/client/auth/types.d.ts +1 -1
  44. package/dist/client/index.d.ts +1 -1
  45. package/dist/client/lib/activity/activity.class.d.ts +130 -22
  46. package/dist/client/lib/activity/activity.class.d.ts.map +1 -1
  47. package/dist/client/lib/activity/transport.d.ts +15 -0
  48. package/dist/client/lib/activity/transport.d.ts.map +1 -0
  49. package/dist/client/lib/activity/types.d.ts +53 -0
  50. package/dist/client/lib/activity/types.d.ts.map +1 -0
  51. package/dist/client/lib/utils.d.ts +33 -0
  52. package/dist/client/lib/utils.d.ts.map +1 -1
  53. package/dist/client/lib/utils.ts +109 -0
  54. package/dist/client/namespaces/activity.d.ts +45 -6
  55. package/dist/client/namespaces/activity.d.ts.map +1 -1
  56. package/dist/client/timeback-client.class.d.ts +7 -1
  57. package/dist/client/timeback-client.class.d.ts.map +1 -1
  58. package/dist/client.d.ts +1 -1
  59. package/dist/client.js +1 -1
  60. package/dist/edge.js +1 -1
  61. package/dist/identity.js +1 -1
  62. package/dist/index.d.ts +3 -3
  63. package/dist/index.d.ts.map +1 -1
  64. package/dist/index.js +22 -22
  65. package/dist/server/adapters/express.d.ts.map +1 -1
  66. package/dist/server/adapters/express.js +1 -1
  67. package/dist/server/adapters/native.d.ts.map +1 -1
  68. package/dist/server/adapters/native.js +1 -1
  69. package/dist/server/adapters/nextjs.js +1 -1
  70. package/dist/server/adapters/nuxt.d.ts.map +1 -1
  71. package/dist/server/adapters/nuxt.js +1 -1
  72. package/dist/server/adapters/solid-start.d.ts.map +1 -1
  73. package/dist/server/adapters/solid-start.js +1 -1
  74. package/dist/server/adapters/svelte-kit.d.ts.map +1 -1
  75. package/dist/server/adapters/svelte-kit.js +1 -1
  76. package/dist/server/adapters/tanstack-start.d.ts.map +1 -1
  77. package/dist/server/adapters/tanstack-start.js +1 -1
  78. package/dist/server/adapters/utils.d.ts +1 -1
  79. package/dist/server/adapters/utils.d.ts.map +1 -1
  80. package/dist/server/handlers/activity/caliper.d.ts +50 -14
  81. package/dist/server/handlers/activity/caliper.d.ts.map +1 -1
  82. package/dist/server/handlers/activity/heartbeat-handler.d.ts +15 -0
  83. package/dist/server/handlers/activity/heartbeat-handler.d.ts.map +1 -0
  84. package/dist/server/handlers/activity/index.d.ts +5 -3
  85. package/dist/server/handlers/activity/index.d.ts.map +1 -1
  86. package/dist/server/handlers/activity/progress.d.ts +2 -2
  87. package/dist/server/handlers/activity/progress.d.ts.map +1 -1
  88. package/dist/server/handlers/activity/schema.d.ts +40 -6
  89. package/dist/server/handlers/activity/schema.d.ts.map +1 -1
  90. package/dist/server/handlers/activity/submit-handler.d.ts +29 -0
  91. package/dist/server/handlers/activity/submit-handler.d.ts.map +1 -0
  92. package/dist/server/handlers/activity/submit.d.ts +44 -0
  93. package/dist/server/handlers/activity/submit.d.ts.map +1 -0
  94. package/dist/server/handlers/activity/types.d.ts +126 -5
  95. package/dist/server/handlers/activity/types.d.ts.map +1 -1
  96. package/dist/server/handlers/identity/handler.d.ts +23 -4
  97. package/dist/server/handlers/identity/handler.d.ts.map +1 -1
  98. package/dist/server/handlers/identity/index.d.ts +2 -2
  99. package/dist/server/handlers/identity/index.d.ts.map +1 -1
  100. package/dist/server/handlers/identity/oidc.d.ts.map +1 -1
  101. package/dist/server/handlers/identity/types.d.ts +0 -6
  102. package/dist/server/handlers/identity/types.d.ts.map +1 -1
  103. package/dist/server/handlers/index.d.ts +3 -3
  104. package/dist/server/handlers/index.d.ts.map +1 -1
  105. package/dist/server/handlers/user/handler.d.ts.map +1 -1
  106. package/dist/server/handlers/user/profile.d.ts.map +1 -1
  107. package/dist/server/handlers/user/types.d.ts +3 -0
  108. package/dist/server/handlers/user/types.d.ts.map +1 -1
  109. package/dist/server/handlers/user/verify.d.ts.map +1 -1
  110. package/dist/server/index.d.ts +1 -1
  111. package/dist/server/index.d.ts.map +1 -1
  112. package/dist/server/lib/hooks.d.ts +20 -0
  113. package/dist/server/lib/hooks.d.ts.map +1 -0
  114. package/dist/server/lib/index.d.ts +4 -2
  115. package/dist/server/lib/index.d.ts.map +1 -1
  116. package/dist/server/lib/logger.d.ts +36 -9
  117. package/dist/server/lib/logger.d.ts.map +1 -1
  118. package/dist/server/lib/resolve.d.ts +1 -1
  119. package/dist/server/lib/resolve.d.ts.map +1 -1
  120. package/dist/server/lib/utils.d.ts +19 -1
  121. package/dist/server/lib/utils.d.ts.map +1 -1
  122. package/dist/server/lib/validation.d.ts +55 -0
  123. package/dist/server/lib/validation.d.ts.map +1 -0
  124. package/dist/server/namespaces/activity/index.d.ts +8 -0
  125. package/dist/server/namespaces/activity/index.d.ts.map +1 -0
  126. package/dist/server/namespaces/activity/record.d.ts +49 -0
  127. package/dist/server/namespaces/activity/record.d.ts.map +1 -0
  128. package/dist/server/namespaces/activity/schema.d.ts +50 -0
  129. package/dist/server/namespaces/activity/schema.d.ts.map +1 -0
  130. package/dist/server/namespaces/user/get-profile.d.ts +32 -0
  131. package/dist/server/namespaces/user/get-profile.d.ts.map +1 -0
  132. package/dist/server/namespaces/user/index.d.ts +8 -0
  133. package/dist/server/namespaces/user/index.d.ts.map +1 -0
  134. package/dist/server/namespaces/user/verify.d.ts +28 -0
  135. package/dist/server/namespaces/user/verify.d.ts.map +1 -0
  136. package/dist/server/timeback.d.ts +3 -3
  137. package/dist/server/timeback.d.ts.map +1 -1
  138. package/dist/server/types.d.ts +394 -12
  139. package/dist/server/types.d.ts.map +1 -1
  140. package/dist/shared/constants.d.ts +20 -0
  141. package/dist/shared/constants.d.ts.map +1 -1
  142. package/dist/shared/constants.ts +51 -0
  143. package/dist/shared/index.d.ts +9 -0
  144. package/dist/shared/index.d.ts.map +1 -0
  145. package/dist/shared/schemas.d.ts +57 -0
  146. package/dist/shared/schemas.d.ts.map +1 -0
  147. package/dist/shared/types.d.ts +263 -10
  148. package/dist/shared/types.d.ts.map +1 -1
  149. package/dist/shared/types.ts +620 -0
  150. package/package.json +5 -5
  151. package/dist/chunk-ahy54f2r.js +0 -2
  152. package/dist/chunk-j1xdrfqj.js +0 -2
  153. package/dist/chunk-qaa129bd.js +0 -2
  154. package/dist/chunk-qr0bbnsr.js +0 -1
  155. package/dist/chunk-rgbpvxbv.js +0 -1
  156. package/dist/server/handlers/activity/handler.d.ts +0 -32
  157. package/dist/server/handlers/activity/handler.d.ts.map +0 -1
  158. package/dist/shared/xp-calculator.d.ts +0 -25
  159. package/dist/shared/xp-calculator.d.ts.map +0 -1
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Shared Zod Schemas
3
+ *
4
+ * Zod schemas for shared types used across client and server.
5
+ */
6
+ import * as z from 'zod';
7
+ /**
8
+ * Zod schema for grade-based course selector.
9
+ *
10
+ * @see {@link SubjectGradeCourseRef}
11
+ */
12
+ export declare const subjectGradeCourseRefSchema: z.ZodObject<{
13
+ subject: z.ZodEnum<{
14
+ FastMath: "FastMath";
15
+ Language: "Language";
16
+ Math: "Math";
17
+ None: "None";
18
+ Other: "Other";
19
+ Reading: "Reading";
20
+ Science: "Science";
21
+ "Social Studies": "Social Studies";
22
+ Vocabulary: "Vocabulary";
23
+ Writing: "Writing";
24
+ }>;
25
+ grade: z.ZodUnion<readonly [z.ZodLiteral<-1>, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>, z.ZodLiteral<7>, z.ZodLiteral<8>, z.ZodLiteral<9>, z.ZodLiteral<10>, z.ZodLiteral<11>, z.ZodLiteral<12>, z.ZodLiteral<13>]>;
26
+ }, z.core.$strip>;
27
+ /**
28
+ * Zod schema for code-based course selector.
29
+ *
30
+ * @see {@link CourseCodeRef}
31
+ */
32
+ export declare const courseCodeRefSchema: z.ZodObject<{
33
+ code: z.ZodString;
34
+ }, z.core.$strip>;
35
+ /**
36
+ * Zod schema for activity course reference (union of subject+grade or code).
37
+ *
38
+ * @see {@link ActivityCourseRef}
39
+ */
40
+ export declare const activityCourseRefSchema: z.ZodUnion<readonly [z.ZodObject<{
41
+ subject: z.ZodEnum<{
42
+ FastMath: "FastMath";
43
+ Language: "Language";
44
+ Math: "Math";
45
+ None: "None";
46
+ Other: "Other";
47
+ Reading: "Reading";
48
+ Science: "Science";
49
+ "Social Studies": "Social Studies";
50
+ Vocabulary: "Vocabulary";
51
+ Writing: "Writing";
52
+ }>;
53
+ grade: z.ZodUnion<readonly [z.ZodLiteral<-1>, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>, z.ZodLiteral<7>, z.ZodLiteral<8>, z.ZodLiteral<9>, z.ZodLiteral<10>, z.ZodLiteral<11>, z.ZodLiteral<12>, z.ZodLiteral<13>]>;
54
+ }, z.core.$strip>, z.ZodObject<{
55
+ code: z.ZodString;
56
+ }, z.core.$strip>]>;
57
+ //# sourceMappingURL=schemas.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/shared/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAWxB;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;iBAGtC,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;mBAA8D,CAAA"}
@@ -142,6 +142,70 @@ export type ActivityCourseRef = SubjectGradeCourseRef | CourseCodeRef;
142
142
  * @returns True if grade-based selector
143
143
  */
144
144
  export declare function isSubjectGradeCourseRef(ref: ActivityCourseRef): ref is SubjectGradeCourseRef;
145
+ /**
146
+ * Time tracking configuration options.
147
+ *
148
+ * Controls how the SDK tracks and reports time-spent data via heartbeats.
149
+ */
150
+ export interface TimeTrackingOptions {
151
+ /**
152
+ * Interval in milliseconds between automatic heartbeat flushes.
153
+ * @default 15000 (15 seconds)
154
+ */
155
+ flushIntervalMs?: number;
156
+ /**
157
+ * Whether to pause time tracking when the tab is not visible.
158
+ * @default true
159
+ */
160
+ visibilityAware?: boolean;
161
+ /**
162
+ * Whether to flush accumulated time when the tab becomes hidden.
163
+ * @default true
164
+ */
165
+ flushOnVisibilityHidden?: boolean;
166
+ /**
167
+ * Whether to attempt a best-effort flush on page unload (pagehide event).
168
+ *
169
+ * Implementation notes:
170
+ * - Prefer `navigator.sendBeacon()` when available and safe to use
171
+ * - Fall back to `fetch(..., { keepalive: true })` otherwise
172
+ *
173
+ * sendBeacon cannot set arbitrary headers (e.g. Authorization), so
174
+ * integrations that rely on bearer tokens typically use the keepalive
175
+ * fetch fallback.
176
+ * @default true
177
+ */
178
+ flushOnPageHide?: boolean;
179
+ /**
180
+ * Timeout in milliseconds after which hidden time stops being tracked.
181
+ *
182
+ * When the tab is hidden for longer than this duration, heartbeats stop
183
+ * and the hidden time is not counted. When the user returns, tracking
184
+ * resumes fresh without counting the extended absence.
185
+ *
186
+ * Set to `null` or `Infinity` to disable (always track hidden time).
187
+ * @default 600000 (10 minutes)
188
+ */
189
+ hiddenTimeoutMs?: number | null;
190
+ /**
191
+ * Number of retry attempts for failed heartbeat sends.
192
+ *
193
+ * Set to `0` (default) for no retries. Retries use exponential backoff
194
+ * with delays configured by `retryDelaysMs`.
195
+ *
196
+ * @default 0
197
+ */
198
+ retryAttempts?: number;
199
+ /**
200
+ * Delay schedule (in milliseconds) between retry attempts.
201
+ *
202
+ * Each index corresponds to the delay before that retry attempt.
203
+ * If more attempts are made than there are entries, the last value is reused.
204
+ *
205
+ * @default [100, 300, 1000]
206
+ */
207
+ retryDelaysMs?: number[];
208
+ }
145
209
  /**
146
210
  * Activity start parameters.
147
211
  *
@@ -197,6 +261,63 @@ export interface ActivityParams {
197
261
  name: string;
198
262
  /** Course selector (must match a unique course in timeback.config.json) */
199
263
  course: ActivityCourseRef;
264
+ /**
265
+ * Optional run identifier for correlating events across sessions.
266
+ *
267
+ * When resuming an activity, provide the same `runId` from the previous session
268
+ * to correlate time-spent events with the eventual completion event.
269
+ *
270
+ * If not provided, the SDK generates a new UUID.
271
+ */
272
+ runId?: string;
273
+ /**
274
+ * Time tracking configuration options.
275
+ *
276
+ * Heartbeats are enabled by default. Use this to customize flush intervals
277
+ * or disable visibility-aware tracking.
278
+ *
279
+ * Set to `false` to disable client-side time tracking entirely. When
280
+ * disabled, no heartbeats are sent, no visibility handlers are registered,
281
+ * and `end()` skips the final time flush. Use this when time is managed
282
+ * server-side (e.g. via `timeback.activity.record()`).
283
+ */
284
+ time?: TimeTrackingOptions | false;
285
+ /**
286
+ * Called when a heartbeat or submission fails.
287
+ *
288
+ * Heartbeat errors are non-fatal — the SDK continues tracking time
289
+ * regardless. Submit errors (from `end()`) are also surfaced here
290
+ * before being re-thrown.
291
+ *
292
+ * @param error - The error that occurred
293
+ * @param context - Details about the failed operation
294
+ */
295
+ onError?: (error: Error, context: ActivityErrorContext) => void;
296
+ /**
297
+ * Called when the activity is paused (via `pause()` or visibility timeout).
298
+ */
299
+ onPause?: () => void;
300
+ /**
301
+ * Called when the activity resumes after being paused.
302
+ */
303
+ onResume?: () => void;
304
+ /**
305
+ * Called after each successful heartbeat flush.
306
+ *
307
+ * @param elapsedMs - Active milliseconds reported in this flush
308
+ */
309
+ onFlush?: (elapsedMs: number) => void;
310
+ }
311
+ /**
312
+ * Context passed to the `onError` callback.
313
+ */
314
+ export interface ActivityErrorContext {
315
+ /** Which operation failed — aligns with Caliper event types. */
316
+ type: 'timeSpent' | 'completion';
317
+ /** The activity slug passed to `activity.start()`. */
318
+ activityId: string;
319
+ /** The `runId` for this activity instance. */
320
+ runId: string;
200
321
  }
201
322
  /**
202
323
  * Activity metrics (optional performance data).
@@ -212,11 +333,12 @@ export interface ActivityMetrics {
212
333
  masteredUnits?: number;
213
334
  }
214
335
  /**
215
- * Data passed to `Activity.end()` when completing an activity.
336
+ * Question count metrics for activity completion.
216
337
  *
217
338
  * @example Basic usage
218
339
  * ```typescript
219
340
  * await activity.end({
341
+ * xpEarned: 100,
220
342
  * totalQuestions: 10,
221
343
  * correctQuestions: 8,
222
344
  * })
@@ -225,6 +347,7 @@ export interface ActivityMetrics {
225
347
  * @example With time override
226
348
  * ```typescript
227
349
  * await activity.end({
350
+ * xpEarned: 100,
228
351
  * totalQuestions: 10,
229
352
  * correctQuestions: 8,
230
353
  * time: { active: 42000, inactive: 3000 },
@@ -250,9 +373,31 @@ type QuestionCountMetrics = {
250
373
  /** Omit question counts entirely. */
251
374
  correctQuestions?: undefined;
252
375
  };
253
- export type ActivityEndData = QuestionCountMetrics & {
254
- /** XP earned from this activity */
255
- xpEarned?: number;
376
+ /** Optional time override for activity.end() */
377
+ interface ActivityEndTimeOverride {
378
+ /** Active time in milliseconds */
379
+ active: number;
380
+ /** Inactive/paused time in milliseconds (defaults to 0) */
381
+ inactive?: number;
382
+ }
383
+ /**
384
+ * Time-only end: final flush without completion event.
385
+ *
386
+ * Call `activity.end()` with no args or just a time override to flush
387
+ * accumulated time without sending an ActivityCompletedEvent.
388
+ */
389
+ type ActivityEndTimeOnly = {
390
+ totalQuestions?: undefined;
391
+ correctQuestions?: undefined;
392
+ xpEarned?: undefined;
393
+ masteredUnits?: undefined;
394
+ pctComplete?: undefined;
395
+ time?: ActivityEndTimeOverride;
396
+ };
397
+ /** Completion end: flush + ActivityCompletedEvent. */
398
+ type ActivityEndCompletion = QuestionCountMetrics & {
399
+ /** XP earned from this activity. */
400
+ xpEarned: number;
256
401
  /** Number of units mastered */
257
402
  masteredUnits?: number;
258
403
  /**
@@ -263,13 +408,17 @@ export type ActivityEndData = QuestionCountMetrics & {
263
408
  * Optional time override. When provided, the SDK uses these values instead
264
409
  * of the internal timer. Values are clamped to >= 0 and rounded to integers.
265
410
  */
266
- time?: {
267
- /** Active time in milliseconds */
268
- active: number;
269
- /** Inactive/paused time in milliseconds (defaults to 0) */
270
- inactive?: number;
271
- };
411
+ time?: ActivityEndTimeOverride;
272
412
  };
413
+ /**
414
+ * Data for ending an activity.
415
+ *
416
+ * Two modes:
417
+ * - **Time-only**: `activity.end()` or `activity.end({ time: {...} })` — final
418
+ * flush only, no completion event
419
+ * - **Completion**: `activity.end({ xpEarned, ... })` — final flush + completion event
420
+ */
421
+ export type ActivityEndData = ActivityEndTimeOnly | ActivityEndCompletion;
273
422
  /**
274
423
  * Activity state sent to the server when ending.
275
424
  *
@@ -311,6 +460,76 @@ export interface ActivityEndPayload {
311
460
  */
312
461
  pctComplete?: number;
313
462
  }
463
+ /**
464
+ * Activity heartbeat payload for time-spent tracking.
465
+ *
466
+ * Sent periodically to report accumulated active time for a time window.
467
+ * The server builds a `TimeSpentEvent` from this data.
468
+ */
469
+ export interface ActivityHeartbeatPayload {
470
+ /**
471
+ * Activity slug (stable identifier for the learning object).
472
+ */
473
+ id: string;
474
+ /**
475
+ * Human-readable display name of the activity.
476
+ */
477
+ name: string;
478
+ /** Course selector (must match a unique course in timeback.config.json) */
479
+ course: ActivityCourseRef;
480
+ /**
481
+ * Run identifier for correlating heartbeats with the completion event.
482
+ */
483
+ runId: string;
484
+ /**
485
+ * ISO 8601 timestamp when this time window started.
486
+ */
487
+ startedAt: string;
488
+ /**
489
+ * ISO 8601 timestamp when this time window ended.
490
+ */
491
+ endedAt: string;
492
+ /**
493
+ * Active time in this window in milliseconds.
494
+ */
495
+ elapsedMs: number;
496
+ /**
497
+ * Paused time in this window in milliseconds.
498
+ */
499
+ pausedMs: number;
500
+ }
501
+ /**
502
+ * Activity submit payload for completion events.
503
+ *
504
+ * Sent when the activity completes with metrics.
505
+ * The server builds an `ActivityCompletedEvent` from this data.
506
+ */
507
+ export interface ActivitySubmitPayload {
508
+ /**
509
+ * Activity slug (stable identifier for the learning object).
510
+ */
511
+ id: string;
512
+ /**
513
+ * Human-readable display name of the activity.
514
+ */
515
+ name: string;
516
+ /** Course selector (must match a unique course in timeback.config.json) */
517
+ course: ActivityCourseRef;
518
+ /**
519
+ * Run identifier for correlating with previous heartbeats.
520
+ */
521
+ runId: string;
522
+ /**
523
+ * ISO 8601 timestamp when the activity ended.
524
+ */
525
+ endedAt: string;
526
+ /** Activity metrics */
527
+ metrics: ActivityMetrics;
528
+ /**
529
+ * App-reported course progress (per enrollment), as a percentage from 0–100.
530
+ */
531
+ pctComplete?: number;
532
+ }
314
533
  /**
315
534
  * Activity submission response.
316
535
  */
@@ -333,5 +552,39 @@ export type TimebackVerifyResult = {
333
552
  /** User does not exist in Timeback */
334
553
  verified: false;
335
554
  };
555
+ /**
556
+ * Verification state for the current user.
557
+ *
558
+ * Used by framework adapters (React, Vue, Svelte, Solid) to expose
559
+ * verification status as a state machine for UI consumption.
560
+ */
561
+ export type TimebackVerificationState = {
562
+ status: 'loading';
563
+ } | {
564
+ status: 'verified';
565
+ timebackId: string;
566
+ } | {
567
+ status: 'unverified';
568
+ } | {
569
+ status: 'error';
570
+ message: string;
571
+ };
572
+ /**
573
+ * Profile state for the current user.
574
+ *
575
+ * Used by framework adapters (React, Vue, Svelte, Solid) to expose
576
+ * profile fetching status as a state machine for UI consumption.
577
+ */
578
+ export type TimebackProfileState = {
579
+ status: 'idle';
580
+ } | {
581
+ status: 'loading';
582
+ } | {
583
+ status: 'loaded';
584
+ profile: TimebackProfile;
585
+ } | {
586
+ status: 'error';
587
+ message: string;
588
+ };
336
589
  export {};
337
590
  //# sourceMappingURL=types.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,yBAAyB;IACzB,MAAM,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;KACZ,CAAA;IAED,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,4BAA4B;IAC5B,EAAE,CAAC,EAAE;QACJ,sCAAsC;QACtC,KAAK,EAAE,MAAM,CAAA;QACb,0DAA0D;QAC1D,GAAG,EAAE,MAAM,CAAA;KACX,CAAA;IAED,uBAAuB;IACvB,OAAO,CAAC,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACZ,CAAC,CAAA;IAEF,yBAAyB;IACzB,KAAK,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAC3B,CAAA;CACD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACrC,eAAe,EACf,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAC5C,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACxD,8CAA8C;IAC9C,MAAM,EAAE,cAAc,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,eAAe,CAAA;IACxB,KAAK,EAAE,aAAa,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,aAAa,CAAA;AAErE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,iBAAiB,GAAG,GAAG,IAAI,qBAAqB,CAE5F;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;OAUG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAA;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;IAElC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAE/D;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,kEAAgE;IAChE,IAAI,EAAE,WAAW,GAAG,YAAY,CAAA;IAChC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,KAAK,oBAAoB,GACtB;IACA;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAA;CACvB,GACD;IACA,qCAAqC;IACrC,cAAc,CAAC,EAAE,SAAS,CAAA;IAC1B,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,SAAS,CAAA;CAC3B,CAAA;AAEJ,gDAAgD;AAChD,UAAU,uBAAuB;IAChC,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG;IAC1B,cAAc,CAAC,EAAE,SAAS,CAAA;IAC1B,gBAAgB,CAAC,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,IAAI,CAAC,EAAE,uBAAuB,CAAA;CAC9B,CAAA;AAED,sDAAsD;AACtD,KAAK,qBAAqB,GAAG,oBAAoB,GAAG;IACnD,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,uBAAuB,CAAA;CAC9B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,qBAAqB,CAAA;AAEzE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAA;IACzB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAA;IAChB,uBAAuB;IACvB,OAAO,EAAE,eAAe,CAAA;IACxB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAA;IACzB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACrC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAA;IACzB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,uBAAuB;IACvB,OAAO,EAAE,eAAe,CAAA;IACxB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IACA,8BAA8B;IAC9B,QAAQ,EAAE,IAAI,CAAA;IACd,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAA;CACjB,GACD;IACA,sCAAsC;IACtC,QAAQ,EAAE,KAAK,CAAA;CACd,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAClC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA"}