@contractspec/lib.personalization 1.57.0 → 1.58.0

package/dist/node/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
+};

package/dist/node/docs/index.js

@@ -0,0 +1,271 @@
+// 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);

package/dist/node/docs/overlay-engine.docblock.js

@@ -0,0 +1,98 @@
+// src/docs/overlay-engine.docblock.ts
+import { registerDocBlocks } 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+  }
+];
+registerDocBlocks(personalization_overlay_engine_DocBlocks);
+export {
+  personalization_overlay_engine_DocBlocks
+};

package/dist/node/docs/workflow-composition.docblock.js

@@ -0,0 +1,83 @@
+// src/docs/workflow-composition.docblock.ts
+import { registerDocBlocks } 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+  }
+];
+registerDocBlocks(personalization_workflow_composition_DocBlocks);
+export {
+  personalization_workflow_composition_DocBlocks
+};