@lssm/module.learning-journey 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/contracts/onboarding.js

@@ -1 +1,404 @@
-import{l as e}from"../libs/schema/dist/ScalarTypeEnum.js";import{n as t}from"../libs/schema/dist/SchemaModel.js";import"../libs/schema/dist/index.js";import{n,t as r}from"../libs/contracts/dist/spec.js";import"../libs/contracts/dist/index.js";import{LEARNING_JOURNEY_OWNERS as i}from"./shared.js";import{SuccessOutput as a}from"./models.js";const o=t({name:`OnboardingStepCondition`,description:`Structured completion condition for onboarding steps.`,fields:{eventName:{type:e.String_unsecure(),isOptional:!1},eventVersion:{type:e.Int_unsecure(),isOptional:!0},sourceModule:{type:e.String_unsecure(),isOptional:!0},payloadFilter:{type:e.JSON(),isOptional:!0}}}),s=t({name:`OnboardingStep`,description:`Declarative onboarding step definition.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},trackId:{type:e.String_unsecure(),isOptional:!1},title:{type:e.String_unsecure(),isOptional:!1},description:{type:e.String_unsecure(),isOptional:!0},instructions:{type:e.String_unsecure(),isOptional:!0},helpUrl:{type:e.String_unsecure(),isOptional:!0},order:{type:e.Int_unsecure(),isOptional:!1},completionEvent:{type:e.String_unsecure(),isOptional:!1},completionCondition:{type:o,isOptional:!0},xpReward:{type:e.Int_unsecure(),isOptional:!0},isRequired:{type:e.Boolean(),isOptional:!0},canSkip:{type:e.Boolean(),isOptional:!0},actionUrl:{type:e.String_unsecure(),isOptional:!0},actionLabel:{type:e.String_unsecure(),isOptional:!0},metadata:{type:e.JSON(),isOptional:!0}}}),c=t({name:`OnboardingTrack`,description:`Onboarding track metadata and steps.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},productId:{type:e.String_unsecure(),isOptional:!0},name:{type:e.String_unsecure(),isOptional:!1},description:{type:e.String_unsecure(),isOptional:!0},targetUserSegment:{type:e.String_unsecure(),isOptional:!0},targetRole:{type:e.String_unsecure(),isOptional:!0},isActive:{type:e.Boolean(),isOptional:!0},isRequired:{type:e.Boolean(),isOptional:!0},canSkip:{type:e.Boolean(),isOptional:!0},totalXp:{type:e.Int_unsecure(),isOptional:!0},completionXpBonus:{type:e.Int_unsecure(),isOptional:!0},completionBadgeKey:{type:e.String_unsecure(),isOptional:!0},streakHoursWindow:{type:e.Int_unsecure(),isOptional:!0},streakBonusXp:{type:e.Int_unsecure(),isOptional:!0},metadata:{type:e.JSON(),isOptional:!0},steps:{type:s,isArray:!0,isOptional:!1}}}),l=t({name:`OnboardingStepProgress`,description:`Progress for a specific onboarding step.`,fields:{stepId:{type:e.String_unsecure(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},xpEarned:{type:e.Int_unsecure(),isOptional:!0},triggeringEvent:{type:e.String_unsecure(),isOptional:!0},eventPayload:{type:e.JSON(),isOptional:!0},completedAt:{type:e.DateTime(),isOptional:!0}}}),u=t({name:`OnboardingProgress`,description:`Aggregated progress for an onboarding track.`,fields:{learnerId:{type:e.String_unsecure(),isOptional:!0},trackId:{type:e.String_unsecure(),isOptional:!1},progress:{type:e.Int_unsecure(),isOptional:!1},isCompleted:{type:e.Boolean(),isOptional:!1},xpEarned:{type:e.Int_unsecure(),isOptional:!0},startedAt:{type:e.DateTime(),isOptional:!0},completedAt:{type:e.DateTime(),isOptional:!0},lastActivityAt:{type:e.DateTime(),isOptional:!0},steps:{type:l,isArray:!0,isOptional:!0}}}),d=t({name:`ListOnboardingTracksInput`,description:`Filters for listing onboarding tracks.`,fields:{learnerId:{type:e.String_unsecure(),isOptional:!0},productId:{type:e.String_unsecure(),isOptional:!0},trackIds:{type:e.String_unsecure(),isArray:!0,isOptional:!0},includeProgress:{type:e.Boolean(),isOptional:!0}}}),f=t({name:`ListOnboardingTracksOutput`,description:`Available onboarding tracks with optional progress.`,fields:{tracks:{type:c,isArray:!0,isOptional:!1},progress:{type:u,isArray:!0,isOptional:!0}}}),p=t({name:`GetOnboardingProgressInput`,description:`Input for fetching onboarding progress for a track.`,fields:{trackId:{type:e.String_unsecure(),isOptional:!1},learnerId:{type:e.String_unsecure(),isOptional:!0}}}),m=t({name:`RecordOnboardingEventInput`,description:`Record a domain event to advance onboarding progress via completion conditions.`,fields:{learnerId:{type:e.String_unsecure(),isOptional:!1},trackId:{type:e.String_unsecure(),isOptional:!0},eventName:{type:e.String_unsecure(),isOptional:!1},eventVersion:{type:e.Int_unsecure(),isOptional:!0},eventPayload:{type:e.JSON(),isOptional:!0},occurredAt:{type:e.DateTime(),isOptional:!0}}}),h=n({meta:{name:`learning.onboarding.listTracks`,version:1,stability:`stable`,owners:[...i],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:d,output:f},policy:{auth:`user`}}),g=n({meta:{name:`learning.onboarding.getProgress`,version:1,stability:`stable`,owners:[...i],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:p,output:u},policy:{auth:`user`}}),_=r({meta:{name:`learning.onboarding.recordEvent`,version:1,stability:`stable`,owners:[...i],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:m,output:a,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{g as GetOnboardingProgressContract,h as ListOnboardingTracksContract,u as OnboardingProgressModel,s as OnboardingStepModel,l as OnboardingStepProgressModel,c as OnboardingTrackModel,_ as RecordOnboardingEventContract};
+import { ScalarTypeEnum } from "../libs/schema/dist/ScalarTypeEnum.js";
+import { defineSchemaModel } from "../libs/schema/dist/SchemaModel.js";
+import "../libs/schema/dist/index.js";
+import { defineCommand, defineQuery } from "../libs/contracts/dist/spec.js";
+import "../libs/contracts/dist/index.js";
+import { LEARNING_JOURNEY_OWNERS } from "./shared.js";
+import { SuccessOutput } from "./models.js";
+
+//#region src/contracts/onboarding.ts
+const OnboardingStepConditionModel = defineSchemaModel({
+	name: "OnboardingStepCondition",
+	description: "Structured completion condition for onboarding steps.",
+	fields: {
+		eventName: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		eventVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		sourceModule: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		payloadFilter: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: true
+		}
+	}
+});
+const OnboardingStepModel = defineSchemaModel({
+	name: "OnboardingStep",
+	description: "Declarative onboarding step definition.",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		trackId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		title: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		description: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		instructions: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		helpUrl: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		order: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		completionEvent: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		completionCondition: {
+			type: OnboardingStepConditionModel,
+			isOptional: true
+		},
+		xpReward: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		isRequired: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		canSkip: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		actionUrl: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		actionLabel: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		metadata: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: true
+		}
+	}
+});
+const OnboardingTrackModel = defineSchemaModel({
+	name: "OnboardingTrack",
+	description: "Onboarding track metadata and steps.",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		productId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		name: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		description: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		targetUserSegment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		targetRole: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		isActive: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		isRequired: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		canSkip: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		totalXp: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		completionXpBonus: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		completionBadgeKey: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		streakHoursWindow: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		streakBonusXp: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		metadata: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: true
+		},
+		steps: {
+			type: OnboardingStepModel,
+			isArray: true,
+			isOptional: false
+		}
+	}
+});
+const OnboardingStepProgressModel = defineSchemaModel({
+	name: "OnboardingStepProgress",
+	description: "Progress for a specific onboarding step.",
+	fields: {
+		stepId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		xpEarned: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		triggeringEvent: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		eventPayload: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: true
+		},
+		completedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		}
+	}
+});
+const OnboardingProgressModel = defineSchemaModel({
+	name: "OnboardingProgress",
+	description: "Aggregated progress for an onboarding track.",
+	fields: {
+		learnerId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		trackId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		progress: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		isCompleted: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: false
+		},
+		xpEarned: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		startedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		completedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		lastActivityAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		steps: {
+			type: OnboardingStepProgressModel,
+			isArray: true,
+			isOptional: true
+		}
+	}
+});
+const ListOnboardingTracksInput = defineSchemaModel({
+	name: "ListOnboardingTracksInput",
+	description: "Filters for listing onboarding tracks.",
+	fields: {
+		learnerId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		productId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		trackIds: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true
+		},
+		includeProgress: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const ListOnboardingTracksOutput = defineSchemaModel({
+	name: "ListOnboardingTracksOutput",
+	description: "Available onboarding tracks with optional progress.",
+	fields: {
+		tracks: {
+			type: OnboardingTrackModel,
+			isArray: true,
+			isOptional: false
+		},
+		progress: {
+			type: OnboardingProgressModel,
+			isArray: true,
+			isOptional: true
+		}
+	}
+});
+const GetOnboardingProgressInput = defineSchemaModel({
+	name: "GetOnboardingProgressInput",
+	description: "Input for fetching onboarding progress for a track.",
+	fields: {
+		trackId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		learnerId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const RecordOnboardingEventInput = defineSchemaModel({
+	name: "RecordOnboardingEventInput",
+	description: "Record a domain event to advance onboarding progress via completion conditions.",
+	fields: {
+		learnerId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		trackId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		eventName: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		eventVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		eventPayload: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: true
+		},
+		occurredAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		}
+	}
+});
+const ListOnboardingTracksContract = defineQuery({
+	meta: {
+		name: "learning.onboarding.listTracks",
+		version: 1,
+		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" }
+});
+const GetOnboardingProgressContract = defineQuery({
+	meta: {
+		name: "learning.onboarding.getProgress",
+		version: 1,
+		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" }
+});
+const RecordOnboardingEventContract = defineCommand({
+	meta: {
+		name: "learning.onboarding.recordEvent",
+		version: 1,
+		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" }
+});
+
+//#endregion
+export { GetOnboardingProgressContract, ListOnboardingTracksContract, OnboardingProgressModel, OnboardingStepModel, OnboardingStepProgressModel, OnboardingTrackModel, RecordOnboardingEventContract };