@contractspec/lib.personalization 1.57.0 → 1.59.0

package/dist/adapter.d.ts

@@ -1,22 +1,18 @@
-import { BehaviorInsights } from "./types.js";
-import { OverlaySpec } from "@contractspec/lib.overlay-engine";
-
-//#region src/adapter.d.ts
-interface OverlaySuggestionOptions {
-  overlayId: string;
-  tenantId: string;
-  capability: string;
-  userId?: string;
-  role?: string;
-  version?: string;
+import type { OverlaySpec } from '@contractspec/lib.overlay-engine';
+import type { BehaviorInsights } from './types';
+export interface OverlaySuggestionOptions {
+    overlayId: string;
+    tenantId: string;
+    capability: string;
+    userId?: string;
+    role?: string;
+    version?: string;
 }
-interface WorkflowAdaptation {
-  workflow: string;
-  step: string;
-  note: string;
+export 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 };
+export declare function insightsToOverlaySuggestion(insights: BehaviorInsights, options: OverlaySuggestionOptions): OverlaySpec | null;
+export declare function insightsToWorkflowAdaptations(insights: BehaviorInsights): WorkflowAdaptation[];
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","names":[],"sources":["../src/adapter.ts"],"mappings":";;;;UAMiB,wBAAA;EACf,SAAA;EACA,QAAA;EACA,UAAA;EACA,MAAA;EACA,IAAA;EACA,OAAA;AAAA;AAAA,UAGe,kBAAA;EACf,QAAA;EACA,IAAA;EACA,IAAA;AAAA;AAAA,iBAGc,2BAAA,CACd,QAAA,EAAU,gBAAA,EACV,OAAA,EAAS,wBAAA,GACR,WAAA;AAAA,iBAuCa,6BAAA,CACd,QAAA,EAAU,gBAAA,GACT,kBAAA"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,wBAAwB,GAChC,WAAW,GAAG,IAAI,CAqCpB;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,gBAAgB,GACzB,kBAAkB,EAAE,CAMtB"}

package/dist/adapter.js

@@ -1,42 +1,47 @@
-//#region src/adapter.ts
+// @bun
+// src/adapter.ts
 function insightsToOverlaySuggestion(insights, options) {
-	const modifications = [];
-	insights.suggestedHiddenFields.forEach((field) => {
-		modifications.push({
-			type: "hideField",
-			field,
-			reason: "Automatically hidden because usage is near zero"
-		});
-	});
-	if (insights.frequentlyUsedFields.length) modifications.push({
-		type: "reorderFields",
-		fields: insights.frequentlyUsedFields
-	});
-	if (!modifications.length) return null;
-	return {
-		overlayId: options.overlayId,
-		version: options.version ?? "1.0.0",
-		appliesTo: {
-			tenantId: options.tenantId,
-			capability: options.capability,
-			userId: options.userId,
-			role: options.role
-		},
-		modifications,
-		metadata: {
-			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			automated: true
-		}
-	};
+  const modifications = [];
+  insights.suggestedHiddenFields.forEach((field) => {
+    modifications.push({
+      type: "hideField",
+      field,
+      reason: "Automatically hidden because usage is near zero"
+    });
+  });
+  if (insights.frequentlyUsedFields.length) {
+    modifications.push({
+      type: "reorderFields",
+      fields: insights.frequentlyUsedFields
+    });
+  }
+  if (!modifications.length) {
+    return null;
+  }
+  return {
+    overlayId: options.overlayId,
+    version: options.version ?? "1.0.0",
+    appliesTo: {
+      tenantId: options.tenantId,
+      capability: options.capability,
+      userId: options.userId,
+      role: options.role
+    },
+    modifications,
+    metadata: {
+      generatedAt: new Date().toISOString(),
+      automated: true
+    }
+  };
 }
 function insightsToWorkflowAdaptations(insights) {
-	return insights.workflowBottlenecks.map((bottleneck) => ({
-		workflow: bottleneck.workflow,
-		step: bottleneck.step,
-		note: `High drop rate (${Math.round(bottleneck.dropRate * 100)}%) detected`
-	}));
+  return insights.workflowBottlenecks.map((bottleneck) => ({
+    workflow: bottleneck.workflow,
+    step: bottleneck.step,
+    note: `High drop rate (${Math.round(bottleneck.dropRate * 100)}%) detected`
+  }));
 }
-
-//#endregion
-export { insightsToOverlaySuggestion, insightsToWorkflowAdaptations };
-//# sourceMappingURL=adapter.js.map
+export {
+  insightsToWorkflowAdaptations,
+  insightsToOverlaySuggestion
+};

package/dist/analyzer.d.ts

@@ -1,23 +1,19 @@
-import { BehaviorInsights } from "./types.js";
-import { BehaviorStore } from "./store.js";
-
-//#region src/analyzer.d.ts
-interface BehaviorAnalyzerOptions {
-  fieldInactivityThreshold?: number;
-  minSamples?: number;
+import type { BehaviorStore } from './store';
+import type { BehaviorInsights } from './types';
+export interface BehaviorAnalyzerOptions {
+    fieldInactivityThreshold?: number;
+    minSamples?: number;
 }
-interface AnalyzeParams {
-  tenantId: string;
-  userId?: string;
-  role?: string;
-  windowMs?: number;
+export 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>;
+export declare class BehaviorAnalyzer {
+    private readonly store;
+    private readonly options;
+    constructor(store: BehaviorStore, options?: BehaviorAnalyzerOptions);
+    analyze(params: AnalyzeParams): Promise<BehaviorInsights>;
 }
-//#endregion
-export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions };
 //# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","names":[],"sources":["../src/analyzer.ts"],"mappings":";;;;UAGiB,uBAAA;EACf,wBAAA;EACA,UAAA;AAAA;AAAA,UAGe,aAAA;EACf,QAAA;EACA,MAAA;EACA,IAAA;EACA,QAAA;AAAA;AAAA,cAKW,gBAAA;EAAA,iBAEQ,KAAA;EAAA,iBACA,OAAA;cADA,KAAA,EAAO,aAAA,EACP,OAAA,GAAS,uBAAA;EAGtB,OAAA,CAAQ,MAAA,EAAQ,aAAA,GAAgB,OAAA,CAAQ,gBAAA;AAAA"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAkC,MAAM,SAAS,CAAC;AAEhF,MAAM,WAAW,uBAAuB;IACtC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,uBAA4B;IAGlD,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAchE"}

package/dist/analyzer.js

@@ -1,55 +1,73 @@
-//#region src/analyzer.ts
-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);
-	}
-};
+// @bun
+// src/analyzer.ts
+var DEFAULT_THRESHOLD = 3;
+
+class BehaviorAnalyzer {
+  store;
+  options;
+  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;
+    }
+    const summary = await this.store.summarize(query);
+    return buildInsights(summary, 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
-	};
+  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 < 0.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";
+  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 };
-//# sourceMappingURL=analyzer.js.map
+export {
+  BehaviorAnalyzer
+};

package/dist/browser/adapter.js

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

package/dist/browser/analyzer.js

@@ -0,0 +1,72 @@
+// src/analyzer.ts
+var DEFAULT_THRESHOLD = 3;
+
+class BehaviorAnalyzer {
+  store;
+  options;
+  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;
+    }
+    const summary = await this.store.summarize(query);
+    return buildInsights(summary, 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 < 0.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";
+}
+export {
+  BehaviorAnalyzer
+};

package/dist/browser/docs/behavior-tracking.docblock.js

@@ -0,0 +1,97 @@
+// src/docs/behavior-tracking.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var personalization_behavior_tracking_DocBlocks = [
+  {
+    id: "docs.personalization.behavior-tracking",
+    title: "Behavior Tracking",
+    summary: "`@contractspec/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/personalization/behavior-tracking",
+    tags: ["personalization", "behavior-tracking"],
+    body: `# Behavior Tracking
+
+\`@contractspec/lib.personalization\` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.
+
+## Tracker
+
+\`\`\`ts
+import { createBehaviorTracker } from '@contractspec/lib.personalization';
+import { InMemoryBehaviorStore } from '@contractspec/lib.personalization/store';
+
+const tracker = createBehaviorTracker({
+  store: new InMemoryBehaviorStore(),
+  context: { tenantId: ctx.tenant.id, userId: ctx.identity.userId },
+  autoFlushIntervalMs: 5000,
+});
+
+tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'internalNotes' });
+tracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });
+tracker.trackWorkflowStep({ workflow: 'invoice-approval', step: 'review', status: 'entered' });
+\`\`\`
+
+All events are buffered and flushed either when the buffer hits 25 entries or when \`autoFlushIntervalMs\` elapses. Tracked metrics flow to OpenTelemetry via the meter/counter built into the tracker.
+
+## Analyzer
+
+\`\`\`ts
+import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
+
+const analyzer = new BehaviorAnalyzer(store, { fieldInactivityThreshold: 2 });
+const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'manager-42', windowMs: 7 * 24 * 60 * 60 * 1000 });
+
+/*
+{
+  unusedFields: ['internalNotes'],
+  suggestedHiddenFields: ['internalNotes'],
+  frequentlyUsedFields: ['customerReference', 'items'],
+  workflowBottlenecks: [{ workflow: 'invoice-approval', step: 'finance-review', dropRate: 0.6 }],
+  layoutPreference: 'table'
+}
+*/
+\`\`\`
+
+Use the analyzer output with the overlay adapter to generate suggestions automatically.
+
+## Adapter
+
+\`\`\`ts
+import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
+
+const overlay = insightsToOverlaySuggestion(insights, {
+  overlayId: 'acme-order-form',
+  tenantId: 'acme',
+  capability: 'billing.createOrder',
+});
+\`\`\`
+
+When the adapter returns an overlay spec, pass it to the overlay engine to register or sign it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+  }
+];
+registerDocBlocks(personalization_behavior_tracking_DocBlocks);
+export {
+  personalization_behavior_tracking_DocBlocks
+};