@contractspec/example.learning-journey-registry 1.57.0 → 1.59.0

package/dist/node/index.js

@@ -0,0 +1,540 @@
+// src/tracks.ts
+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";
+var mapStep = (step) => ({
+  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
+});
+var mapTrackSpecToDto = (track) => ({
+  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
+});
+var learningJourneyTracks = [
+  ...studioLearningTracks,
+  ...platformLearningTracks,
+  ...crmLearningTracks,
+  ...drillTracks,
+  ...ambientCoachTracks,
+  ...questTracks
+];
+var onboardingTrackCatalog = learningJourneyTracks.map(mapTrackSpecToDto);
+// src/progress-store.ts
+var progressStore = new Map;
+var getTrackResolver = (tracks) => (trackId) => tracks.find((t) => t.id === trackId);
+var getLearnerTracks = (learnerId) => {
+  const existing = progressStore.get(learnerId);
+  if (existing)
+    return existing;
+  const map = new Map;
+  progressStore.set(learnerId, map);
+  return map;
+};
+var initProgress = (learnerId, track) => ({
+  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
+});
+
+// src/api.ts
+var getTrack = getTrackResolver(learningJourneyTracks);
+var matchesFilter = (filter, payload) => {
+  if (!filter)
+    return true;
+  if (!payload)
+    return false;
+  return Object.entries(filter).every(([key, value]) => payload[key] === value);
+};
+var matchesBaseEvent = (condition, event) => {
+  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);
+};
+var matchesCondition = (condition, event, step, trackStartedAt) => {
+  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;
+    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) };
+};
+var getAvailability = (availability, startedAt) => {
+  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 };
+};
+var computeProgressPercent = (steps) => {
+  const total = steps.length || 1;
+  const done = steps.filter((s) => s.status === "COMPLETED").length;
+  return Math.round(done / total * 100);
+};
+var applyTrackCompletionBonuses = (track, progress) => {
+  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
+  };
+};
+var listTracks = (learnerId) => {
+  const progressMap = learnerId ? getLearnerTracks(learnerId) : undefined;
+  const progress = learnerId && progressMap ? Array.from(progressMap.values()) : [];
+  return {
+    tracks: learningJourneyTracks,
+    progress
+  };
+};
+var getProgress = (trackId, learnerId) => {
+  const track = getTrack(trackId);
+  if (!track)
+    return;
+  const map = getLearnerTracks(learnerId);
+  const existing = map.get(trackId) ?? initProgress(learnerId, track);
+  map.set(trackId, existing);
+  return existing;
+};
+var recordEvent = (event) => {
+  const targets = event.trackId !== undefined ? learningJourneyTracks.filter((t) => t.id === event.trackId) : learningJourneyTracks;
+  const updated = [];
+  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 = 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) {
+        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 = {
+      ...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;
+};
+
+// src/docs/learning-journey-registry.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var registryDocBlocks = [
+  {
+    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);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+
+// src/presentations/index.ts
+import {
+  definePresentation,
+  StabilityEnum
+} from "@contractspec/lib.contracts";
+var baseMeta = {
+  domain: "learning-journey",
+  title: "Learning Journey",
+  owners: ["@learning-team"],
+  tags: ["learning", "journey", "onboarding"],
+  stability: StabilityEnum.Experimental,
+  goal: "Progress through learning tracks",
+  context: "Learning journey section"
+};
+var 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"]
+});
+var 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"]
+});
+var 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"]
+});
+var learningJourneyPresentations = [
+  LearningTrackListPresentation,
+  LearningTrackDetailPresentation,
+  LearningTrackProgressWidgetPresentation
+];
+
+// src/learning-journey-registry.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var 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"
+  },
+  operations: [],
+  events: [],
+  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" }
+  ],
+  opToPresentation: [],
+  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"]
+    }
+  ],
+  capabilities: {
+    requires: [{ key: "identity", version: "1.0.0" }]
+  }
+});
+
+// src/ui/LearningMiniApp.tsx
+import { useMemo } from "react";
+import { GamifiedMiniApp } from "@contractspec/example.learning-journey-ui-gamified";
+import { OnboardingMiniApp } from "@contractspec/example.learning-journey-ui-onboarding";
+import { CoachingMiniApp } from "@contractspec/example.learning-journey-ui-coaching";
+import { jsxDEV } from "react/jsx-dev-runtime";
+"use client";
+var TEMPLATE_TO_TRACK = {
+  "learning-journey-duo-drills": "drills_language_basics",
+  "learning-journey-quest-challenges": "money_reset_7day",
+  "learning-journey-studio-onboarding": "studio_getting_started",
+  "learning-journey-platform-tour": "platform_tour",
+  "learning-journey-ambient-coach": "money_ambient_coach",
+  "learning-journey-crm-onboarding": "crm_first_win"
+};
+var TEMPLATE_TO_APP_TYPE = {
+  "learning-journey-duo-drills": "gamified",
+  "learning-journey-quest-challenges": "gamified",
+  "learning-journey-studio-onboarding": "onboarding",
+  "learning-journey-platform-tour": "onboarding",
+  "learning-journey-ambient-coach": "coaching",
+  "learning-journey-crm-onboarding": "coaching"
+};
+function LearningMiniApp({
+  templateId,
+  initialView = "overview",
+  onViewChange
+}) {
+  const track = useMemo(() => {
+    const trackId = TEMPLATE_TO_TRACK[templateId];
+    if (!trackId)
+      return null;
+    return learningJourneyTracks.find((t) => t.id === trackId);
+  }, [templateId]);
+  const appType = TEMPLATE_TO_APP_TYPE[templateId];
+  if (!track) {
+    return /* @__PURE__ */ jsxDEV("div", {
+      className: "rounded-lg border border-amber-500/50 bg-amber-500/10 p-6 text-center",
+      children: /* @__PURE__ */ jsxDEV("p", {
+        className: "text-amber-500",
+        children: [
+          "Unknown learning template: ",
+          templateId
+        ]
+      }, undefined, true, undefined, this)
+    }, undefined, false, undefined, this);
+  }
+  switch (appType) {
+    case "gamified":
+      return /* @__PURE__ */ jsxDEV(GamifiedMiniApp, {
+        track,
+        initialView,
+        onViewChange
+      }, undefined, false, undefined, this);
+    case "onboarding":
+      return /* @__PURE__ */ jsxDEV(OnboardingMiniApp, {
+        track,
+        initialView,
+        onViewChange
+      }, undefined, false, undefined, this);
+    case "coaching":
+      return /* @__PURE__ */ jsxDEV(CoachingMiniApp, {
+        track,
+        initialView,
+        onViewChange
+      }, undefined, false, undefined, this);
+    default:
+      return /* @__PURE__ */ jsxDEV("div", {
+        className: "rounded-lg border border-red-500/50 bg-red-500/10 p-6 text-center",
+        children: /* @__PURE__ */ jsxDEV("p", {
+          className: "text-red-500",
+          children: [
+            "Unknown app type for template: ",
+            templateId
+          ]
+        }, undefined, true, undefined, this)
+      }, undefined, false, undefined, this);
+  }
+}
+function isLearningTemplate(templateId) {
+  return templateId in TEMPLATE_TO_TRACK;
+}
+function getLearningTemplateIds() {
+  return Object.keys(TEMPLATE_TO_TRACK);
+}
+export {
+  studioLearningTracks,
+  recordEvent,
+  platformLearningTracks,
+  onboardingTrackCatalog,
+  mapTrackSpecToDto,
+  mapStep,
+  listTracks,
+  learningJourneyTracks,
+  learningJourneyPresentations,
+  isLearningTemplate,
+  getProgress,
+  getLearningTemplateIds,
+  example_default as example,
+  crmLearningTracks,
+  LearningTrackProgressWidgetPresentation,
+  LearningTrackListPresentation,
+  LearningTrackDetailPresentation,
+  LearningMiniApp,
+  LearningJourneyRegistryFeature
+};

package/dist/node/learning-journey-registry.feature.js

@@ -0,0 +1,45 @@
+// src/learning-journey-registry.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var 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"
+  },
+  operations: [],
+  events: [],
+  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" }
+  ],
+  opToPresentation: [],
+  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"]
+    }
+  ],
+  capabilities: {
+    requires: [{ key: "identity", version: "1.0.0" }]
+  }
+});
+export {
+  LearningJourneyRegistryFeature
+};

package/dist/node/presentations/index.js

@@ -0,0 +1,67 @@
+// src/presentations/index.ts
+import {
+  definePresentation,
+  StabilityEnum
+} from "@contractspec/lib.contracts";
+var baseMeta = {
+  domain: "learning-journey",
+  title: "Learning Journey",
+  owners: ["@learning-team"],
+  tags: ["learning", "journey", "onboarding"],
+  stability: StabilityEnum.Experimental,
+  goal: "Progress through learning tracks",
+  context: "Learning journey section"
+};
+var 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"]
+});
+var 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"]
+});
+var 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"]
+});
+var learningJourneyPresentations = [
+  LearningTrackListPresentation,
+  LearningTrackDetailPresentation,
+  LearningTrackProgressWidgetPresentation
+];
+export {
+  learningJourneyPresentations,
+  LearningTrackProgressWidgetPresentation,
+  LearningTrackListPresentation,
+  LearningTrackDetailPresentation
+};

package/dist/node/progress-store.js

@@ -0,0 +1,34 @@
+// src/progress-store.ts
+var progressStore = new Map;
+var getTrackResolver = (tracks) => (trackId) => tracks.find((t) => t.id === trackId);
+var getLearnerTracks = (learnerId) => {
+  const existing = progressStore.get(learnerId);
+  if (existing)
+    return existing;
+  const map = new Map;
+  progressStore.set(learnerId, map);
+  return map;
+};
+var initProgress = (learnerId, track) => ({
+  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
+});
+export {
+  progressStore,
+  initProgress,
+  getTrackResolver,
+  getLearnerTracks
+};