@lssm/example.personalization 0.0.0-canary-20251213172311

package/.turbo/turbo-build.log

@@ -0,0 +1,18 @@
+$ bun build:bundle && bun build:types
+$ tsdown
+ℹ tsdown v0.17.0 powered by rolldown v1.0.0-beta.53
+ℹ config file: /home/runner/work/contractspec/contractspec/packages/examples/personalization/tsdown.config.js 
+ℹ entry: src/behavior-tracking.ts, src/example.ts, src/index.ts, src/overlay-customization.ts, src/workflow-extension.ts, src/docs/index.ts, src/docs/personalization.docblock.ts
+ℹ target: esnext
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ dist/docs/personalization.docblock.js  1.26 kB │ gzip: 0.63 kB
+ℹ dist/overlay-customization.js          1.09 kB │ gzip: 0.56 kB
+ℹ dist/workflow-extension.js             1.09 kB │ gzip: 0.56 kB
+ℹ dist/behavior-tracking.js              1.01 kB │ gzip: 0.52 kB
+ℹ dist/example.js                        0.58 kB │ gzip: 0.34 kB
+ℹ dist/index.js                          0.45 kB │ gzip: 0.21 kB
+ℹ dist/docs/index.js                     0.04 kB │ gzip: 0.06 kB
+ℹ 7 files, total: 5.51 kB
+✔ Build complete in 37ms
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @lssm/example.personalization
+
+## 0.0.0-canary-20251213172311
+
+### Patch Changes
+
+- Updated dependencies [3086383]
+  - @lssm/lib.workflow-composer@0.0.0-canary-20251213172311
+  - @lssm/lib.personalization@0.0.0-canary-20251213172311
+  - @lssm/lib.overlay-engine@0.0.0-canary-20251213172311
+  - @lssm/lib.contracts@0.0.0-canary-20251213172311
+  - @lssm/lib.logger@0.0.0-canary-20251213172311

package/dist/behavior-tracking.js

@@ -0,0 +1 @@
+import{createBehaviorTracker as e}from"@lssm/lib.personalization/tracker";import{InMemoryBehaviorStore as t}from"@lssm/lib.personalization/store";import{BehaviorAnalyzer as n}from"@lssm/lib.personalization/analyzer";import{LogLevel as r,Logger as i}from"@lssm/lib.logger";const a=new i({level:process.env.NODE_ENV===`production`?r.INFO:r.DEBUG,environment:process.env.NODE_ENV||`development`,enableColors:process.env.NODE_ENV!==`production`});async function o(){let r=new t,i=e({store:r,context:{tenantId:`acme`,userId:`user-123`}});i.trackFieldAccess({operation:`billing.createOrder`,field:`internalNotes`}),i.trackFieldAccess({operation:`billing.createOrder`,field:`customerReference`}),i.trackFeatureUsage({feature:`workflow-editor`,action:`opened`}),i.trackWorkflowStep({workflow:`invoice-approval`,step:`review`,status:`entered`}),await i.flush();let o=await new n(r).analyze({tenantId:`acme`,userId:`user-123`});a.info(`Behavior insights computed`,{insights:o})}export{o as runBehaviorTrackingExample};

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./personalization.docblock.js";

package/dist/docs/personalization.docblock.js

@@ -0,0 +1,9 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{id:`docs.examples.personalization`,title:`Personalization Patterns (example)`,summary:`Behavior tracking, overlay-driven UI tweaks, and tenant workflow extension patterns.`,kind:`reference`,visibility:`public`,route:`/docs/examples/personalization`,tags:[`personalization`,`overlays`,`workflows`,`example`],body:`## Includes
+- Behavior tracking + insight analysis.
+- Overlay customization (hide fields, rename labels).
+- Workflow extension (inject tenant-specific steps).
+
+## Guardrails
+- Keep tracking events structured and non-PII.
+- Keep overlays signed and scoped.
+- Keep workflow composition deterministic.`},{id:`docs.examples.personalization.usage`,title:`Personalization — Usage`,summary:`How to run the small examples and swap adapters.`,kind:`usage`,visibility:`public`,route:`/docs/examples/personalization/usage`,tags:[`personalization`,`usage`],body:"## Usage\n- Call `runBehaviorTrackingExample()` for insights.\n- Call `runOverlayCustomizationExample()` to apply overlays.\n- Call `composeTenantWorkflowExample()` and `logTenantWorkflowSteps()` to inspect steps.\n\n## Notes\n- Replace in-memory stores with app-layer storage.\n- Keep PII out of logs and markdown outputs."}]);

package/dist/example.js

@@ -0,0 +1 @@
+var e={id:`personalization`,title:`Personalization Patterns`,summary:`Small examples for behavior tracking, overlay-based UI customization, and tenant workflow extension.`,tags:[`personalization`,`overlays`,`behavior`,`workflows`],kind:`library`,visibility:`public`,docs:{rootDocId:`docs.examples.personalization`,usageDocId:`docs.examples.personalization.usage`},entrypoints:{packageName:`@lssm/example.personalization`,docs:`./docs`},surfaces:{templates:!0,sandbox:{enabled:!0,modes:[`markdown`,`specs`]},studio:{enabled:!0,installable:!0},mcp:{enabled:!0}}};export{e as default};

package/dist/index.js

@@ -0,0 +1 @@
+import{runBehaviorTrackingExample as e}from"./behavior-tracking.js";import t from"./example.js";import{runOverlayCustomizationExample as n}from"./overlay-customization.js";import{composeTenantWorkflowExample as r,logTenantWorkflowSteps as i}from"./workflow-extension.js";import"./docs/index.js";export{r as composeTenantWorkflowExample,t as example,i as logTenantWorkflowSteps,e as runBehaviorTrackingExample,n as runOverlayCustomizationExample};

package/dist/overlay-customization.js

@@ -0,0 +1 @@
+import{LogLevel as e,Logger as t}from"@lssm/lib.logger";import{defineOverlay as n}from"@lssm/lib.overlay-engine/spec";import{signOverlay as r}from"@lssm/lib.overlay-engine/signer";import{OverlayEngine as i,OverlayRegistry as a}from"@lssm/lib.overlay-engine";const o=new t({level:process.env.NODE_ENV===`production`?e.INFO:e.DEBUG,environment:process.env.NODE_ENV||`development`,enableColors:process.env.NODE_ENV!==`production`});async function s(){let e=new a({allowUnsigned:!0}),t=new i({registry:e}),s=await r(n({overlayId:`demo-overlay`,version:`1.0.0`,appliesTo:{capability:`billing.createOrder`,tenantId:`demo`},modifications:[{type:`hideField`,field:`internalNotes`},{type:`renameLabel`,field:`customerReference`,newLabel:`PO Number`}]}),process.env.PRIVATE_KEY_PEM??``);e.register(s);let c=t.apply({target:{fields:[{key:`customerReference`,label:`Customer Reference`,visible:!0},{key:`internalNotes`,label:`Internal Notes`,visible:!0}]},capability:`billing.createOrder`,tenantId:`demo`});o.info(`Overlay applied`,{fields:c.target.fields})}export{s as runOverlayCustomizationExample};

package/dist/workflow-extension.js

@@ -0,0 +1 @@
+import{LogLevel as e,Logger as t}from"@lssm/lib.logger";import{WorkflowComposer as n}from"@lssm/lib.workflow-composer";const r=new t({level:process.env.NODE_ENV===`production`?e.INFO:e.DEBUG,environment:process.env.NODE_ENV||`development`,enableColors:process.env.NODE_ENV!==`production`}),i={meta:{name:`billing.invoiceApproval`,version:1,title:`Invoice Approval`,owners:[],tags:[],description:``,domain:`billing`,stability:`stable`},definition:{steps:[{id:`validate-invoice`,type:`automation`,label:`Validate Invoice`},{id:`final-approval`,type:`human`,label:`Final Approval`}],transitions:[{from:`validate-invoice`,to:`final-approval`}]}};function a(){let e=new n;return e.register({workflow:`billing.invoiceApproval`,tenantId:`acme`,customSteps:[{after:`validate-invoice`,inject:{id:`acme-legal`,type:`human`,label:`ACME Legal Review`},transitionTo:`final-approval`}]}),e.compose({base:i,tenantId:`acme`})}function o(e){r.info(`Tenant workflow composed`,{workflow:e.meta.name,steps:e.definition.steps.map(e=>e.id)})}export{a as composeTenantWorkflowExample,o as logTenantWorkflowSteps};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lssm/example.personalization",
+  "version": "0.0.0-canary-20251213172311",
+  "description": "Personalization examples: behavior tracking, overlay customization, workflow extension.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./behavior-tracking": "./src/behavior-tracking.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/personalization.docblock": "./src/docs/personalization.docblock.ts",
+    "./example": "./src/example.ts",
+    "./overlay-customization": "./src/overlay-customization.ts",
+    "./workflow-extension": "./src/workflow-extension.ts",
+    "./*": "./*"
+  },
+  "scripts": {
+    "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 test"
+  },
+  "dependencies": {
+    "@lssm/lib.personalization": "workspace:*",
+    "@lssm/lib.overlay-engine": "workspace:*",
+    "@lssm/lib.workflow-composer": "workspace:*",
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.logger": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./behavior-tracking": "./dist/behavior-tracking.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/personalization.docblock": "./dist/docs/personalization.docblock.js",
+      "./example": "./dist/example.js",
+      "./overlay-customization": "./dist/overlay-customization.js",
+      "./workflow-extension": "./dist/workflow-extension.js",
+      "./*": "./*"
+    }
+  },
+  "module": "./dist/index.js"
+}

package/src/behavior-tracking.ts

@@ -0,0 +1,44 @@
+import { createBehaviorTracker } from '@lssm/lib.personalization/tracker';
+import { InMemoryBehaviorStore } from '@lssm/lib.personalization/store';
+import { BehaviorAnalyzer } from '@lssm/lib.personalization/analyzer';
+import { Logger, LogLevel } from '@lssm/lib.logger';
+
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+  environment: process.env.NODE_ENV || 'development',
+  enableColors: process.env.NODE_ENV !== 'production',
+});
+
+export async function runBehaviorTrackingExample(): Promise<void> {
+  const store = new InMemoryBehaviorStore();
+  const tracker = createBehaviorTracker({
+    store,
+    context: {
+      tenantId: 'acme',
+      userId: 'user-123',
+    },
+  });
+
+  tracker.trackFieldAccess({
+    operation: 'billing.createOrder',
+    field: 'internalNotes',
+  });
+  tracker.trackFieldAccess({
+    operation: 'billing.createOrder',
+    field: 'customerReference',
+  });
+  tracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });
+  tracker.trackWorkflowStep({
+    workflow: 'invoice-approval',
+    step: 'review',
+    status: 'entered',
+  });
+  await tracker.flush();
+
+  const analyzer = new BehaviorAnalyzer(store);
+  const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'user-123' });
+
+  logger.info('Behavior insights computed', { insights });
+}
+
+

package/src/docs/index.ts

@@ -0,0 +1,3 @@
+import './personalization.docblock';
+
+

package/src/docs/personalization.docblock.ts

@@ -0,0 +1,28 @@
+import type { DocBlock } from '@lssm/lib.contracts/docs';
+import { registerDocBlocks } from '@lssm/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.personalization',
+    title: 'Personalization Patterns (example)',
+    summary:
+      'Behavior tracking, overlay-driven UI tweaks, and tenant workflow extension patterns.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/personalization',
+    tags: ['personalization', 'overlays', 'workflows', 'example'],
+    body: `## Includes\n- Behavior tracking + insight analysis.\n- Overlay customization (hide fields, rename labels).\n- Workflow extension (inject tenant-specific steps).\n\n## Guardrails\n- Keep tracking events structured and non-PII.\n- Keep overlays signed and scoped.\n- Keep workflow composition deterministic.`,
+  },
+  {
+    id: 'docs.examples.personalization.usage',
+    title: 'Personalization — Usage',
+    summary: 'How to run the small examples and swap adapters.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/personalization/usage',
+    tags: ['personalization', 'usage'],
+    body: `## Usage\n- Call \`runBehaviorTrackingExample()\` for insights.\n- Call \`runOverlayCustomizationExample()\` to apply overlays.\n- Call \`composeTenantWorkflowExample()\` and \`logTenantWorkflowSteps()\` to inspect steps.\n\n## Notes\n- Replace in-memory stores with app-layer storage.\n- Keep PII out of logs and markdown outputs.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,27 @@
+const example = {
+  id: 'personalization',
+  title: 'Personalization Patterns',
+  summary:
+    'Small examples for behavior tracking, overlay-based UI customization, and tenant workflow extension.',
+  tags: ['personalization', 'overlays', 'behavior', 'workflows'],
+  kind: 'library',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.personalization',
+    usageDocId: 'docs.examples.personalization.usage',
+  },
+  entrypoints: {
+    packageName: '@lssm/example.personalization',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;
+
+

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './behavior-tracking';
+export * from './overlay-customization';
+export * from './workflow-extension';
+export { default as example } from './example';
+import './docs';
+
+

package/src/overlay-customization.ts

@@ -0,0 +1,50 @@
+import { defineOverlay } from '@lssm/lib.overlay-engine/spec';
+import { signOverlay } from '@lssm/lib.overlay-engine/signer';
+import { OverlayEngine, OverlayRegistry } from '@lssm/lib.overlay-engine';
+import { Logger, LogLevel } from '@lssm/lib.logger';
+
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+  environment: process.env.NODE_ENV || 'development',
+  enableColors: process.env.NODE_ENV !== 'production',
+});
+
+export async function runOverlayCustomizationExample(): Promise<void> {
+  const registry = new OverlayRegistry({ allowUnsigned: true });
+  const engine = new OverlayEngine({ registry });
+
+  const overlay = defineOverlay({
+    overlayId: 'demo-overlay',
+    version: '1.0.0',
+    appliesTo: {
+      capability: 'billing.createOrder',
+      tenantId: 'demo',
+    },
+    modifications: [
+      { type: 'hideField', field: 'internalNotes' },
+      {
+        type: 'renameLabel',
+        field: 'customerReference',
+        newLabel: 'PO Number',
+      },
+    ],
+  });
+
+  const signed = await signOverlay(overlay, process.env.PRIVATE_KEY_PEM ?? '');
+  registry.register(signed);
+
+  const result = engine.apply({
+    target: {
+      fields: [
+        { key: 'customerReference', label: 'Customer Reference', visible: true },
+        { key: 'internalNotes', label: 'Internal Notes', visible: true },
+      ],
+    },
+    capability: 'billing.createOrder',
+    tenantId: 'demo',
+  });
+
+  logger.info('Overlay applied', { fields: result.target.fields });
+}
+
+

package/src/workflow-extension.ts

@@ -0,0 +1,62 @@
+import type { WorkflowSpec } from '@lssm/lib.contracts/workflow/spec';
+import { WorkflowComposer } from '@lssm/lib.workflow-composer';
+import { Logger, LogLevel } from '@lssm/lib.logger';
+
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+  environment: process.env.NODE_ENV || 'development',
+  enableColors: process.env.NODE_ENV !== 'production',
+});
+
+const BaseWorkflow: WorkflowSpec = {
+  meta: {
+    name: 'billing.invoiceApproval',
+    version: 1,
+    title: 'Invoice Approval',
+    owners: [],
+    tags: [],
+    description: '',
+    domain: 'billing',
+    stability: 'stable',
+  },
+  definition: {
+    steps: [
+      { id: 'validate-invoice', type: 'automation', label: 'Validate Invoice' },
+      { id: 'final-approval', type: 'human', label: 'Final Approval' },
+    ],
+    transitions: [{ from: 'validate-invoice', to: 'final-approval' }],
+  },
+};
+
+export function composeTenantWorkflowExample(): WorkflowSpec {
+  const composer = new WorkflowComposer();
+  composer.register({
+    workflow: 'billing.invoiceApproval',
+    tenantId: 'acme',
+    customSteps: [
+      {
+        after: 'validate-invoice',
+        inject: {
+          id: 'acme-legal',
+          type: 'human',
+          label: 'ACME Legal Review',
+        },
+        transitionTo: 'final-approval',
+      },
+    ],
+  });
+
+  return composer.compose({
+    base: BaseWorkflow,
+    tenantId: 'acme',
+  });
+}
+
+export function logTenantWorkflowSteps(workflow: WorkflowSpec): void {
+  logger.info('Tenant workflow composed', {
+    workflow: workflow.meta.name,
+    steps: workflow.definition.steps.map((step) => step.id),
+  });
+}
+
+

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@lssm/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}
+
+