@contractspec/lib.personalization 1.56.1 → 1.58.0

package/dist/browser/index.js

@@ -0,0 +1,555 @@
+// 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`
+  }));
+}
+
+// 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";
+}
+
+// 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);
+
+// src/docs/overlay-engine.docblock.ts
+import { registerDocBlocks as registerDocBlocks2 } from "@contractspec/lib.contracts/docs";
+var personalization_overlay_engine_DocBlocks = [
+  {
+    id: "docs.personalization.overlay-engine",
+    title: "Overlay Engine",
+    summary: "`@contractspec/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/personalization/overlay-engine",
+    tags: ["personalization", "overlay-engine"],
+    body: `# Overlay Engine
+
+\`@contractspec/lib.overlay-engine\` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.
+
+## Key APIs
+
+- \`defineOverlay(spec)\` – helper to keep specs typed.
+- \`OverlayRegistry\` – register signed overlays and retrieve them per context.
+- \`OverlayEngine\` – apply overlays to renderable targets, emit audit events, and merge modifications deterministically.
+- \`signOverlay(spec, privateKey)\` – Ed25519/RSA-PSS signer.
+- \`verifyOverlaySignature(overlay)\` – verify public key signatures.
+- \`useOverlay(engine, params)\` – client hook that returns \`{ target, overlaysApplied }\`.
+
+## Scope Precedence
+
+Registrations are sorted by specificity:
+
+1. Tenant overlays
+2. Role overlays
+3. User overlays
+4. Device overlays
+
+Less specific overlays run first; more specific overlays override later.
+
+## Example
+
+\`\`\`ts
+const registry = new OverlayRegistry();
+const engine = new OverlayEngine({
+  registry,
+  audit: (event) => auditLogService.record(event),
+});
+
+const overlay = defineOverlay({
+  overlayId: 'acme-order-form',
+  version: '1.0.0',
+  appliesTo: {
+    capability: 'billing.createOrder',
+    tenantId: 'acme',
+  },
+  modifications: [
+    { type: 'hideField', field: 'internalNotes' },
+    { type: 'renameLabel', field: 'customerReference', newLabel: 'PO Number' },
+  ],
+});
+
+const signedOverlay = await signOverlay(overlay, privateKeyPem);
+registry.register(signedOverlay);
+
+const result = engine.apply({
+  target: { fields: baseFields },
+  capability: 'billing.createOrder',
+  tenantId: 'acme',
+  userId: 'manager-7',
+});
+\`\`\`
+
+\`result.target.fields\` now carries the hidden and renamed outputs ready for rendering.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+  }
+];
+registerDocBlocks2(personalization_overlay_engine_DocBlocks);
+
+// src/docs/workflow-composition.docblock.ts
+import { registerDocBlocks as registerDocBlocks3 } from "@contractspec/lib.contracts/docs";
+var personalization_workflow_composition_DocBlocks = [
+  {
+    id: "docs.personalization.workflow-composition",
+    title: "Workflow Composition",
+    summary: "`@contractspec/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/personalization/workflow-composition",
+    tags: ["personalization", "workflow-composition"],
+    body: `# Workflow Composition
+
+\`@contractspec/lib.workflow-composer\` composes base WorkflowSpecs with tenant/role/device-specific extensions.
+
+## Extensions
+
+\`\`\`ts
+import { WorkflowComposer } from '@contractspec/lib.workflow-composer';
+import { approvalStepTemplate } from '@contractspec/lib.workflow-composer/templates';
+
+const composer = new WorkflowComposer();
+
+composer.register({
+  workflow: 'billing.invoiceApproval',
+  tenantId: 'acme',
+  priority: 10,
+  customSteps: [
+    {
+      after: 'validate-invoice',
+      inject: approvalStepTemplate({
+        id: 'acme-legal-review',
+        label: 'Legal Review (ACME)',
+        description: 'Tenant-specific compliance step.',
+      }),
+      transitionTo: 'final-approval',
+    },
+  ],
+  hiddenSteps: ['internal-audit'],
+});
+\`\`\`
+
+## Compose
+
+\`\`\`ts
+const runtimeSpec = composer.compose({
+  base: BaseInvoiceWorkflow,
+  tenantId: 'acme',
+});
+
+workflowRunner.execute(runtimeSpec, ctx);
+\`\`\`
+
+The composer uses anchor references (\`after\`/\`before\`) to place injected steps and cleans up transitions when steps are hidden.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+  }
+];
+registerDocBlocks3(personalization_workflow_composition_DocBlocks);
+// src/store.ts
+class InMemoryBehaviorStore {
+  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;
+  });
+}
+
+// src/tracker.ts
+import { trace, metrics } from "@opentelemetry/api";
+var DEFAULT_BUFFER_SIZE = 25;
+
+class BehaviorTracker {
+  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();
+    }
+  }
+}
+var createBehaviorTracker = (options) => new BehaviorTracker(options);
+export {
+  insightsToWorkflowAdaptations,
+  insightsToOverlaySuggestion,
+  createBehaviorTracker,
+  InMemoryBehaviorStore,
+  BehaviorTracker,
+  BehaviorAnalyzer
+};

package/dist/browser/store.js

@@ -0,0 +1,75 @@
+// src/store.ts
+class InMemoryBehaviorStore {
+  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;
+  });
+}
+export {
+  InMemoryBehaviorStore
+};

package/dist/browser/tracker.js

@@ -0,0 +1,94 @@
+// src/tracker.ts
+import { trace, metrics } from "@opentelemetry/api";
+var DEFAULT_BUFFER_SIZE = 25;
+
+class BehaviorTracker {
+  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();
+    }
+  }
+}
+var createBehaviorTracker = (options) => new BehaviorTracker(options);
+export {
+  createBehaviorTracker,
+  BehaviorTracker
+};