@lssm/lib.personalization 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,16 @@
+# @lssm/lib.personalization
+
+Composable behavior tracking and personalization primitives for ContractSpec applications. The library provides trackers that capture feature usage, analyzers that transform raw events into adaptation hints, and adapters that feed personalized overlays or workflow tweaks.
+
+## Modules
+
+- `tracker` – lightweight tracker helpers that record field/feature/workflow usage.
+- `store` – store abstractions plus an in-memory implementation.
+- `analyzer` – stateless analyzers that convert usage data into insights.
+- `adapter` – bridges insights into OverlaySpecs or WorkflowComposer extensions.
+
+See `docs/tech/personalization/behavior-tracking.md` for full usage notes.
+
+
+
+

package/dist/adapter.d.ts

@@ -0,0 +1,21 @@
+import { BehaviorInsights } from "./types.js";
+import { OverlaySpec } from "@lssm/lib.overlay-engine";
+
+//#region src/adapter.d.ts
+interface OverlaySuggestionOptions {
+  overlayId: string;
+  tenantId: string;
+  capability: string;
+  userId?: string;
+  role?: string;
+  version?: string;
+}
+interface WorkflowAdaptation {
+  workflow: string;
+  step: string;
+  note: string;
+}
+declare function insightsToOverlaySuggestion(insights: BehaviorInsights, options: OverlaySuggestionOptions): OverlaySpec | null;
+declare function insightsToWorkflowAdaptations(insights: BehaviorInsights): WorkflowAdaptation[];
+//#endregion
+export { OverlaySuggestionOptions, WorkflowAdaptation, insightsToOverlaySuggestion, insightsToWorkflowAdaptations };

package/dist/adapter.js

@@ -0,0 +1 @@
+function e(e,t){let n=[];return e.suggestedHiddenFields.forEach(e=>{n.push({type:`hideField`,field:e,reason:`Automatically hidden because usage is near zero`})}),e.frequentlyUsedFields.length&&n.push({type:`reorderFields`,fields:e.frequentlyUsedFields}),n.length?{overlayId:t.overlayId,version:t.version??`1.0.0`,appliesTo:{tenantId:t.tenantId,capability:t.capability,userId:t.userId,role:t.role},modifications:n,metadata:{generatedAt:new Date().toISOString(),automated:!0}}:null}function t(e){return e.workflowBottlenecks.map(e=>({workflow:e.workflow,step:e.step,note:`High drop rate (${Math.round(e.dropRate*100)}%) detected`}))}export{e as insightsToOverlaySuggestion,t as insightsToWorkflowAdaptations};

package/dist/analyzer.d.ts

@@ -0,0 +1,22 @@
+import { BehaviorInsights } from "./types.js";
+import { BehaviorStore } from "./store.js";
+
+//#region src/analyzer.d.ts
+interface BehaviorAnalyzerOptions {
+  fieldInactivityThreshold?: number;
+  minSamples?: number;
+}
+interface AnalyzeParams {
+  tenantId: string;
+  userId?: string;
+  role?: string;
+  windowMs?: number;
+}
+declare class BehaviorAnalyzer {
+  private readonly store;
+  private readonly options;
+  constructor(store: BehaviorStore, options?: BehaviorAnalyzerOptions);
+  analyze(params: AnalyzeParams): Promise<BehaviorInsights>;
+}
+//#endregion
+export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions };

package/dist/analyzer.js

@@ -0,0 +1 @@
+var e=class{constructor(e,t={}){this.store=e,this.options=t}async analyze(e){let n={tenantId:e.tenantId,userId:e.userId,role:e.role};return e.windowMs&&(n.since=Date.now()-e.windowMs),t(await this.store.summarize(n),this.options)}};function t(e,t){let r=t.fieldInactivityThreshold??3,i=t.minSamples??10,a=[],o=[];for(let[t,n]of Object.entries(e.fieldCounts))n<=r&&a.push(t),n>=r*4&&o.push(t);let s=Object.entries(e.workflowStepCounts).flatMap(([e,t])=>{let n=Object.values(t).reduce((e,t)=>e+t,0);return!n||n<i?[]:Object.entries(t).filter(([,e])=>e/n<.4).map(([t,r])=>({workflow:e,step:t,dropRate:1-r/n}))}),c=n(e);return{unusedFields:a,suggestedHiddenFields:a.slice(0,5),frequentlyUsedFields:o.slice(0,10),workflowBottlenecks:s,layoutPreference:c}}function n(e){let t=Object.keys(e.fieldCounts).length;if(t)return t>=15?`table`:t>=8?`grid`:`form`}export{e as BehaviorAnalyzer};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorSummary, FeatureUsageEvent, FieldAccessEvent, WorkflowStepEvent } from "./types.js";
+import { BehaviorStore, InMemoryBehaviorStore } from "./store.js";
+import { BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, createBehaviorTracker } from "./tracker.js";
+import { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions } from "./analyzer.js";
+import { OverlaySuggestionOptions, WorkflowAdaptation, insightsToOverlaySuggestion, insightsToWorkflowAdaptations } from "./adapter.js";
+export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions, BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorStore, BehaviorSummary, BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, FeatureUsageEvent, FieldAccessEvent, InMemoryBehaviorStore, OverlaySuggestionOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, WorkflowAdaptation, WorkflowStepEvent, createBehaviorTracker, insightsToOverlaySuggestion, insightsToWorkflowAdaptations };

package/dist/index.js

@@ -0,0 +1 @@
+import{InMemoryBehaviorStore as e}from"./store.js";import{BehaviorTracker as t,createBehaviorTracker as n}from"./tracker.js";import{BehaviorAnalyzer as r}from"./analyzer.js";import{insightsToOverlaySuggestion as i,insightsToWorkflowAdaptations as a}from"./adapter.js";export{r as BehaviorAnalyzer,t as BehaviorTracker,e as InMemoryBehaviorStore,n as createBehaviorTracker,i as insightsToOverlaySuggestion,a as insightsToWorkflowAdaptations};

package/dist/store.d.ts

@@ -0,0 +1,20 @@
+import { BehaviorEvent, BehaviorQuery, BehaviorSummary } from "./types.js";
+
+//#region src/store.d.ts
+interface BehaviorStore {
+  record(event: BehaviorEvent): Promise<void> | void;
+  bulkRecord(events: BehaviorEvent[]): Promise<void> | void;
+  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;
+  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;
+  clear?(): Promise<void> | void;
+}
+declare class InMemoryBehaviorStore implements BehaviorStore {
+  private events;
+  record(event: BehaviorEvent): Promise<void>;
+  bulkRecord(events: BehaviorEvent[]): Promise<void>;
+  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;
+  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;
+  clear(): Promise<void>;
+}
+//#endregion
+export { BehaviorStore, InMemoryBehaviorStore };

package/dist/store.js

@@ -0,0 +1 @@
+var e=class{events=[];async record(e){this.events.push(e)}async bulkRecord(e){this.events.push(...e)}async query(e){return t(this.events,e)}async summarize(e){let t=await this.query(e),n={fieldCounts:{},featureCounts:{},workflowStepCounts:{},totalEvents:t.length};return t.forEach(e=>{switch(e.type){case`field_access`:n.fieldCounts[e.field]=(n.fieldCounts[e.field]??0)+1;break;case`feature_usage`:n.featureCounts[e.feature]=(n.featureCounts[e.feature]??0)+1;break;case`workflow_step`:{let t=n.workflowStepCounts[e.workflow]??={};t[e.step]=(t[e.step]??0)+1;break}default:break}}),n}async clear(){this.events=[]}};function t(e,t){return e.filter(e=>!(t.tenantId&&e.tenantId!==t.tenantId||t.userId&&e.userId!==t.userId||t.role&&e.role!==t.role||t.since&&e.timestamp<t.since||t.until&&e.timestamp>t.until||t.operation&&e.type===`field_access`&&e.operation!==t.operation||t.feature&&e.type===`feature_usage`&&e.feature!==t.feature||t.workflow&&e.type===`workflow_step`&&e.workflow!==t.workflow))}export{e as InMemoryBehaviorStore};

package/dist/tracker.d.ts

@@ -0,0 +1,52 @@
+import { BehaviorStore } from "./store.js";
+
+//#region src/tracker.d.ts
+interface BehaviorTrackerContext {
+  tenantId: string;
+  userId?: string;
+  role?: string;
+  device?: string;
+  metadata?: Record<string, unknown>;
+}
+interface BehaviorTrackerOptions {
+  store: BehaviorStore;
+  context: BehaviorTrackerContext;
+  tracerName?: string;
+  autoFlushIntervalMs?: number;
+  bufferSize?: number;
+}
+interface TrackFieldAccessInput {
+  operation: string;
+  field: string;
+  metadata?: Record<string, unknown>;
+}
+interface TrackFeatureUsageInput {
+  feature: string;
+  action: 'opened' | 'completed' | 'dismissed';
+  metadata?: Record<string, unknown>;
+}
+interface TrackWorkflowStepInput {
+  workflow: string;
+  step: string;
+  status: 'entered' | 'completed' | 'skipped' | 'errored';
+  metadata?: Record<string, unknown>;
+}
+declare class BehaviorTracker {
+  private readonly store;
+  private readonly context;
+  private readonly tracer;
+  private readonly counter;
+  private buffer;
+  private readonly bufferSize;
+  private flushTimer?;
+  constructor(options: BehaviorTrackerOptions);
+  trackFieldAccess(input: TrackFieldAccessInput): void;
+  trackFeatureUsage(input: TrackFeatureUsageInput): void;
+  trackWorkflowStep(input: TrackWorkflowStepInput): void;
+  flush(): Promise<void>;
+  dispose(): Promise<void>;
+  private enqueue;
+}
+declare const createBehaviorTracker: (options: BehaviorTrackerOptions) => BehaviorTracker;
+//#endregion
+export { BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, createBehaviorTracker };

package/dist/tracker.js

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

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+//#region src/types.d.ts
+type BehaviorEventType = 'field_access' | 'feature_usage' | 'workflow_step';
+interface BehaviorEventBase {
+  id?: string;
+  tenantId: string;
+  userId?: string;
+  role?: string;
+  device?: string;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+interface FieldAccessEvent extends BehaviorEventBase {
+  type: 'field_access';
+  operation: string;
+  field: string;
+}
+interface FeatureUsageEvent extends BehaviorEventBase {
+  type: 'feature_usage';
+  feature: string;
+  action: 'opened' | 'completed' | 'dismissed';
+}
+interface WorkflowStepEvent extends BehaviorEventBase {
+  type: 'workflow_step';
+  workflow: string;
+  step: string;
+  status: 'entered' | 'completed' | 'skipped' | 'errored';
+}
+type BehaviorEvent = FieldAccessEvent | FeatureUsageEvent | WorkflowStepEvent;
+interface BehaviorQuery {
+  tenantId?: string;
+  userId?: string;
+  role?: string;
+  feature?: string;
+  operation?: string;
+  workflow?: string;
+  since?: number;
+  until?: number;
+  limit?: number;
+}
+interface BehaviorSummary {
+  fieldCounts: Record<string, number>;
+  featureCounts: Record<string, number>;
+  workflowStepCounts: Record<string, Record<string, number>>;
+  totalEvents: number;
+}
+interface BehaviorInsights {
+  unusedFields: string[];
+  frequentlyUsedFields: string[];
+  suggestedHiddenFields: string[];
+  workflowBottlenecks: {
+    workflow: string;
+    step: string;
+    dropRate: number;
+  }[];
+  layoutPreference?: 'form' | 'grid' | 'list' | 'table';
+}
+//#endregion
+export { BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorSummary, FeatureUsageEvent, FieldAccessEvent, WorkflowStepEvent };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lssm/lib.personalization",
+  "version": "0.0.0-canary-20251206160926",
+  "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "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 run"
+  },
+  "dependencies": {
+    "@lssm/lib.bus": "workspace:*",
+    "@lssm/lib.overlay-engine": "workspace:*",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}