@contractspec/example.personalization 0.0.0-canary-20260113170453

package/dist/workflow-extension.js

@@ -0,0 +1,67 @@
+import { LogLevel, Logger } from "@contractspec/lib.logger";
+import { StabilityEnum } from "@contractspec/lib.contracts";
+import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
+
+//#region src/workflow-extension.ts
+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 = {
+	meta: {
+		key: "billing.invoiceApproval",
+		version: "1.0.0",
+		title: "Invoice Approval",
+		owners: [],
+		tags: [],
+		description: "",
+		domain: "billing",
+		stability: StabilityEnum.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 composeTenantWorkflowExample() {
+	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"
+	});
+}
+function logTenantWorkflowSteps(workflow) {
+	logger.info("Tenant workflow composed", {
+		workflow: workflow.meta.key,
+		steps: workflow.definition.steps.map((step) => step.id)
+	});
+}
+
+//#endregion
+export { composeTenantWorkflowExample, logTenantWorkflowSteps };
+//# sourceMappingURL=workflow-extension.js.map

package/dist/workflow-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-extension.js","names":[],"sources":["../src/workflow-extension.ts"],"sourcesContent":["import { StabilityEnum } from '@contractspec/lib.contracts';\nimport type { WorkflowSpec } from '@contractspec/lib.contracts/workflow/spec';\nimport { WorkflowComposer } from '@contractspec/lib.workflow-composer';\nimport { Logger, LogLevel } from '@contractspec/lib.logger';\n\nconst logger = new Logger({\n  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,\n  environment:\n    (process.env.NODE_ENV as 'production' | 'development' | 'test') ||\n    'development',\n  enableColors: process.env.NODE_ENV !== 'production',\n});\n\nconst BaseWorkflow: WorkflowSpec = {\n  meta: {\n    key: 'billing.invoiceApproval',\n    version: '1.0.0',\n    title: 'Invoice Approval',\n    owners: [],\n    tags: [],\n    description: '',\n    domain: 'billing',\n    stability: StabilityEnum.Stable,\n  },\n  definition: {\n    steps: [\n      { id: 'validate-invoice', type: 'automation', label: 'Validate Invoice' },\n      { id: 'final-approval', type: 'human', label: 'Final Approval' },\n    ],\n    transitions: [{ from: 'validate-invoice', to: 'final-approval' }],\n  },\n};\n\nexport function composeTenantWorkflowExample(): WorkflowSpec {\n  const composer = new WorkflowComposer();\n  composer.register({\n    workflow: 'billing.invoiceApproval',\n    tenantId: 'acme',\n    customSteps: [\n      {\n        after: 'validate-invoice',\n        inject: {\n          id: 'acme-legal',\n          type: 'human',\n          label: 'ACME Legal Review',\n        },\n        transitionTo: 'final-approval',\n      },\n    ],\n  });\n\n  return composer.compose({\n    base: BaseWorkflow,\n    tenantId: 'acme',\n  });\n}\n\nexport function logTenantWorkflowSteps(workflow: WorkflowSpec): void {\n  logger.info('Tenant workflow composed', {\n    workflow: workflow.meta.key,\n    steps: workflow.definition.steps.map((step) => step.id),\n  });\n}\n"],"mappings":";;;;;AAKA,MAAM,SAAS,IAAI,OAAO;CACxB,OAAO,QAAQ,IAAI,aAAa,eAAe,SAAS,OAAO,SAAS;CACxE,aACG,QAAQ,IAAI,YACb;CACF,cAAc,QAAQ,IAAI,aAAa;CACxC,CAAC;AAEF,MAAM,eAA6B;CACjC,MAAM;EACJ,KAAK;EACL,SAAS;EACT,OAAO;EACP,QAAQ,EAAE;EACV,MAAM,EAAE;EACR,aAAa;EACb,QAAQ;EACR,WAAW,cAAc;EAC1B;CACD,YAAY;EACV,OAAO,CACL;GAAE,IAAI;GAAoB,MAAM;GAAc,OAAO;GAAoB,EACzE;GAAE,IAAI;GAAkB,MAAM;GAAS,OAAO;GAAkB,CACjE;EACD,aAAa,CAAC;GAAE,MAAM;GAAoB,IAAI;GAAkB,CAAC;EAClE;CACF;AAED,SAAgB,+BAA6C;CAC3D,MAAM,WAAW,IAAI,kBAAkB;AACvC,UAAS,SAAS;EAChB,UAAU;EACV,UAAU;EACV,aAAa,CACX;GACE,OAAO;GACP,QAAQ;IACN,IAAI;IACJ,MAAM;IACN,OAAO;IACR;GACD,cAAc;GACf,CACF;EACF,CAAC;AAEF,QAAO,SAAS,QAAQ;EACtB,MAAM;EACN,UAAU;EACX,CAAC;;AAGJ,SAAgB,uBAAuB,UAA8B;AACnE,QAAO,KAAK,4BAA4B;EACtC,UAAU,SAAS,KAAK;EACxB,OAAO,SAAS,WAAW,MAAM,KAAK,SAAS,KAAK,GAAG;EACxD,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@contractspec/example.personalization",
+  "version": "0.0.0-canary-20260113170453",
+  "description": "Personalization examples: behavior tracking, overlay customization, workflow extension.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "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",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "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": {
+    "@contractspec/lib.personalization": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.overlay-engine": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.workflow-composer": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.logger": "0.0.0-canary-20260113170453"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113170453",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113170453",
+    "tsdown": "^0.19.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",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/personalization"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/behavior-tracking.ts

@@ -0,0 +1,47 @@
+import { createBehaviorTracker } from '@contractspec/lib.personalization/tracker';
+import { InMemoryBehaviorStore } from '@contractspec/lib.personalization/store';
+import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
+import { Logger, LogLevel } from '@contractspec/lib.logger';
+
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+  environment:
+    (process.env.NODE_ENV as 'production' | 'development' | 'test') ||
+    '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 @@
+import './personalization.docblock';

package/src/docs/personalization.docblock.ts

@@ -0,0 +1,28 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/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,32 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'personalization',
+    version: '1.0.0',
+    title: 'Personalization Patterns',
+    description:
+      'Small examples for behavior tracking, overlay-based UI customization, and tenant workflow extension.',
+    kind: 'library',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['personalization', 'overlays', 'behavior', 'workflows'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.personalization',
+    usageDocId: 'docs.examples.personalization.usage',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.personalization',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,5 @@
+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,57 @@
+import { defineOverlay } from '@contractspec/lib.overlay-engine/spec';
+import { signOverlay } from '@contractspec/lib.overlay-engine/signer';
+import {
+  OverlayEngine,
+  OverlayRegistry,
+} from '@contractspec/lib.overlay-engine';
+import { Logger, LogLevel } from '@contractspec/lib.logger';
+
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+  environment:
+    (process.env.NODE_ENV as 'production' | 'development' | 'test') ||
+    '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,63 @@
+import { StabilityEnum } from '@contractspec/lib.contracts';
+import type { WorkflowSpec } from '@contractspec/lib.contracts/workflow/spec';
+import { WorkflowComposer } from '@contractspec/lib.workflow-composer';
+import { Logger, LogLevel } from '@contractspec/lib.logger';
+
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+  environment:
+    (process.env.NODE_ENV as 'production' | 'development' | 'test') ||
+    'development',
+  enableColors: process.env.NODE_ENV !== 'production',
+});
+
+const BaseWorkflow: WorkflowSpec = {
+  meta: {
+    key: 'billing.invoiceApproval',
+    version: '1.0.0',
+    title: 'Invoice Approval',
+    owners: [],
+    tags: [],
+    description: '',
+    domain: 'billing',
+    stability: StabilityEnum.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.key,
+    steps: workflow.definition.steps.map((step) => step.id),
+  });
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "paths": {
+      "@contractspec/lib.personalization/*": ["../../libs/personalization/src/*"],
+      "@contractspec/lib.contracts/*": ["../../libs/contracts/src/*"],
+      "@contractspec/lib.contracts": ["../../libs/contracts/src/index.ts"],
+      "@contractspec/lib.overlay-engine/*": ["../../libs/overlay-engine/src/*"],
+      "@contractspec/lib.overlay-engine": ["../../libs/overlay-engine/src/index.ts"]
+    }
+  }
+}
+
+

package/tsdown.config.js

@@ -0,0 +1,6 @@
+import { defineConfig } from 'tsdown';
+import { moduleLibrary } from '@contractspec/tool.tsdown';
+
+export default defineConfig(() => ({
+  ...moduleLibrary,
+}));