@contractspec/module.learning-journey 1.57.0 → 1.59.0

package/dist/browser/contracts/index.js

@@ -0,0 +1,578 @@
+// src/contracts/shared.ts
+var LEARNING_JOURNEY_OWNERS = ["modules.learning-journey"];
+
+// src/contracts/models.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+var CourseModel = defineSchemaModel({
+  name: "Course",
+  description: "A learning course",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    difficulty: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    estimatedDuration: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    thumbnailUrl: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var LearnerModel = defineSchemaModel({
+  name: "Learner",
+  description: "A learner profile",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    displayName: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    level: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    totalXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    currentStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    longestStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var EnrollmentModel = defineSchemaModel({
+  name: "Enrollment",
+  description: "A course enrollment",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    courseId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    progress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var ProgressModel = defineSchemaModel({
+  name: "LessonProgress",
+  description: "Lesson progress",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    lessonId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    progress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    score: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeSpent: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var DeckModel = defineSchemaModel({
+  name: "Deck",
+  description: "A flashcard deck",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    cardCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var CardModel = defineSchemaModel({
+  name: "Card",
+  description: "A flashcard",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    deckId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    front: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    back: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    hints: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    isDue: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    nextReviewAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var AchievementModel = defineSchemaModel({
+  name: "Achievement",
+  description: "An achievement",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    icon: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    xpReward: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    unlockedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var EnrollInCourseInput = defineSchemaModel({
+  name: "EnrollInCourseInput",
+  description: "Input for enrolling in a course",
+  fields: {
+    courseId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var CompleteLessonInput = defineSchemaModel({
+  name: "CompleteLessonInput",
+  description: "Input for completing a lesson",
+  fields: {
+    lessonId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    score: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeSpent: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var SubmitCardReviewInput = defineSchemaModel({
+  name: "SubmitCardReviewInput",
+  description: "Input for submitting a card review",
+  fields: {
+    cardId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    rating: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    responseTimeMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var GetDueCardsInput = defineSchemaModel({
+  name: "GetDueCardsInput",
+  description: "Input for getting due cards",
+  fields: {
+    deckId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var GetDueCardsOutput = defineSchemaModel({
+  name: "GetDueCardsOutput",
+  description: "Output for getting due cards",
+  fields: {
+    cards: { type: CardModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var GetLearnerDashboardInput = defineSchemaModel({
+  name: "GetLearnerDashboardInput",
+  description: "Input for getting learner dashboard",
+  fields: {
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var LearnerDashboardModel = defineSchemaModel({
+  name: "LearnerDashboard",
+  description: "Learner dashboard data",
+  fields: {
+    learner: { type: LearnerModel, isOptional: false },
+    currentStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    dailyXpGoal: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    dailyXpProgress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    activeEnrollments: {
+      type: EnrollmentModel,
+      isArray: true,
+      isOptional: false
+    },
+    recentAchievements: {
+      type: AchievementModel,
+      isArray: true,
+      isOptional: false
+    },
+    dueCardCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var SuccessOutput = defineSchemaModel({
+  name: "SuccessOutput",
+  description: "Generic success output",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    xpEarned: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+
+// src/contracts/operations.ts
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var EnrollInCourseContract = defineCommand({
+  meta: {
+    key: "learning.enroll",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "enrollment"],
+    description: "Enroll in a course.",
+    goal: "Start learning a new course.",
+    context: "Called when a learner wants to start a course."
+  },
+  io: {
+    input: EnrollInCourseInput,
+    output: EnrollmentModel,
+    errors: {
+      COURSE_NOT_FOUND: {
+        description: "Course does not exist",
+        http: 404,
+        gqlCode: "COURSE_NOT_FOUND",
+        when: "Course ID is invalid"
+      },
+      ALREADY_ENROLLED: {
+        description: "Already enrolled in course",
+        http: 409,
+        gqlCode: "ALREADY_ENROLLED",
+        when: "Learner is already enrolled"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var CompleteLessonContract = defineCommand({
+  meta: {
+    key: "learning.completeLesson",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "progress"],
+    description: "Mark a lesson as completed.",
+    goal: "Record lesson completion and earn XP.",
+    context: "Called when a learner finishes a lesson."
+  },
+  io: {
+    input: CompleteLessonInput,
+    output: SuccessOutput,
+    errors: {
+      LESSON_NOT_FOUND: {
+        description: "Lesson does not exist",
+        http: 404,
+        gqlCode: "LESSON_NOT_FOUND",
+        when: "Lesson ID is invalid"
+      },
+      NOT_ENROLLED: {
+        description: "Not enrolled in course",
+        http: 403,
+        gqlCode: "NOT_ENROLLED",
+        when: "Learner is not enrolled in the course"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var SubmitCardReviewContract = defineCommand({
+  meta: {
+    key: "learning.submitCardReview",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "flashcards"],
+    description: "Submit a flashcard review.",
+    goal: "Record review and update SRS schedule.",
+    context: "Called when reviewing flashcards."
+  },
+  io: {
+    input: SubmitCardReviewInput,
+    output: SuccessOutput,
+    errors: {
+      CARD_NOT_FOUND: {
+        description: "Card does not exist",
+        http: 404,
+        gqlCode: "CARD_NOT_FOUND",
+        when: "Card ID is invalid"
+      },
+      INVALID_RATING: {
+        description: "Invalid rating",
+        http: 400,
+        gqlCode: "INVALID_RATING",
+        when: "Rating must be AGAIN, HARD, GOOD, or EASY"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var GetDueCardsContract = defineQuery({
+  meta: {
+    key: "learning.getDueCards",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "flashcards"],
+    description: "Get flashcards due for review.",
+    goal: "Get the next batch of cards to review.",
+    context: "Called when starting a review session."
+  },
+  io: {
+    input: GetDueCardsInput,
+    output: GetDueCardsOutput
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var GetLearnerDashboardContract = defineQuery({
+  meta: {
+    key: "learning.getDashboard",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "dashboard"],
+    description: "Get learner dashboard data.",
+    goal: "Display learner progress and stats.",
+    context: "Called when viewing the learning dashboard."
+  },
+  io: {
+    input: GetLearnerDashboardInput,
+    output: LearnerDashboardModel
+  },
+  policy: {
+    auth: "user"
+  }
+});
+
+// src/contracts/onboarding.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
+import { defineCommand as defineCommand2, defineQuery as defineQuery2 } from "@contractspec/lib.contracts";
+var OnboardingStepConditionModel = defineSchemaModel2({
+  name: "OnboardingStepCondition",
+  description: "Structured completion condition for onboarding steps.",
+  fields: {
+    eventName: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    eventVersion: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    sourceModule: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    payloadFilter: { type: ScalarTypeEnum2.JSON(), isOptional: true }
+  }
+});
+var OnboardingStepModel = defineSchemaModel2({
+  name: "OnboardingStep",
+  description: "Declarative onboarding step definition.",
+  fields: {
+    id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    instructions: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    helpUrl: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    order: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    completionEvent: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    completionCondition: {
+      type: OnboardingStepConditionModel,
+      isOptional: true
+    },
+    xpReward: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    isRequired: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    canSkip: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    actionUrl: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    actionLabel: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum2.JSON(), isOptional: true }
+  }
+});
+var OnboardingTrackModel = defineSchemaModel2({
+  name: "OnboardingTrack",
+  description: "Onboarding track metadata and steps.",
+  fields: {
+    id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    productId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    name: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    targetUserSegment: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    targetRole: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    isActive: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    isRequired: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    canSkip: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    totalXp: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    completionXpBonus: {
+      type: ScalarTypeEnum2.Int_unsecure(),
+      isOptional: true
+    },
+    completionBadgeKey: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    streakHoursWindow: {
+      type: ScalarTypeEnum2.Int_unsecure(),
+      isOptional: true
+    },
+    streakBonusXp: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum2.JSON(), isOptional: true },
+    steps: { type: OnboardingStepModel, isArray: true, isOptional: false }
+  }
+});
+var OnboardingStepProgressModel = defineSchemaModel2({
+  name: "OnboardingStepProgress",
+  description: "Progress for a specific onboarding step.",
+  fields: {
+    stepId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    xpEarned: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    triggeringEvent: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    eventPayload: { type: ScalarTypeEnum2.JSON(), isOptional: true },
+    completedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true }
+  }
+});
+var OnboardingProgressModel = defineSchemaModel2({
+  name: "OnboardingProgress",
+  description: "Aggregated progress for an onboarding track.",
+  fields: {
+    learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    progress: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    isCompleted: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    xpEarned: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    startedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    completedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    lastActivityAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    steps: {
+      type: OnboardingStepProgressModel,
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var ListOnboardingTracksInput = defineSchemaModel2({
+  name: "ListOnboardingTracksInput",
+  description: "Filters for listing onboarding tracks.",
+  fields: {
+    learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    productId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    trackIds: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    },
+    includeProgress: {
+      type: ScalarTypeEnum2.Boolean(),
+      isOptional: true
+    }
+  }
+});
+var ListOnboardingTracksOutput = defineSchemaModel2({
+  name: "ListOnboardingTracksOutput",
+  description: "Available onboarding tracks with optional progress.",
+  fields: {
+    tracks: { type: OnboardingTrackModel, isArray: true, isOptional: false },
+    progress: {
+      type: OnboardingProgressModel,
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var GetOnboardingProgressInput = defineSchemaModel2({
+  name: "GetOnboardingProgressInput",
+  description: "Input for fetching onboarding progress for a track.",
+  fields: {
+    trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var RecordOnboardingEventInput = defineSchemaModel2({
+  name: "RecordOnboardingEventInput",
+  description: "Record a domain event to advance onboarding progress via completion conditions.",
+  fields: {
+    learnerId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    trackId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    eventName: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    eventVersion: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    eventPayload: { type: ScalarTypeEnum2.JSON(), isOptional: true },
+    occurredAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true }
+  }
+});
+var ListOnboardingTracksContract = defineQuery2({
+  meta: {
+    key: "learning.onboarding.listTracks",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "onboarding", "journey"],
+    description: "List onboarding tracks available to a learner or product.",
+    goal: "Expose track catalog for UI/API surfaces.",
+    context: "Called when showing onboarding/learning journey catalog."
+  },
+  io: {
+    input: ListOnboardingTracksInput,
+    output: ListOnboardingTracksOutput
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var GetOnboardingProgressContract = defineQuery2({
+  meta: {
+    key: "learning.onboarding.getProgress",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "onboarding", "journey"],
+    description: "Fetch onboarding progress for a specific track.",
+    goal: "Display learner progress and remaining steps.",
+    context: "Called when rendering a track detail or widget."
+  },
+  io: {
+    input: GetOnboardingProgressInput,
+    output: OnboardingProgressModel
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var RecordOnboardingEventContract = defineCommand2({
+  meta: {
+    key: "learning.onboarding.recordEvent",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...LEARNING_JOURNEY_OWNERS],
+    tags: ["learning", "onboarding", "events"],
+    description: "Record a domain event to evaluate onboarding step completion conditions.",
+    goal: "Advance onboarding automatically from product events.",
+    context: "Called by event bus handlers when relevant product events fire (e.g., deal.created)."
+  },
+  io: {
+    input: RecordOnboardingEventInput,
+    output: SuccessOutput,
+    errors: {
+      TRACK_NOT_FOUND: {
+        description: "Track not found for event routing",
+        http: 404,
+        gqlCode: "TRACK_NOT_FOUND",
+        when: "Track ID or routing context is invalid"
+      },
+      STEP_NOT_FOUND: {
+        description: "Step not found for completion condition",
+        http: 404,
+        gqlCode: "STEP_NOT_FOUND",
+        when: "No step matches the incoming event"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+export {
+  SuccessOutput,
+  SubmitCardReviewInput,
+  SubmitCardReviewContract,
+  RecordOnboardingEventContract,
+  ProgressModel,
+  OnboardingTrackModel,
+  OnboardingStepProgressModel,
+  OnboardingStepModel,
+  OnboardingProgressModel,
+  ListOnboardingTracksContract,
+  LearnerModel,
+  LearnerDashboardModel,
+  LEARNING_JOURNEY_OWNERS,
+  GetOnboardingProgressContract,
+  GetLearnerDashboardInput,
+  GetLearnerDashboardContract,
+  GetDueCardsOutput,
+  GetDueCardsInput,
+  GetDueCardsContract,
+  EnrollmentModel,
+  EnrollInCourseInput,
+  EnrollInCourseContract,
+  DeckModel,
+  CourseModel,
+  CompleteLessonInput,
+  CompleteLessonContract,
+  CardModel,
+  AchievementModel
+};