@contractspec/module.learning-journey 1.57.0 → 1.58.0

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 (140) hide show
  1. package/dist/browser/contracts/index.js +578 -0
  2. package/dist/browser/contracts/models.js +193 -0
  3. package/dist/browser/contracts/onboarding.js +417 -0
  4. package/dist/browser/contracts/operations.js +326 -0
  5. package/dist/browser/contracts/shared.js +5 -0
  6. package/dist/browser/docs/index.js +124 -0
  7. package/dist/browser/docs/learning-journey.docblock.js +124 -0
  8. package/dist/browser/engines/index.js +526 -0
  9. package/dist/browser/engines/srs.js +198 -0
  10. package/dist/browser/engines/streak.js +159 -0
  11. package/dist/browser/engines/xp.js +171 -0
  12. package/dist/browser/entities/ai.js +343 -0
  13. package/dist/browser/entities/course.js +276 -0
  14. package/dist/browser/entities/flashcard.js +222 -0
  15. package/dist/browser/entities/gamification.js +340 -0
  16. package/dist/browser/entities/index.js +2136 -0
  17. package/dist/browser/entities/learner.js +329 -0
  18. package/dist/browser/entities/onboarding.js +301 -0
  19. package/dist/browser/entities/quiz.js +304 -0
  20. package/dist/browser/events.js +423 -0
  21. package/dist/browser/index.js +3833 -0
  22. package/dist/browser/learning-journey.capability.js +40 -0
  23. package/dist/browser/learning-journey.feature.js +56 -0
  24. package/dist/browser/track-spec.js +0 -0
  25. package/dist/contracts/index.d.ts +5 -5
  26. package/dist/contracts/index.d.ts.map +1 -0
  27. package/dist/contracts/index.js +578 -5
  28. package/dist/contracts/models.d.ts +426 -431
  29. package/dist/contracts/models.d.ts.map +1 -1
  30. package/dist/contracts/models.js +178 -372
  31. package/dist/contracts/onboarding.d.ts +621 -627
  32. package/dist/contracts/onboarding.d.ts.map +1 -1
  33. package/dist/contracts/onboarding.js +404 -388
  34. package/dist/contracts/operations.d.ts +243 -249
  35. package/dist/contracts/operations.d.ts.map +1 -1
  36. package/dist/contracts/operations.js +324 -148
  37. package/dist/contracts/shared.d.ts +1 -4
  38. package/dist/contracts/shared.d.ts.map +1 -1
  39. package/dist/contracts/shared.js +6 -6
  40. package/dist/docs/index.d.ts +2 -1
  41. package/dist/docs/index.d.ts.map +1 -0
  42. package/dist/docs/index.js +125 -1
  43. package/dist/docs/learning-journey.docblock.d.ts +2 -1
  44. package/dist/docs/learning-journey.docblock.d.ts.map +1 -0
  45. package/dist/docs/learning-journey.docblock.js +47 -58
  46. package/dist/engines/index.d.ts +4 -4
  47. package/dist/engines/index.d.ts.map +1 -0
  48. package/dist/engines/index.js +526 -4
  49. package/dist/engines/srs.d.ts +89 -92
  50. package/dist/engines/srs.d.ts.map +1 -1
  51. package/dist/engines/srs.js +197 -217
  52. package/dist/engines/streak.d.ts +84 -87
  53. package/dist/engines/streak.d.ts.map +1 -1
  54. package/dist/engines/streak.js +158 -192
  55. package/dist/engines/xp.d.ts +80 -83
  56. package/dist/engines/xp.d.ts.map +1 -1
  57. package/dist/engines/xp.js +170 -211
  58. package/dist/entities/ai.d.ts +199 -204
  59. package/dist/entities/ai.d.ts.map +1 -1
  60. package/dist/entities/ai.js +336 -368
  61. package/dist/entities/course.d.ts +149 -154
  62. package/dist/entities/course.d.ts.map +1 -1
  63. package/dist/entities/course.js +267 -306
  64. package/dist/entities/flashcard.d.ts +144 -149
  65. package/dist/entities/flashcard.d.ts.map +1 -1
  66. package/dist/entities/flashcard.js +217 -243
  67. package/dist/entities/gamification.d.ts +197 -202
  68. package/dist/entities/gamification.d.ts.map +1 -1
  69. package/dist/entities/gamification.js +331 -382
  70. package/dist/entities/index.d.ts +613 -618
  71. package/dist/entities/index.d.ts.map +1 -1
  72. package/dist/entities/index.js +2135 -43
  73. package/dist/entities/learner.d.ts +191 -196
  74. package/dist/entities/learner.d.ts.map +1 -1
  75. package/dist/entities/learner.js +322 -357
  76. package/dist/entities/onboarding.d.ts +164 -169
  77. package/dist/entities/onboarding.d.ts.map +1 -1
  78. package/dist/entities/onboarding.js +296 -301
  79. package/dist/entities/quiz.d.ts +184 -189
  80. package/dist/entities/quiz.d.ts.map +1 -1
  81. package/dist/entities/quiz.js +296 -361
  82. package/dist/events.d.ts +608 -614
  83. package/dist/events.d.ts.map +1 -1
  84. package/dist/events.js +421 -687
  85. package/dist/index.d.ts +8 -20
  86. package/dist/index.d.ts.map +1 -0
  87. package/dist/index.js +3834 -22
  88. package/dist/learning-journey.capability.d.ts +3 -8
  89. package/dist/learning-journey.capability.d.ts.map +1 -1
  90. package/dist/learning-journey.capability.js +41 -46
  91. package/dist/learning-journey.feature.d.ts +1 -6
  92. package/dist/learning-journey.feature.d.ts.map +1 -1
  93. package/dist/learning-journey.feature.js +55 -155
  94. package/dist/node/contracts/index.js +578 -0
  95. package/dist/node/contracts/models.js +193 -0
  96. package/dist/node/contracts/onboarding.js +417 -0
  97. package/dist/node/contracts/operations.js +326 -0
  98. package/dist/node/contracts/shared.js +5 -0
  99. package/dist/node/docs/index.js +124 -0
  100. package/dist/node/docs/learning-journey.docblock.js +124 -0
  101. package/dist/node/engines/index.js +526 -0
  102. package/dist/node/engines/srs.js +198 -0
  103. package/dist/node/engines/streak.js +159 -0
  104. package/dist/node/engines/xp.js +171 -0
  105. package/dist/node/entities/ai.js +343 -0
  106. package/dist/node/entities/course.js +276 -0
  107. package/dist/node/entities/flashcard.js +222 -0
  108. package/dist/node/entities/gamification.js +340 -0
  109. package/dist/node/entities/index.js +2136 -0
  110. package/dist/node/entities/learner.js +329 -0
  111. package/dist/node/entities/onboarding.js +301 -0
  112. package/dist/node/entities/quiz.js +304 -0
  113. package/dist/node/events.js +423 -0
  114. package/dist/node/index.js +3833 -0
  115. package/dist/node/learning-journey.capability.js +40 -0
  116. package/dist/node/learning-journey.feature.js +56 -0
  117. package/dist/node/track-spec.js +0 -0
  118. package/dist/track-spec.d.ts +115 -118
  119. package/dist/track-spec.d.ts.map +1 -1
  120. package/dist/track-spec.js +1 -0
  121. package/package.json +237 -60
  122. package/dist/contracts/models.js.map +0 -1
  123. package/dist/contracts/onboarding.js.map +0 -1
  124. package/dist/contracts/operations.js.map +0 -1
  125. package/dist/contracts/shared.js.map +0 -1
  126. package/dist/docs/learning-journey.docblock.js.map +0 -1
  127. package/dist/engines/srs.js.map +0 -1
  128. package/dist/engines/streak.js.map +0 -1
  129. package/dist/engines/xp.js.map +0 -1
  130. package/dist/entities/ai.js.map +0 -1
  131. package/dist/entities/course.js.map +0 -1
  132. package/dist/entities/flashcard.js.map +0 -1
  133. package/dist/entities/gamification.js.map +0 -1
  134. package/dist/entities/index.js.map +0 -1
  135. package/dist/entities/learner.js.map +0 -1
  136. package/dist/entities/onboarding.js.map +0 -1
  137. package/dist/entities/quiz.js.map +0 -1
  138. package/dist/events.js.map +0 -1
  139. package/dist/learning-journey.capability.js.map +0 -1
  140. package/dist/learning-journey.feature.js.map +0 -1
@@ -1,6 +1,579 @@
1
- import { LEARNING_JOURNEY_OWNERS } from "./shared.js";
2
- import { AchievementModel, CardModel, CompleteLessonInput, CourseModel, DeckModel, EnrollInCourseInput, EnrollmentModel, GetDueCardsInput, GetDueCardsOutput, GetLearnerDashboardInput, LearnerDashboardModel, LearnerModel, ProgressModel, SubmitCardReviewInput, SuccessOutput } from "./models.js";
3
- import { CompleteLessonContract, EnrollInCourseContract, GetDueCardsContract, GetLearnerDashboardContract, SubmitCardReviewContract } from "./operations.js";
4
- import { GetOnboardingProgressContract, ListOnboardingTracksContract, OnboardingProgressModel, OnboardingStepModel, OnboardingStepProgressModel, OnboardingTrackModel, RecordOnboardingEventContract } from "./onboarding.js";
1
+ // @bun
2
+ // src/contracts/shared.ts
3
+ var LEARNING_JOURNEY_OWNERS = ["modules.learning-journey"];
5
4
 
6
- export { AchievementModel, CardModel, CompleteLessonContract, CompleteLessonInput, CourseModel, DeckModel, EnrollInCourseContract, EnrollInCourseInput, EnrollmentModel, GetDueCardsContract, GetDueCardsInput, GetDueCardsOutput, GetLearnerDashboardContract, GetLearnerDashboardInput, GetOnboardingProgressContract, LEARNING_JOURNEY_OWNERS, LearnerDashboardModel, LearnerModel, ListOnboardingTracksContract, OnboardingProgressModel, OnboardingStepModel, OnboardingStepProgressModel, OnboardingTrackModel, ProgressModel, RecordOnboardingEventContract, SubmitCardReviewContract, SubmitCardReviewInput, SuccessOutput };
5
+ // src/contracts/models.ts
6
+ import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
7
+ var CourseModel = defineSchemaModel({
8
+ name: "Course",
9
+ description: "A learning course",
10
+ fields: {
11
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
12
+ title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
13
+ slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
14
+ description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
15
+ difficulty: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
16
+ status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
17
+ estimatedDuration: {
18
+ type: ScalarTypeEnum.Int_unsecure(),
19
+ isOptional: true
20
+ },
21
+ thumbnailUrl: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
22
+ createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
23
+ }
24
+ });
25
+ var LearnerModel = defineSchemaModel({
26
+ name: "Learner",
27
+ description: "A learner profile",
28
+ fields: {
29
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
30
+ userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
31
+ displayName: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
32
+ level: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
33
+ totalXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
34
+ currentStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
35
+ longestStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
36
+ createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
37
+ }
38
+ });
39
+ var EnrollmentModel = defineSchemaModel({
40
+ name: "Enrollment",
41
+ description: "A course enrollment",
42
+ fields: {
43
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
44
+ learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
45
+ courseId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
46
+ status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
47
+ progress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
48
+ startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
49
+ completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
50
+ }
51
+ });
52
+ var ProgressModel = defineSchemaModel({
53
+ name: "LessonProgress",
54
+ description: "Lesson progress",
55
+ fields: {
56
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
57
+ learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
58
+ lessonId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
59
+ status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
60
+ progress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
61
+ score: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
62
+ timeSpent: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
63
+ completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
64
+ }
65
+ });
66
+ var DeckModel = defineSchemaModel({
67
+ name: "Deck",
68
+ description: "A flashcard deck",
69
+ fields: {
70
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
71
+ title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
72
+ description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
73
+ cardCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
74
+ isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: false },
75
+ createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
76
+ }
77
+ });
78
+ var CardModel = defineSchemaModel({
79
+ name: "Card",
80
+ description: "A flashcard",
81
+ fields: {
82
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
83
+ deckId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
84
+ front: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
85
+ back: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
86
+ hints: { type: ScalarTypeEnum.JSON(), isOptional: true },
87
+ isDue: { type: ScalarTypeEnum.Boolean(), isOptional: false },
88
+ nextReviewAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
89
+ }
90
+ });
91
+ var AchievementModel = defineSchemaModel({
92
+ name: "Achievement",
93
+ description: "An achievement",
94
+ fields: {
95
+ id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
96
+ key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
97
+ name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
98
+ description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
99
+ icon: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
100
+ xpReward: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
101
+ unlockedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
102
+ }
103
+ });
104
+ var EnrollInCourseInput = defineSchemaModel({
105
+ name: "EnrollInCourseInput",
106
+ description: "Input for enrolling in a course",
107
+ fields: {
108
+ courseId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
109
+ }
110
+ });
111
+ var CompleteLessonInput = defineSchemaModel({
112
+ name: "CompleteLessonInput",
113
+ description: "Input for completing a lesson",
114
+ fields: {
115
+ lessonId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
116
+ score: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
117
+ timeSpent: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
118
+ }
119
+ });
120
+ var SubmitCardReviewInput = defineSchemaModel({
121
+ name: "SubmitCardReviewInput",
122
+ description: "Input for submitting a card review",
123
+ fields: {
124
+ cardId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
125
+ rating: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
126
+ responseTimeMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
127
+ }
128
+ });
129
+ var GetDueCardsInput = defineSchemaModel({
130
+ name: "GetDueCardsInput",
131
+ description: "Input for getting due cards",
132
+ fields: {
133
+ deckId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
134
+ limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
135
+ }
136
+ });
137
+ var GetDueCardsOutput = defineSchemaModel({
138
+ name: "GetDueCardsOutput",
139
+ description: "Output for getting due cards",
140
+ fields: {
141
+ cards: { type: CardModel, isArray: true, isOptional: false },
142
+ total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
143
+ }
144
+ });
145
+ var GetLearnerDashboardInput = defineSchemaModel({
146
+ name: "GetLearnerDashboardInput",
147
+ description: "Input for getting learner dashboard",
148
+ fields: {
149
+ learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
150
+ }
151
+ });
152
+ var LearnerDashboardModel = defineSchemaModel({
153
+ name: "LearnerDashboard",
154
+ description: "Learner dashboard data",
155
+ fields: {
156
+ learner: { type: LearnerModel, isOptional: false },
157
+ currentStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
158
+ dailyXpGoal: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
159
+ dailyXpProgress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
160
+ activeEnrollments: {
161
+ type: EnrollmentModel,
162
+ isArray: true,
163
+ isOptional: false
164
+ },
165
+ recentAchievements: {
166
+ type: AchievementModel,
167
+ isArray: true,
168
+ isOptional: false
169
+ },
170
+ dueCardCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
171
+ }
172
+ });
173
+ var SuccessOutput = defineSchemaModel({
174
+ name: "SuccessOutput",
175
+ description: "Generic success output",
176
+ fields: {
177
+ success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
178
+ xpEarned: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
179
+ }
180
+ });
181
+
182
+ // src/contracts/operations.ts
183
+ import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
184
+ var EnrollInCourseContract = defineCommand({
185
+ meta: {
186
+ key: "learning.enroll",
187
+ version: "1.0.0",
188
+ stability: "stable",
189
+ owners: [...LEARNING_JOURNEY_OWNERS],
190
+ tags: ["learning", "enrollment"],
191
+ description: "Enroll in a course.",
192
+ goal: "Start learning a new course.",
193
+ context: "Called when a learner wants to start a course."
194
+ },
195
+ io: {
196
+ input: EnrollInCourseInput,
197
+ output: EnrollmentModel,
198
+ errors: {
199
+ COURSE_NOT_FOUND: {
200
+ description: "Course does not exist",
201
+ http: 404,
202
+ gqlCode: "COURSE_NOT_FOUND",
203
+ when: "Course ID is invalid"
204
+ },
205
+ ALREADY_ENROLLED: {
206
+ description: "Already enrolled in course",
207
+ http: 409,
208
+ gqlCode: "ALREADY_ENROLLED",
209
+ when: "Learner is already enrolled"
210
+ }
211
+ }
212
+ },
213
+ policy: {
214
+ auth: "user"
215
+ }
216
+ });
217
+ var CompleteLessonContract = defineCommand({
218
+ meta: {
219
+ key: "learning.completeLesson",
220
+ version: "1.0.0",
221
+ stability: "stable",
222
+ owners: [...LEARNING_JOURNEY_OWNERS],
223
+ tags: ["learning", "progress"],
224
+ description: "Mark a lesson as completed.",
225
+ goal: "Record lesson completion and earn XP.",
226
+ context: "Called when a learner finishes a lesson."
227
+ },
228
+ io: {
229
+ input: CompleteLessonInput,
230
+ output: SuccessOutput,
231
+ errors: {
232
+ LESSON_NOT_FOUND: {
233
+ description: "Lesson does not exist",
234
+ http: 404,
235
+ gqlCode: "LESSON_NOT_FOUND",
236
+ when: "Lesson ID is invalid"
237
+ },
238
+ NOT_ENROLLED: {
239
+ description: "Not enrolled in course",
240
+ http: 403,
241
+ gqlCode: "NOT_ENROLLED",
242
+ when: "Learner is not enrolled in the course"
243
+ }
244
+ }
245
+ },
246
+ policy: {
247
+ auth: "user"
248
+ }
249
+ });
250
+ var SubmitCardReviewContract = defineCommand({
251
+ meta: {
252
+ key: "learning.submitCardReview",
253
+ version: "1.0.0",
254
+ stability: "stable",
255
+ owners: [...LEARNING_JOURNEY_OWNERS],
256
+ tags: ["learning", "flashcards"],
257
+ description: "Submit a flashcard review.",
258
+ goal: "Record review and update SRS schedule.",
259
+ context: "Called when reviewing flashcards."
260
+ },
261
+ io: {
262
+ input: SubmitCardReviewInput,
263
+ output: SuccessOutput,
264
+ errors: {
265
+ CARD_NOT_FOUND: {
266
+ description: "Card does not exist",
267
+ http: 404,
268
+ gqlCode: "CARD_NOT_FOUND",
269
+ when: "Card ID is invalid"
270
+ },
271
+ INVALID_RATING: {
272
+ description: "Invalid rating",
273
+ http: 400,
274
+ gqlCode: "INVALID_RATING",
275
+ when: "Rating must be AGAIN, HARD, GOOD, or EASY"
276
+ }
277
+ }
278
+ },
279
+ policy: {
280
+ auth: "user"
281
+ }
282
+ });
283
+ var GetDueCardsContract = defineQuery({
284
+ meta: {
285
+ key: "learning.getDueCards",
286
+ version: "1.0.0",
287
+ stability: "stable",
288
+ owners: [...LEARNING_JOURNEY_OWNERS],
289
+ tags: ["learning", "flashcards"],
290
+ description: "Get flashcards due for review.",
291
+ goal: "Get the next batch of cards to review.",
292
+ context: "Called when starting a review session."
293
+ },
294
+ io: {
295
+ input: GetDueCardsInput,
296
+ output: GetDueCardsOutput
297
+ },
298
+ policy: {
299
+ auth: "user"
300
+ }
301
+ });
302
+ var GetLearnerDashboardContract = defineQuery({
303
+ meta: {
304
+ key: "learning.getDashboard",
305
+ version: "1.0.0",
306
+ stability: "stable",
307
+ owners: [...LEARNING_JOURNEY_OWNERS],
308
+ tags: ["learning", "dashboard"],
309
+ description: "Get learner dashboard data.",
310
+ goal: "Display learner progress and stats.",
311
+ context: "Called when viewing the learning dashboard."
312
+ },
313
+ io: {
314
+ input: GetLearnerDashboardInput,
315
+ output: LearnerDashboardModel
316
+ },
317
+ policy: {
318
+ auth: "user"
319
+ }
320
+ });
321
+
322
+ // src/contracts/onboarding.ts
323
+ import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
324
+ import { defineCommand as defineCommand2, defineQuery as defineQuery2 } from "@contractspec/lib.contracts";
325
+ var OnboardingStepConditionModel = defineSchemaModel2({
326
+ name: "OnboardingStepCondition",
327
+ description: "Structured completion condition for onboarding steps.",
328
+ fields: {
329
+ eventName: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
330
+ eventVersion: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
331
+ sourceModule: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
332
+ payloadFilter: { type: ScalarTypeEnum2.JSON(), isOptional: true }
333
+ }
334
+ });
335
+ var OnboardingStepModel = defineSchemaModel2({
336
+ name: "OnboardingStep",
337
+ description: "Declarative onboarding step definition.",
338
+ fields: {
339
+ id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
340
+ trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
341
+ title: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
342
+ description: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
343
+ instructions: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
344
+ helpUrl: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
345
+ order: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
346
+ completionEvent: {
347
+ type: ScalarTypeEnum2.String_unsecure(),
348
+ isOptional: false
349
+ },
350
+ completionCondition: {
351
+ type: OnboardingStepConditionModel,
352
+ isOptional: true
353
+ },
354
+ xpReward: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
355
+ isRequired: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
356
+ canSkip: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
357
+ actionUrl: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
358
+ actionLabel: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
359
+ metadata: { type: ScalarTypeEnum2.JSON(), isOptional: true }
360
+ }
361
+ });
362
+ var OnboardingTrackModel = defineSchemaModel2({
363
+ name: "OnboardingTrack",
364
+ description: "Onboarding track metadata and steps.",
365
+ fields: {
366
+ id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
367
+ productId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
368
+ name: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
369
+ description: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
370
+ targetUserSegment: {
371
+ type: ScalarTypeEnum2.String_unsecure(),
372
+ isOptional: true
373
+ },
374
+ targetRole: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
375
+ isActive: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
376
+ isRequired: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
377
+ canSkip: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
378
+ totalXp: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
379
+ completionXpBonus: {
380
+ type: ScalarTypeEnum2.Int_unsecure(),
381
+ isOptional: true
382
+ },
383
+ completionBadgeKey: {
384
+ type: ScalarTypeEnum2.String_unsecure(),
385
+ isOptional: true
386
+ },
387
+ streakHoursWindow: {
388
+ type: ScalarTypeEnum2.Int_unsecure(),
389
+ isOptional: true
390
+ },
391
+ streakBonusXp: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
392
+ metadata: { type: ScalarTypeEnum2.JSON(), isOptional: true },
393
+ steps: { type: OnboardingStepModel, isArray: true, isOptional: false }
394
+ }
395
+ });
396
+ var OnboardingStepProgressModel = defineSchemaModel2({
397
+ name: "OnboardingStepProgress",
398
+ description: "Progress for a specific onboarding step.",
399
+ fields: {
400
+ stepId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
401
+ status: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
402
+ xpEarned: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
403
+ triggeringEvent: {
404
+ type: ScalarTypeEnum2.String_unsecure(),
405
+ isOptional: true
406
+ },
407
+ eventPayload: { type: ScalarTypeEnum2.JSON(), isOptional: true },
408
+ completedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true }
409
+ }
410
+ });
411
+ var OnboardingProgressModel = defineSchemaModel2({
412
+ name: "OnboardingProgress",
413
+ description: "Aggregated progress for an onboarding track.",
414
+ fields: {
415
+ learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
416
+ trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
417
+ progress: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
418
+ isCompleted: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
419
+ xpEarned: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
420
+ startedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
421
+ completedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
422
+ lastActivityAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
423
+ steps: {
424
+ type: OnboardingStepProgressModel,
425
+ isArray: true,
426
+ isOptional: true
427
+ }
428
+ }
429
+ });
430
+ var ListOnboardingTracksInput = defineSchemaModel2({
431
+ name: "ListOnboardingTracksInput",
432
+ description: "Filters for listing onboarding tracks.",
433
+ fields: {
434
+ learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
435
+ productId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
436
+ trackIds: {
437
+ type: ScalarTypeEnum2.String_unsecure(),
438
+ isArray: true,
439
+ isOptional: true
440
+ },
441
+ includeProgress: {
442
+ type: ScalarTypeEnum2.Boolean(),
443
+ isOptional: true
444
+ }
445
+ }
446
+ });
447
+ var ListOnboardingTracksOutput = defineSchemaModel2({
448
+ name: "ListOnboardingTracksOutput",
449
+ description: "Available onboarding tracks with optional progress.",
450
+ fields: {
451
+ tracks: { type: OnboardingTrackModel, isArray: true, isOptional: false },
452
+ progress: {
453
+ type: OnboardingProgressModel,
454
+ isArray: true,
455
+ isOptional: true
456
+ }
457
+ }
458
+ });
459
+ var GetOnboardingProgressInput = defineSchemaModel2({
460
+ name: "GetOnboardingProgressInput",
461
+ description: "Input for fetching onboarding progress for a track.",
462
+ fields: {
463
+ trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
464
+ learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
465
+ }
466
+ });
467
+ var RecordOnboardingEventInput = defineSchemaModel2({
468
+ name: "RecordOnboardingEventInput",
469
+ description: "Record a domain event to advance onboarding progress via completion conditions.",
470
+ fields: {
471
+ learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
472
+ trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
473
+ eventName: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
474
+ eventVersion: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
475
+ eventPayload: { type: ScalarTypeEnum2.JSON(), isOptional: true },
476
+ occurredAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true }
477
+ }
478
+ });
479
+ var ListOnboardingTracksContract = defineQuery2({
480
+ meta: {
481
+ key: "learning.onboarding.listTracks",
482
+ version: "1.0.0",
483
+ stability: "stable",
484
+ owners: [...LEARNING_JOURNEY_OWNERS],
485
+ tags: ["learning", "onboarding", "journey"],
486
+ description: "List onboarding tracks available to a learner or product.",
487
+ goal: "Expose track catalog for UI/API surfaces.",
488
+ context: "Called when showing onboarding/learning journey catalog."
489
+ },
490
+ io: {
491
+ input: ListOnboardingTracksInput,
492
+ output: ListOnboardingTracksOutput
493
+ },
494
+ policy: {
495
+ auth: "user"
496
+ }
497
+ });
498
+ var GetOnboardingProgressContract = defineQuery2({
499
+ meta: {
500
+ key: "learning.onboarding.getProgress",
501
+ version: "1.0.0",
502
+ stability: "stable",
503
+ owners: [...LEARNING_JOURNEY_OWNERS],
504
+ tags: ["learning", "onboarding", "journey"],
505
+ description: "Fetch onboarding progress for a specific track.",
506
+ goal: "Display learner progress and remaining steps.",
507
+ context: "Called when rendering a track detail or widget."
508
+ },
509
+ io: {
510
+ input: GetOnboardingProgressInput,
511
+ output: OnboardingProgressModel
512
+ },
513
+ policy: {
514
+ auth: "user"
515
+ }
516
+ });
517
+ var RecordOnboardingEventContract = defineCommand2({
518
+ meta: {
519
+ key: "learning.onboarding.recordEvent",
520
+ version: "1.0.0",
521
+ stability: "stable",
522
+ owners: [...LEARNING_JOURNEY_OWNERS],
523
+ tags: ["learning", "onboarding", "events"],
524
+ description: "Record a domain event to evaluate onboarding step completion conditions.",
525
+ goal: "Advance onboarding automatically from product events.",
526
+ context: "Called by event bus handlers when relevant product events fire (e.g., deal.created)."
527
+ },
528
+ io: {
529
+ input: RecordOnboardingEventInput,
530
+ output: SuccessOutput,
531
+ errors: {
532
+ TRACK_NOT_FOUND: {
533
+ description: "Track not found for event routing",
534
+ http: 404,
535
+ gqlCode: "TRACK_NOT_FOUND",
536
+ when: "Track ID or routing context is invalid"
537
+ },
538
+ STEP_NOT_FOUND: {
539
+ description: "Step not found for completion condition",
540
+ http: 404,
541
+ gqlCode: "STEP_NOT_FOUND",
542
+ when: "No step matches the incoming event"
543
+ }
544
+ }
545
+ },
546
+ policy: {
547
+ auth: "user"
548
+ }
549
+ });
550
+ export {
551
+ SuccessOutput,
552
+ SubmitCardReviewInput,
553
+ SubmitCardReviewContract,
554
+ RecordOnboardingEventContract,
555
+ ProgressModel,
556
+ OnboardingTrackModel,
557
+ OnboardingStepProgressModel,
558
+ OnboardingStepModel,
559
+ OnboardingProgressModel,
560
+ ListOnboardingTracksContract,
561
+ LearnerModel,
562
+ LearnerDashboardModel,
563
+ LEARNING_JOURNEY_OWNERS,
564
+ GetOnboardingProgressContract,
565
+ GetLearnerDashboardInput,
566
+ GetLearnerDashboardContract,
567
+ GetDueCardsOutput,
568
+ GetDueCardsInput,
569
+ GetDueCardsContract,
570
+ EnrollmentModel,
571
+ EnrollInCourseInput,
572
+ EnrollInCourseContract,
573
+ DeckModel,
574
+ CourseModel,
575
+ CompleteLessonInput,
576
+ CompleteLessonContract,
577
+ CardModel,
578
+ AchievementModel
579
+ };