@contractspec/example.learning-journey-registry 0.0.0-canary-20260113170453

package/src/api.ts

@@ -0,0 +1,301 @@
+import { learningJourneyTracks } from './tracks';
+import type {
+  LearningJourneyTrackSpec,
+  StepAvailabilitySpec,
+  StepCompletionConditionSpec,
+} from '@contractspec/module.learning-journey/track-spec';
+import type { LearningEvent, StepProgress, TrackProgress } from './api-types';
+import {
+  getLearnerTracks,
+  getTrackResolver,
+  initProgress,
+} from './progress-store';
+
+const getTrack = getTrackResolver(learningJourneyTracks);
+
+const matchesFilter = (
+  filter: Record<string, unknown> | undefined,
+  payload: Record<string, unknown> | undefined
+): boolean => {
+  if (!filter) return true;
+  if (!payload) return false;
+  return Object.entries(filter).every(([key, value]) => payload[key] === value);
+};
+
+const matchesBaseEvent = (
+  condition: {
+    eventName: string;
+    eventVersion?: number;
+    sourceModule?: string;
+    payloadFilter?: Record<string, unknown>;
+  },
+  event: LearningEvent
+): boolean => {
+  if (condition.eventName !== event.name) return false;
+  if (condition.eventVersion !== undefined && event.version !== undefined) {
+    if (condition.eventVersion !== event.version) return false;
+  }
+  if (
+    condition.sourceModule &&
+    event.sourceModule &&
+    condition.sourceModule !== event.sourceModule
+  ) {
+    return false;
+  }
+  return matchesFilter(
+    condition.payloadFilter,
+    event.payload as Record<string, unknown> | undefined
+  );
+};
+
+const matchesCondition = (
+  condition: StepCompletionConditionSpec,
+  event: LearningEvent,
+  step: StepProgress,
+  trackStartedAt: Date | undefined
+): {
+  matched: boolean;
+  occurrences?: number;
+  masteryCount?: number;
+} => {
+  if (condition.kind === 'count') {
+    if (!matchesBaseEvent(condition, event)) return { matched: false };
+    const occurrences = (step.occurrences ?? 0) + 1;
+    const within =
+      condition.withinHours === undefined ||
+      Boolean(
+        trackStartedAt &&
+        event.occurredAt &&
+        (event.occurredAt.getTime() - trackStartedAt.getTime()) /
+          (1000 * 60 * 60) <=
+          condition.withinHours
+      );
+    return { matched: within && occurrences >= condition.atLeast, occurrences };
+  }
+
+  if (condition.kind === 'time_window') {
+    if (!matchesBaseEvent(condition, event)) return { matched: false };
+    if (
+      condition.withinHoursOfStart !== undefined &&
+      trackStartedAt &&
+      event.occurredAt
+    ) {
+      const hoursSinceStart =
+        (event.occurredAt.getTime() - trackStartedAt.getTime()) /
+        (1000 * 60 * 60);
+      if (hoursSinceStart > condition.withinHoursOfStart) {
+        return { matched: false };
+      }
+    }
+    return { matched: true };
+  }
+
+  if (condition.kind === 'srs_mastery') {
+    if (event.name !== condition.eventName) return { matched: false };
+    const payload = event.payload as Record<string, unknown> | undefined;
+    if (!matchesFilter(condition.payloadFilter, payload)) {
+      return { matched: false };
+    }
+    const skillKey = condition.skillIdField ?? 'skillId';
+    const masteryKey = condition.masteryField ?? 'mastery';
+    const skillId = payload?.[skillKey];
+    const masteryValue = payload?.[masteryKey];
+    if (skillId === undefined || masteryValue === undefined) {
+      return { matched: false };
+    }
+    if (typeof masteryValue !== 'number') return { matched: false };
+    if (masteryValue < condition.minimumMastery) return { matched: false };
+    const masteryCount = (step.masteryCount ?? 0) + 1;
+    const required = condition.requiredCount ?? 1;
+    return { matched: masteryCount >= required, masteryCount };
+  }
+
+  return { matched: matchesBaseEvent(condition, event) };
+};
+
+const getAvailability = (
+  availability: StepAvailabilitySpec | undefined,
+  startedAt: Date | undefined
+): { availableAt?: Date; dueAt?: Date } => {
+  if (!availability || !startedAt) return {};
+
+  const baseTime = startedAt.getTime();
+  let unlockTime = baseTime;
+
+  if (availability.unlockOnDay !== undefined) {
+    unlockTime =
+      baseTime + (availability.unlockOnDay - 1) * 24 * 60 * 60 * 1000;
+  }
+
+  if (availability.unlockAfterHours !== undefined) {
+    unlockTime = baseTime + availability.unlockAfterHours * 60 * 60 * 1000;
+  }
+
+  const availableAt = new Date(unlockTime);
+  const dueAt =
+    availability.dueWithinHours !== undefined
+      ? new Date(
+          availableAt.getTime() + availability.dueWithinHours * 60 * 60 * 1000
+        )
+      : undefined;
+
+  return { availableAt, dueAt };
+};
+
+const computeProgressPercent = (steps: StepProgress[]): number => {
+  const total = steps.length || 1;
+  const done = steps.filter((s) => s.status === 'COMPLETED').length;
+  return Math.round((done / total) * 100);
+};
+
+const applyTrackCompletionBonuses = (
+  track: LearningJourneyTrackSpec,
+  progress: TrackProgress
+) => {
+  if (progress.isCompleted) return progress;
+
+  const completedAt = new Date();
+  const startedAt = progress.startedAt ?? completedAt;
+  const hoursElapsed =
+    (completedAt.getTime() - startedAt.getTime()) / (1000 * 60 * 60);
+
+  let xpEarned = progress.xpEarned;
+  const { completionRewards, streakRule } = track;
+
+  if (completionRewards?.xpBonus) {
+    xpEarned += completionRewards.xpBonus;
+  }
+
+  if (
+    streakRule?.hoursWindow !== undefined &&
+    hoursElapsed <= streakRule.hoursWindow &&
+    streakRule.bonusXp
+  ) {
+    xpEarned += streakRule.bonusXp;
+  }
+
+  return {
+    ...progress,
+    xpEarned,
+    isCompleted: true,
+    completedAt,
+    lastActivityAt: completedAt,
+  };
+};
+
+export const listTracks = (learnerId?: string) => {
+  const progressMap = learnerId ? getLearnerTracks(learnerId) : undefined;
+  const progress =
+    learnerId && progressMap
+      ? Array.from(progressMap.values())
+      : ([] as TrackProgress[]);
+
+  return {
+    tracks: learningJourneyTracks,
+    progress,
+  };
+};
+
+export const getProgress = (trackId: string, learnerId: string) => {
+  const track = getTrack(trackId);
+  if (!track) return undefined;
+
+  const map = getLearnerTracks(learnerId);
+  const existing = map.get(trackId) ?? initProgress(learnerId, track);
+  map.set(trackId, existing);
+  return existing;
+};
+
+export const recordEvent = (event: LearningEvent) => {
+  const targets =
+    event.trackId !== undefined
+      ? learningJourneyTracks.filter((t) => t.id === event.trackId)
+      : learningJourneyTracks;
+
+  const updated: TrackProgress[] = [];
+  const eventTime = event.occurredAt ?? new Date();
+
+  for (const track of targets) {
+    const map = getLearnerTracks(event.learnerId);
+    const current = map.get(track.id) ?? initProgress(event.learnerId, track);
+    const startedAt = current.startedAt ?? eventTime;
+
+    let changed = current.startedAt === undefined;
+    const steps: StepProgress[] = current.steps.map((step) => {
+      if (step.status === 'COMPLETED') return step;
+
+      const spec = track.steps.find((s) => s.id === step.id);
+      if (!spec) return step;
+
+      const { availableAt, dueAt } = getAvailability(
+        spec.availability,
+        startedAt
+      );
+      if (availableAt && eventTime < availableAt) {
+        return { ...step, availableAt, dueAt };
+      }
+      if (dueAt && eventTime > dueAt) {
+        // keep pending but note deadlines
+        return { ...step, availableAt, dueAt };
+      }
+
+      const result = matchesCondition(spec.completion, event, step, startedAt);
+
+      if (result.matched) {
+        changed = true;
+        return {
+          ...step,
+          status: 'COMPLETED',
+          xpEarned: spec.xpReward ?? 0,
+          completedAt: eventTime,
+          triggeringEvent: event.name,
+          eventPayload: event.payload,
+          occurrences: result.occurrences ?? step.occurrences,
+          masteryCount: result.masteryCount ?? step.masteryCount,
+          availableAt,
+          dueAt,
+        };
+      }
+
+      if (
+        result.occurrences !== undefined ||
+        result.masteryCount !== undefined
+      ) {
+        changed = true;
+      }
+
+      return {
+        ...step,
+        occurrences: result.occurrences ?? step.occurrences,
+        masteryCount: result.masteryCount ?? step.masteryCount,
+        availableAt,
+        dueAt,
+      };
+    });
+
+    if (!changed) {
+      continue;
+    }
+
+    const xpEarned =
+      steps.reduce((sum, s) => sum + s.xpEarned, 0) + (track.totalXp ?? 0);
+    let progress: TrackProgress = {
+      ...current,
+      steps,
+      xpEarned,
+      startedAt,
+      lastActivityAt: eventTime,
+      progress: computeProgressPercent(steps),
+    };
+
+    const allDone = steps.every((s) => s.status === 'COMPLETED');
+    if (allDone) {
+      progress = applyTrackCompletionBonuses(track, progress);
+    }
+
+    map.set(track.id, progress);
+    updated.push(progress);
+  }
+
+  return updated;
+};

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './learning-journey-registry.docblock';

package/src/docs/learning-journey-registry.docblock.ts

@@ -0,0 +1,36 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const registryDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.learning-journey.registry',
+    title: 'Learning Journey — Example Track Registry',
+    summary:
+      'Aggregates learning journey example tracks (Studio onboarding, Platform tour, CRM first win, Drills, Ambient Coach, Quest challenges).',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/learning-journey/registry',
+    tags: ['learning', 'registry', 'onboarding'],
+    body: `## Tracks
+- \`studio_getting_started\` (Studio onboarding)
+- \`platform_primitives_tour\` (Platform primitives)
+- \`crm_first_win\` (CRM pipeline onboarding)
+- \`drills_language_basics\` (Drills & SRS)
+- \`money_ambient_coach\`, \`coliving_ambient_coach\` (Ambient tips)
+- \`money_reset_7day\` (Quest/challenge)
+
+## Exports
+- \`learningJourneyTracks\` — raw specs
+- \`onboardingTrackCatalog\` — DTOs aligned with onboarding API
+- \`mapTrackSpecToDto\` — helper to map individual tracks
+
+## Wiring
+- Use with onboarding API contracts:
+  - \`learning.onboarding.listTracks\`
+  - \`learning.onboarding.getProgress\`
+  - \`learning.onboarding.recordEvent\`
+- Intended for registry/adapters in Studio UI or services that surface tracks.`,
+  },
+];
+
+registerDocBlocks(registryDocBlocks);

package/src/example.ts

@@ -0,0 +1,31 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'learning-journey-registry',
+    version: '1.0.0',
+    title: 'Learning Journey Registry',
+    description:
+      'Registry of learning journey tracks + presentations + UI mini-app bindings.',
+    kind: 'library',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['learning', 'journey', 'registry'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-registry',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-registry',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,8 @@
+import './docs';
+
+export * from './tracks';
+export * from './api';
+export * from './presentations';
+export * from './learning-journey-registry.feature';
+export * from './ui';
+export { default as example } from './example';

package/src/learning-journey-registry.feature.ts

@@ -0,0 +1,64 @@
+/**
+ * Learning Journey Registry Feature Module Specification
+ *
+ * Defines the feature module for the learning journey registry.
+ */
+import { defineFeature } from '@contractspec/lib.contracts';
+
+/**
+ * Learning Journey Registry feature module that bundles
+ * the shared presentations for learning journey tracks.
+ */
+export const LearningJourneyRegistryFeature = defineFeature({
+  meta: {
+    key: 'learning-journey-registry',
+    version: '1.0.0',
+    title: 'Learning Journey Registry',
+    description:
+      'Shared registry and presentations for learning journey tracks',
+    domain: 'learning-journey',
+    owners: ['@learning-team'],
+    tags: ['learning', 'journey', 'onboarding', 'registry'],
+    stability: 'experimental',
+  },
+
+  // No operations in the registry - it's presentation-only
+  operations: [],
+
+  // Events emitted by this feature
+  events: [],
+
+  // Presentations associated with this feature
+  presentations: [
+    { key: 'learning.journey.track_list', version: '1.0.0' },
+    { key: 'learning.journey.track_detail', version: '1.0.0' },
+    { key: 'learning.journey.progress_widget', version: '1.0.0' },
+  ],
+
+  // No op to presentation links for registry
+  opToPresentation: [],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    {
+      key: 'learning.journey.track_list',
+      version: '1.0.0',
+      targets: ['react', 'markdown'],
+    },
+    {
+      key: 'learning.journey.track_detail',
+      version: '1.0.0',
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'learning.journey.progress_widget',
+      version: '1.0.0',
+      targets: ['react'],
+    },
+  ],
+
+  // Capability requirements
+  capabilities: {
+    requires: [{ key: 'identity', version: '1.0.0' }],
+  },
+});

package/src/presentations/index.ts

@@ -0,0 +1,65 @@
+import { definePresentation, StabilityEnum, type PresentationSpecMeta } from '@contractspec/lib.contracts';
+
+const baseMeta: Pick<
+  PresentationSpecMeta,
+  'domain' | 'owners' | 'tags' | 'title' | 'stability' | 'goal' | 'context'
+> = {
+  domain: 'learning-journey',
+  title: 'Learning Journey',
+  owners: ['@learning-team'] as string[],
+  tags: ['learning', 'journey', 'onboarding'] as string[],
+  stability: StabilityEnum.Experimental,
+  goal: 'Progress through learning tracks',
+  context: 'Learning journey section',
+};
+
+export const LearningTrackListPresentation = definePresentation({
+  meta: {
+    key: 'learning.journey.track_list',
+    version: '1.0.0',
+    description: 'List of learning journeys available to the learner.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackList',
+  },
+  targets: ['react', 'markdown'],
+});
+
+export const LearningTrackDetailPresentation = definePresentation({
+  meta: {
+    key: 'learning.journey.track_detail',
+    version: '1.0.0',
+    description: 'Track detail with steps and progress state.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackDetail',
+  },
+  targets: ['react', 'markdown', 'application/json'],
+});
+
+export const LearningTrackProgressWidgetPresentation = definePresentation({
+  meta: {
+    key: 'learning.journey.progress_widget',
+    version: '1.0.0',
+    description: 'Compact widget showing progress for active track.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackProgressWidget',
+  },
+  targets: ['react'],
+});
+
+export const learningJourneyPresentations = [
+  LearningTrackListPresentation,
+  LearningTrackDetailPresentation,
+  LearningTrackProgressWidgetPresentation,
+];

package/src/progress-store.ts

@@ -0,0 +1,39 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+import type { TrackProgress } from './api-types';
+
+export const progressStore = new Map<string, Map<string, TrackProgress>>();
+
+export const getTrackResolver =
+  (tracks: LearningJourneyTrackSpec[]) =>
+  (trackId: string): LearningJourneyTrackSpec | undefined =>
+    tracks.find((t) => t.id === trackId);
+
+export const getLearnerTracks = (learnerId: string) => {
+  const existing = progressStore.get(learnerId);
+  if (existing) return existing;
+  const map = new Map<string, TrackProgress>();
+  progressStore.set(learnerId, map);
+  return map;
+};
+
+export const initProgress = (
+  learnerId: string,
+  track: LearningJourneyTrackSpec
+): TrackProgress => ({
+  learnerId,
+  trackId: track.id,
+  progress: 0,
+  isCompleted: false,
+  xpEarned: 0,
+  steps: track.steps.map((step) => ({
+    id: step.id,
+    status: 'PENDING',
+    xpEarned: 0,
+    occurrences: 0,
+    masteryCount: 0,
+  })),
+  startedAt: undefined,
+  completedAt: undefined,
+  lastActivityAt: undefined,
+});

package/src/tracks.ts

@@ -0,0 +1,91 @@
+import type {
+  LearningJourneyStepSpec,
+  LearningJourneyTrackSpec,
+  StepAvailabilitySpec,
+  StepCompletionConditionSpec,
+} from '@contractspec/module.learning-journey/track-spec';
+import { crmLearningTracks } from '@contractspec/example.learning-journey-crm-onboarding/track';
+import { drillTracks } from '@contractspec/example.learning-journey-duo-drills/track';
+import { ambientCoachTracks } from '@contractspec/example.learning-journey-ambient-coach/track';
+import { questTracks } from '@contractspec/example.learning-journey-quest-challenges/track';
+import { platformLearningTracks } from '@contractspec/example.learning-journey-platform-tour/track';
+import { studioLearningTracks } from '@contractspec/example.learning-journey-studio-onboarding/track';
+
+export interface OnboardingStepDto {
+  id: string;
+  title: string;
+  description?: string;
+  completionEvent: string;
+  completionCondition?: StepCompletionConditionSpec;
+  xpReward?: number;
+  isRequired?: boolean;
+  canSkip?: boolean;
+  actionUrl?: string;
+  actionLabel?: string;
+  availability?: StepAvailabilitySpec;
+  metadata?: Record<string, unknown>;
+}
+
+export interface OnboardingTrackDto {
+  id: string;
+  name: string;
+  description?: string;
+  productId?: string;
+  targetUserSegment?: string;
+  targetRole?: string;
+  totalXp?: number;
+  streakRule?: LearningJourneyTrackSpec['streakRule'];
+  completionRewards?: LearningJourneyTrackSpec['completionRewards'];
+  steps: OnboardingStepDto[];
+  metadata?: Record<string, unknown>;
+}
+
+const mapStep = (step: LearningJourneyStepSpec): OnboardingStepDto => ({
+  id: step.id,
+  title: step.title,
+  description: step.description,
+  completionEvent: step.completion.eventName,
+  completionCondition: step.completion,
+  xpReward: step.xpReward,
+  isRequired: step.isRequired,
+  canSkip: step.canSkip,
+  actionUrl: step.actionUrl,
+  actionLabel: step.actionLabel,
+  availability: step.availability,
+  metadata: step.metadata,
+});
+
+export const mapTrackSpecToDto = (
+  track: LearningJourneyTrackSpec
+): OnboardingTrackDto => ({
+  id: track.id,
+  name: track.name,
+  description: track.description,
+  productId: track.productId,
+  targetUserSegment: track.targetUserSegment,
+  targetRole: track.targetRole,
+  totalXp: track.totalXp,
+  streakRule: track.streakRule,
+  completionRewards: track.completionRewards,
+  steps: track.steps.map(mapStep),
+  metadata: track.metadata,
+});
+
+export const learningJourneyTracks: LearningJourneyTrackSpec[] = [
+  ...studioLearningTracks,
+  ...platformLearningTracks,
+  ...crmLearningTracks,
+  ...drillTracks,
+  ...ambientCoachTracks,
+  ...questTracks,
+];
+
+export const onboardingTrackCatalog: OnboardingTrackDto[] =
+  learningJourneyTracks.map(mapTrackSpecToDto);
+
+export {
+  studioLearningTracks,
+  platformLearningTracks,
+  crmLearningTracks,
+  mapStep,
+};