@lssm/example.personalization 0.0.0-canary-20251217060834 → 0.0.0-canary-20251217072406

package/dist/libs/overlay-engine/dist/merger.js

@@ -0,0 +1,106 @@
+//#region ../../libs/overlay-engine/dist/merger.js
+function applyOverlayModifications(target, overlays, options = {}) {
+	if (!overlays.length) return target;
+	const states = target.fields.map((field) => ({
+		key: field.key,
+		field: { ...field },
+		hidden: field.visible === false
+	}));
+	const fieldMap = new Map(states.map((state) => [state.key, state]));
+	let orderSequence = target.fields.map((field) => field.key);
+	const handleMissing = (field, overlayId) => {
+		if (options.strict) throw new Error(`Overlay "${overlayId}" referenced unknown field "${field}".`);
+	};
+	overlays.forEach((overlay) => {
+		overlay.modifications.forEach((modification) => {
+			switch (modification.type) {
+				case "hideField": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.hidden = true;
+					state.field.visible = false;
+					break;
+				}
+				case "renameLabel": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.label = modification.newLabel;
+					break;
+				}
+				case "setDefault": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.defaultValue = modification.value;
+					break;
+				}
+				case "addHelpText": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.helpText = modification.text;
+					break;
+				}
+				case "makeRequired": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.required = modification.required ?? true;
+					break;
+				}
+				case "reorderFields": {
+					const { filtered, missing } = normalizeOrderList(modification.fields, fieldMap);
+					if (missing.length && options.strict) missing.forEach((field) => handleMissing(field, overlay.overlayId));
+					orderSequence = applyReorder(orderSequence, filtered);
+					break;
+				}
+				default: break;
+			}
+		});
+	});
+	const visibleFields = [];
+	const seen = /* @__PURE__ */ new Set();
+	orderSequence.forEach((key) => {
+		const state = fieldMap.get(key);
+		if (!state || state.hidden) return;
+		seen.add(key);
+		visibleFields.push(state.field);
+	});
+	states.forEach((state) => {
+		if (state.hidden || seen.has(state.key)) return;
+		visibleFields.push(state.field);
+	});
+	visibleFields.forEach((field, index) => {
+		field.order = index;
+		field.visible = true;
+	});
+	return {
+		...target,
+		fields: visibleFields
+	};
+}
+function normalizeOrderList(fields, fieldMap) {
+	const filtered = [];
+	const missing = [];
+	const seen = /* @__PURE__ */ new Set();
+	fields.forEach((field) => {
+		if (!field?.trim()) return;
+		if (!fieldMap.has(field)) {
+			missing.push(field);
+			return;
+		}
+		if (seen.has(field)) return;
+		seen.add(field);
+		filtered.push(field);
+	});
+	return {
+		filtered,
+		missing
+	};
+}
+function applyReorder(sequence, orderedFields) {
+	if (!orderedFields.length) return sequence;
+	const orderedSet = new Set(orderedFields);
+	const remainder = sequence.filter((key) => !orderedSet.has(key));
+	return [...orderedFields, ...remainder];
+}
+
+//#endregion
+export { applyOverlayModifications };

package/dist/libs/overlay-engine/dist/registry.js

@@ -0,0 +1,106 @@
+import { defaultOverlayValidator } from "./validator.js";
+
+//#region ../../libs/overlay-engine/dist/registry.js
+const TARGET_KEYS = [
+	"capability",
+	"workflow",
+	"dataView",
+	"presentation",
+	"operation"
+];
+const SCOPE_WEIGHTS = {
+	tenantId: 8,
+	role: 4,
+	userId: 16,
+	device: 2,
+	tags: 1
+};
+var OverlayRegistry = class {
+	overlays = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	register(overlay, options) {
+		if (!options?.skipValidation) {
+			const result = (this.options.validator ?? defaultOverlayValidator)(overlay);
+			if (!result.valid) {
+				const reason = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+				throw new Error(`Overlay "${overlay.overlayId}" failed validation: ${reason}`);
+			}
+		}
+		const normalized = this.ensureSigned(overlay);
+		const key = this.getKey(normalized.overlayId, normalized.version);
+		const stored = {
+			overlay: normalized,
+			specificity: computeSpecificity(normalized.appliesTo),
+			registeredAt: Date.now()
+		};
+		this.overlays.set(key, stored);
+		return normalized;
+	}
+	unregister(overlayId, version) {
+		if (version) {
+			this.overlays.delete(this.getKey(overlayId, version));
+			return;
+		}
+		for (const key of Array.from(this.overlays.keys())) if (key.startsWith(`${overlayId}@`)) this.overlays.delete(key);
+	}
+	list() {
+		return Array.from(this.overlays.values()).map((entry) => entry.overlay);
+	}
+	get(overlayId, version) {
+		return this.overlays.get(this.getKey(overlayId, version))?.overlay;
+	}
+	forContext(query) {
+		return Array.from(this.overlays.values()).filter((entry) => matches(entry.overlay.appliesTo, query)).sort((a, b) => {
+			if (a.specificity !== b.specificity) return a.specificity - b.specificity;
+			return a.registeredAt - b.registeredAt;
+		}).map((entry) => entry.overlay);
+	}
+	clear() {
+		this.overlays.clear();
+	}
+	size() {
+		return this.overlays.size;
+	}
+	ensureSigned(input) {
+		if (isSignedOverlay(input)) {
+			if (!input.signature?.signature && !this.options.allowUnsigned) throw new Error(`Overlay "${input.overlayId}" is missing a signature.`);
+			return input;
+		}
+		if (!this.options.allowUnsigned) throw new Error(`Overlay "${input.overlayId}" must be signed before registration.`);
+		return input;
+	}
+	getKey(overlayId, version) {
+		return `${overlayId}@${version}`;
+	}
+};
+function isSignedOverlay(spec) {
+	return Boolean(spec.signature);
+}
+function computeSpecificity(appliesTo) {
+	let score = 0;
+	Object.keys(SCOPE_WEIGHTS).forEach((key) => {
+		if (key === "tags" ? Array.isArray(appliesTo.tags) && appliesTo.tags.length > 0 : Boolean(appliesTo[key])) score += SCOPE_WEIGHTS[key];
+	});
+	return score;
+}
+function matches(appliesTo, ctx) {
+	for (const key of TARGET_KEYS) {
+		const expected = appliesTo[key];
+		if (expected && expected !== ctx[key]) return false;
+	}
+	if (appliesTo.tenantId && appliesTo.tenantId !== ctx.tenantId) return false;
+	if (appliesTo.role && appliesTo.role !== ctx.role) return false;
+	if (appliesTo.userId && appliesTo.userId !== ctx.userId) return false;
+	if (appliesTo.device && appliesTo.device !== ctx.device) return false;
+	if (appliesTo.tags?.length) {
+		if (!ctx.tags?.length) return false;
+		const ctxTags = new Set(ctx.tags);
+		if (!appliesTo.tags.every((tag) => ctxTags.has(tag))) return false;
+	}
+	return true;
+}
+
+//#endregion
+export { OverlayRegistry };

package/dist/libs/overlay-engine/dist/runtime.js

@@ -0,0 +1,53 @@
+import { applyOverlayModifications } from "./merger.js";
+
+//#region ../../libs/overlay-engine/dist/runtime.js
+var OverlayEngine = class {
+	registry;
+	audit;
+	constructor(options) {
+		this.registry = options.registry;
+		this.audit = options.audit;
+	}
+	apply(params) {
+		const overlays = params.overlays ?? this.registry.forContext({
+			capability: params.capability,
+			workflow: params.workflow,
+			dataView: params.dataView,
+			presentation: params.presentation,
+			operation: params.operation,
+			tenantId: params.tenantId,
+			role: params.role,
+			userId: params.userId,
+			device: params.device,
+			tags: params.tags
+		});
+		const merged = applyOverlayModifications(params.target, overlays, { strict: params.strict });
+		const context = extractContext(params);
+		overlays.forEach((overlay) => {
+			this.audit?.({
+				overlay: {
+					overlayId: overlay.overlayId,
+					version: overlay.version
+				},
+				context,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		});
+		return {
+			target: merged,
+			overlaysApplied: overlays
+		};
+	}
+};
+function extractContext(params) {
+	return {
+		tenantId: params.tenantId,
+		role: params.role,
+		userId: params.userId,
+		device: params.device,
+		tags: params.tags
+	};
+}
+
+//#endregion
+export { OverlayEngine };

package/dist/libs/overlay-engine/dist/signer.js

@@ -0,0 +1,45 @@
+import stringify from "fast-json-stable-stringify";
+import { constants, createPrivateKey, createPublicKey, sign } from "crypto";
+
+//#region ../../libs/overlay-engine/dist/signer.js
+function signOverlay(spec, privateKey, options = {}) {
+	const algorithm = options.algorithm ?? "ed25519";
+	const keyObject = typeof privateKey === "string" || Buffer.isBuffer(privateKey) ? createPrivateKey(privateKey) : privateKey;
+	const payload = Buffer.from(canonicalizeOverlay(spec), "utf8");
+	let rawSignature;
+	if (algorithm === "ed25519") rawSignature = sign(null, payload, keyObject);
+	else if (algorithm === "rsa-pss-sha256") rawSignature = sign("sha256", payload, {
+		key: keyObject,
+		padding: constants.RSA_PKCS1_PSS_PADDING,
+		saltLength: 32
+	});
+	else throw new Error(`Unsupported overlay signature algorithm: ${algorithm}`);
+	const publicKey = options.publicKey ?? createPublicKey(keyObject).export({
+		format: "pem",
+		type: "spki"
+	}).toString();
+	return {
+		...spec,
+		signature: {
+			algorithm,
+			signature: rawSignature.toString("base64"),
+			publicKey,
+			keyId: options.keyId,
+			issuedAt: toIso(options.issuedAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
+			expiresAt: toIso(options.expiresAt),
+			metadata: options.metadata
+		}
+	};
+}
+function canonicalizeOverlay(spec) {
+	const { signature, ...rest } = spec;
+	return stringify(rest);
+}
+function toIso(value) {
+	if (!value) return;
+	if (typeof value === "string") return new Date(value).toISOString();
+	return value.toISOString();
+}
+
+//#endregion
+export { canonicalizeOverlay, signOverlay };

package/dist/libs/overlay-engine/dist/spec.js

@@ -0,0 +1,7 @@
+//#region ../../libs/overlay-engine/dist/spec.js
+function defineOverlay(spec) {
+	return spec;
+}
+
+//#endregion
+export { defineOverlay };

package/dist/libs/overlay-engine/dist/validator.js

@@ -0,0 +1,93 @@
+//#region ../../libs/overlay-engine/dist/validator.js
+const TARGET_KEYS = [
+	"capability",
+	"workflow",
+	"dataView",
+	"presentation",
+	"operation"
+];
+const defaultOverlayValidator = (spec) => validateOverlaySpec(spec);
+function validateOverlaySpec(spec) {
+	const issues = [];
+	if (!spec.overlayId?.trim()) issues.push({
+		code: "overlay.id",
+		message: "overlayId is required",
+		path: ["overlayId"]
+	});
+	if (!spec.version?.trim()) issues.push({
+		code: "overlay.version",
+		message: "version is required",
+		path: ["version"]
+	});
+	if (!TARGET_KEYS.some((key) => {
+		const value = spec.appliesTo?.[key];
+		return typeof value === "string" && value.trim().length > 0;
+	})) issues.push({
+		code: "overlay.target",
+		message: "Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",
+		path: ["appliesTo"]
+	});
+	if (!spec.modifications?.length) issues.push({
+		code: "overlay.modifications.empty",
+		message: "Overlay must include at least one modification.",
+		path: ["modifications"]
+	});
+	else spec.modifications.forEach((mod, idx) => {
+		validateModification(mod, ["modifications", String(idx)], issues);
+	});
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+}
+function validateModification(modification, path, issues) {
+	const push = (code, message, extraPath) => {
+		issues.push({
+			code,
+			message,
+			path: extraPath ? [...path, ...extraPath] : path
+		});
+	};
+	if (isFieldModification(modification)) {
+		if (!modification.field?.trim()) push("overlay.mod.field", "field is required for this modification", ["field"]);
+	}
+	switch (modification.type) {
+		case "renameLabel":
+			if (!modification.newLabel?.trim()) push("overlay.mod.renameLabel.newLabel", "newLabel is required", ["newLabel"]);
+			break;
+		case "reorderFields": {
+			if (!modification.fields?.length) push("overlay.mod.reorderFields.fields", "fields list cannot be empty", ["fields"]);
+			const seen = /* @__PURE__ */ new Set();
+			for (const field of modification.fields ?? []) {
+				if (!field?.trim()) {
+					push("overlay.mod.reorderFields.fields.blank", "fields entries must be non-empty");
+					break;
+				}
+				if (seen.has(field)) {
+					push("overlay.mod.reorderFields.fields.duplicate", `field "${field}" was listed multiple times`);
+					break;
+				}
+				seen.add(field);
+			}
+			break;
+		}
+		case "setDefault":
+			if (modification.value === void 0) push("overlay.mod.setDefault.value", "value is required", ["value"]);
+			break;
+		case "addHelpText":
+			if (!modification.text?.trim()) push("overlay.mod.addHelpText.text", "text is required", ["text"]);
+			break;
+		case "makeRequired":
+		case "hideField": break;
+		default: {
+			const exhaustive = modification;
+			throw new Error(`Unsupported overlay modification ${exhaustive?.type ?? "unknown"}`);
+		}
+	}
+}
+function isFieldModification(mod) {
+	return "field" in mod;
+}
+
+//#endregion
+export { defaultOverlayValidator, validateOverlaySpec };

package/dist/libs/personalization/dist/analyzer.js

@@ -0,0 +1,54 @@
+//#region ../../libs/personalization/dist/analyzer.js
+const DEFAULT_THRESHOLD = 3;
+var BehaviorAnalyzer = class {
+	constructor(store, options = {}) {
+		this.store = store;
+		this.options = options;
+	}
+	async analyze(params) {
+		const query = {
+			tenantId: params.tenantId,
+			userId: params.userId,
+			role: params.role
+		};
+		if (params.windowMs) query.since = Date.now() - params.windowMs;
+		return buildInsights(await this.store.summarize(query), this.options);
+	}
+};
+function buildInsights(summary, options) {
+	const threshold = options.fieldInactivityThreshold ?? DEFAULT_THRESHOLD;
+	const minSamples = options.minSamples ?? 10;
+	const ignoredFields = [];
+	const frequentlyUsedFields = [];
+	for (const [field, count] of Object.entries(summary.fieldCounts)) {
+		if (count <= threshold) ignoredFields.push(field);
+		if (count >= threshold * 4) frequentlyUsedFields.push(field);
+	}
+	const workflowBottlenecks = Object.entries(summary.workflowStepCounts).flatMap(([workflow, steps]) => {
+		const total = Object.values(steps).reduce((acc, value) => acc + value, 0);
+		if (!total || total < minSamples) return [];
+		return Object.entries(steps).filter(([, count]) => count / total < .4).map(([step, count]) => ({
+			workflow,
+			step,
+			dropRate: 1 - count / total
+		}));
+	});
+	const layoutPreference = detectLayout(summary);
+	return {
+		unusedFields: ignoredFields,
+		suggestedHiddenFields: ignoredFields.slice(0, 5),
+		frequentlyUsedFields: frequentlyUsedFields.slice(0, 10),
+		workflowBottlenecks,
+		layoutPreference
+	};
+}
+function detectLayout(summary) {
+	const fieldCount = Object.keys(summary.fieldCounts).length;
+	if (!fieldCount) return;
+	if (fieldCount >= 15) return "table";
+	if (fieldCount >= 8) return "grid";
+	return "form";
+}
+
+//#endregion
+export { BehaviorAnalyzer };

package/dist/libs/personalization/dist/store.js

@@ -0,0 +1,58 @@
+//#region ../../libs/personalization/dist/store.js
+var InMemoryBehaviorStore = class {
+	events = [];
+	async record(event) {
+		this.events.push(event);
+	}
+	async bulkRecord(events) {
+		this.events.push(...events);
+	}
+	async query(query) {
+		return filterEvents(this.events, query);
+	}
+	async summarize(query) {
+		const events = await this.query(query);
+		const summary = {
+			fieldCounts: {},
+			featureCounts: {},
+			workflowStepCounts: {},
+			totalEvents: events.length
+		};
+		events.forEach((event) => {
+			switch (event.type) {
+				case "field_access":
+					summary.fieldCounts[event.field] = (summary.fieldCounts[event.field] ?? 0) + 1;
+					break;
+				case "feature_usage":
+					summary.featureCounts[event.feature] = (summary.featureCounts[event.feature] ?? 0) + 1;
+					break;
+				case "workflow_step": {
+					const workflow = summary.workflowStepCounts[event.workflow] ??= {};
+					workflow[event.step] = (workflow[event.step] ?? 0) + 1;
+					break;
+				}
+				default: break;
+			}
+		});
+		return summary;
+	}
+	async clear() {
+		this.events = [];
+	}
+};
+function filterEvents(events, query) {
+	return events.filter((event) => {
+		if (query.tenantId && event.tenantId !== query.tenantId) return false;
+		if (query.userId && event.userId !== query.userId) return false;
+		if (query.role && event.role !== query.role) return false;
+		if (query.since && event.timestamp < query.since) return false;
+		if (query.until && event.timestamp > query.until) return false;
+		if (query.operation && event.type === "field_access" && event.operation !== query.operation) return false;
+		if (query.feature && event.type === "feature_usage" && event.feature !== query.feature) return false;
+		if (query.workflow && event.type === "workflow_step" && event.workflow !== query.workflow) return false;
+		return true;
+	});
+}
+
+//#endregion
+export { InMemoryBehaviorStore };

package/dist/libs/personalization/dist/tracker.js

@@ -0,0 +1,92 @@
+import { metrics, trace } from "@opentelemetry/api";
+
+//#region ../../libs/personalization/dist/tracker.js
+const DEFAULT_BUFFER_SIZE = 25;
+var BehaviorTracker = class {
+	store;
+	context;
+	tracer = trace.getTracer("lssm.personalization", "1.0.0");
+	counter = metrics.getMeter("lssm.personalization", "1.0.0").createCounter("lssm.personalization.events", { description: "Behavior events tracked for personalization" });
+	buffer = [];
+	bufferSize;
+	flushTimer;
+	constructor(options) {
+		this.store = options.store;
+		this.context = options.context;
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+		if (options.autoFlushIntervalMs) this.flushTimer = setInterval(() => {
+			this.flush();
+		}, options.autoFlushIntervalMs);
+	}
+	trackFieldAccess(input) {
+		const event = {
+			type: "field_access",
+			operation: input.operation,
+			field: input.field,
+			timestamp: Date.now(),
+			...this.context,
+			metadata: {
+				...this.context.metadata,
+				...input.metadata
+			}
+		};
+		this.enqueue(event);
+	}
+	trackFeatureUsage(input) {
+		const event = {
+			type: "feature_usage",
+			feature: input.feature,
+			action: input.action,
+			timestamp: Date.now(),
+			...this.context,
+			metadata: {
+				...this.context.metadata,
+				...input.metadata
+			}
+		};
+		this.enqueue(event);
+	}
+	trackWorkflowStep(input) {
+		const event = {
+			type: "workflow_step",
+			workflow: input.workflow,
+			step: input.step,
+			status: input.status,
+			timestamp: Date.now(),
+			...this.context,
+			metadata: {
+				...this.context.metadata,
+				...input.metadata
+			}
+		};
+		this.enqueue(event);
+	}
+	async flush() {
+		if (!this.buffer.length) return;
+		const events = this.buffer;
+		this.buffer = [];
+		await this.store.bulkRecord(events);
+	}
+	async dispose() {
+		if (this.flushTimer) clearInterval(this.flushTimer);
+		await this.flush();
+	}
+	enqueue(event) {
+		this.buffer.push(event);
+		this.counter.add(1, {
+			tenantId: this.context.tenantId,
+			type: event.type
+		});
+		this.tracer.startActiveSpan(`personalization.${event.type}`, (span) => {
+			span.setAttribute("tenant.id", this.context.tenantId);
+			if (this.context.userId) span.setAttribute("user.id", this.context.userId);
+			span.setAttribute("personalization.event_type", event.type);
+			span.end();
+		});
+		if (this.buffer.length >= this.bufferSize) this.flush();
+	}
+};
+const createBehaviorTracker = (options) => new BehaviorTracker(options);
+
+//#endregion
+export { createBehaviorTracker };

package/dist/libs/workflow-composer/dist/composer.js

@@ -0,0 +1,28 @@
+import { applyWorkflowExtension } from "./injector.js";
+
+//#region ../../libs/workflow-composer/dist/composer.js
+var WorkflowComposer = class {
+	extensions = [];
+	register(extension) {
+		this.extensions.push(extension);
+		return this;
+	}
+	registerMany(extensions) {
+		extensions.forEach((extension) => this.register(extension));
+		return this;
+	}
+	compose(params) {
+		return this.extensions.filter((extension) => matches(params, extension)).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0)).reduce((acc, extension) => applyWorkflowExtension(acc, extension), params.base);
+	}
+};
+function matches(params, extension) {
+	if (extension.workflow !== params.base.meta.name) return false;
+	if (extension.baseVersion && extension.baseVersion !== params.base.meta.version) return false;
+	if (extension.tenantId && extension.tenantId !== params.tenantId) return false;
+	if (extension.role && extension.role !== params.role) return false;
+	if (extension.device && extension.device !== params.device) return false;
+	return true;
+}
+
+//#endregion
+export { WorkflowComposer };