@contractspec/example.learning-journey-quest-challenges 0.0.0-canary-20260113162409

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@contractspec/example.learning-journey-quest-challenges",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Time-bound quest/challenge learning journey example.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/quest-challenges.docblock": "./dist/docs/quest-challenges.docblock.js",
+    "./example": "./dist/example.js",
+    "./track": "./dist/track.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/module.learning-journey": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./example": "./dist/example.js",
+      "./track": "./dist/track.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/quest-challenges.docblock": "./dist/docs/quest-challenges.docblock.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/learning-journey-quest-challenges"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './quest-challenges.docblock';

package/src/docs/quest-challenges.docblock.ts

@@ -0,0 +1,36 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const questDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.learning-journey.quest-challenges',
+    title: 'Learning Journey — Quest Challenges',
+    summary:
+      'Time-bound challenge pattern (7-day money reset) with day unlocks and event-driven completion.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/learning-journey/quest-challenges',
+    tags: ['learning', 'quest', 'challenge'],
+    body: `## Track
+- **Key**: \`money_reset_7day\`
+- **Duration**: 7 days, steps unlock day by day
+
+## Steps & Events
+- Day 1 \`day1_map_accounts\` → event \`accounts.mapped\`
+- Day 2 \`day2_categorize_transactions\` → event \`transactions.categorized\`
+- Day 3 \`day3_define_goals\` → event \`goals.created\`
+- Day 4 \`day4_setup_recurring_savings\` → event \`recurring_rule.created\`
+- Day 5 \`day5_review_subscriptions\` → event \`subscription.flagged_or_cancelled\`
+- Day 6 \`day6_plan_emergency\` → event \`emergency_plan.completed\`
+- Day 7 \`day7_review_commit\` → event \`quest.review.completed\`
+
+XP: 15 per day, completion bonus 30 if finished within duration. Optional recap via SRS after completion.
+
+## Usage
+- Exported via \`@contractspec/example.learning-journey-quest-challenges/track\`.
+- Step availability uses \`availability.unlockOnDay\` to gate days.
+- Registry progression handles event matching and XP application.`,
+  },
+];
+
+registerDocBlocks(questDocBlocks);

package/src/example.ts

@@ -0,0 +1,31 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'learning-journey-quest-challenges',
+    version: '1.0.0',
+    title: 'Learning Journey — Quest Challenges',
+    description:
+      'Quest/challenge pattern: multi-step goals with progress events, rewards, and streak hooks.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['learning', 'quests', 'challenges'],
+  },
+  docs: {
+    rootDocId: 'docs.learning-journey.quest-challenges',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-quest-challenges',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'markdown'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './track';
+export { default as example } from './example';
+import './docs';

package/src/track.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'bun:test';
+
+import { moneyResetQuestTrack } from './track';
+
+const addDays = (date: Date, days: number) =>
+  new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+
+type StepStatus = 'PENDING' | 'COMPLETED';
+
+describe('quest challenges track', () => {
+  it('unlocks by day and completes within window', () => {
+    const start = new Date('2024-01-01T09:00:00Z');
+    const events = [
+      { name: 'accounts.mapped', dayOffset: 0 },
+      { name: 'transactions.categorized', dayOffset: 1 },
+      { name: 'goals.created', dayOffset: 2 },
+      { name: 'recurring_rule.created', dayOffset: 3 },
+      { name: 'subscription.flagged_or_cancelled', dayOffset: 4 },
+      { name: 'emergency_plan.completed', dayOffset: 5 },
+      { name: 'quest.review.completed', dayOffset: 6 },
+    ];
+
+    const progress = moneyResetQuestTrack.steps.map((step) => ({
+      id: step.id,
+      status: 'PENDING' as StepStatus,
+    }));
+
+    events.forEach((evt) => {
+      const now = addDays(start, evt.dayOffset);
+      moneyResetQuestTrack.steps.forEach((spec, idx) => {
+        const step = progress[idx];
+        if (!step || step.status === 'COMPLETED') return;
+        const availableAt =
+          spec.availability?.unlockOnDay !== undefined
+            ? addDays(start, spec.availability.unlockOnDay - 1)
+            : start;
+        if (now < availableAt) return;
+        const within =
+          spec.completion.kind === 'time_window' &&
+          spec.completion.withinHoursOfStart !== undefined
+            ? (now.getTime() - start.getTime()) / (1000 * 60 * 60) <=
+              spec.completion.withinHoursOfStart
+            : true;
+        if (!within) return;
+        if (spec.completion.eventName !== evt.name) return;
+        step.status = 'COMPLETED';
+      });
+    });
+
+    expect(progress.every((s) => s.status === 'COMPLETED')).toBeTrue();
+  });
+});

package/src/track.ts

@@ -0,0 +1,76 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+const dayStep = (
+  id: string,
+  day: number,
+  eventName: string,
+  description: string
+): LearningJourneyTrackSpec['steps'][number] => ({
+  id,
+  title: `Day ${day}`,
+  description,
+  availability: { unlockOnDay: day },
+  completion: {
+    kind: 'time_window',
+    eventName,
+    withinHoursOfStart: (day + 1) * 24, // allow grace through next day
+  },
+  xpReward: 15,
+  metadata: { day },
+});
+
+export const moneyResetQuestTrack: LearningJourneyTrackSpec = {
+  id: 'money_reset_7day',
+  name: '7-day Money Reset',
+  description:
+    'Time-bound quest to reset personal finances over a focused week.',
+  targetUserSegment: 'money_user',
+  totalXp: 105,
+  completionRewards: { xpBonus: 30 },
+  steps: [
+    dayStep(
+      'day1_map_accounts',
+      1,
+      'accounts.mapped',
+      'Map bank and card accounts.'
+    ),
+    dayStep(
+      'day2_categorize_transactions',
+      2,
+      'transactions.categorized',
+      'Categorize recent transactions.'
+    ),
+    dayStep(
+      'day3_define_goals',
+      3,
+      'goals.created',
+      'Define at least one savings goal.'
+    ),
+    dayStep(
+      'day4_setup_recurring_savings',
+      4,
+      'recurring_rule.created',
+      'Set a recurring savings rule.'
+    ),
+    dayStep(
+      'day5_review_subscriptions',
+      5,
+      'subscription.flagged_or_cancelled',
+      'Review subscriptions and flag or cancel wasteful ones.'
+    ),
+    dayStep(
+      'day6_plan_emergency',
+      6,
+      'emergency_plan.completed',
+      'Draft an emergency plan and target buffer.'
+    ),
+    dayStep(
+      'day7_review_commit',
+      7,
+      'quest.review.completed',
+      'Review week outcomes and commit to the next month.'
+    ),
+  ],
+};
+
+export const questTracks: LearningJourneyTrackSpec[] = [moneyResetQuestTrack];

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}