@contractspec/example.personalization 1.57.0 → 1.58.0

package/dist/node/example.js

@@ -0,0 +1,33 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/node/index.js

@@ -0,0 +1,227 @@
+// src/behavior-tracking.ts
+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";
+var logger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableColors: true
+});
+async function runBehaviorTrackingExample() {
+  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 });
+}
+
+// src/docs/personalization.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+- Call \`runBehaviorTrackingExample()\` for insights.
+- Call \`runOverlayCustomizationExample()\` to apply overlays.
+- Call \`composeTenantWorkflowExample()\` and \`logTenantWorkflowSteps()\` to inspect steps.
+
+## Notes
+- Replace in-memory stores with app-layer storage.
+- Keep PII out of logs and markdown outputs.`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+
+// src/overlay-customization.ts
+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 as Logger2, LogLevel as LogLevel2 } from "@contractspec/lib.logger";
+var logger2 = new Logger2({
+  level: LogLevel2.DEBUG,
+  environment: "development",
+  enableColors: true
+});
+async function runOverlayCustomizationExample() {
+  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"
+  });
+  logger2.info("Overlay applied", { fields: result.target.fields });
+}
+
+// src/workflow-extension.ts
+import { StabilityEnum } from "@contractspec/lib.contracts";
+import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
+import { Logger as Logger3, LogLevel as LogLevel3 } from "@contractspec/lib.logger";
+var logger3 = new Logger3({
+  level: LogLevel3.DEBUG,
+  environment: "development",
+  enableColors: true
+});
+var 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) {
+  logger3.info("Tenant workflow composed", {
+    workflow: workflow.meta.key,
+    steps: workflow.definition.steps.map((step) => step.id)
+  });
+}
+export {
+  runOverlayCustomizationExample,
+  runBehaviorTrackingExample,
+  logTenantWorkflowSteps,
+  example_default as example,
+  composeTenantWorkflowExample
+};

package/dist/node/overlay-customization.js

@@ -0,0 +1,53 @@
+// src/overlay-customization.ts
+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";
+var logger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableColors: true
+});
+async function runOverlayCustomizationExample() {
+  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 });
+}
+export {
+  runOverlayCustomizationExample
+};

package/dist/node/workflow-extension.js

@@ -0,0 +1,60 @@
+// src/workflow-extension.ts
+import { StabilityEnum } from "@contractspec/lib.contracts";
+import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
+import { Logger, LogLevel } from "@contractspec/lib.logger";
+var logger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableColors: true
+});
+var 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)
+  });
+}
+export {
+  logTenantWorkflowSteps,
+  composeTenantWorkflowExample
+};

package/dist/overlay-customization.d.ts

@@ -1,5 +1,2 @@
-//#region src/overlay-customization.d.ts
-declare function runOverlayCustomizationExample(): Promise<void>;
-//#endregion
-export { runOverlayCustomizationExample };
+export declare function runOverlayCustomizationExample(): Promise<void>;
 //# sourceMappingURL=overlay-customization.d.ts.map

package/dist/overlay-customization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay-customization.d.ts","names":[],"sources":["../src/overlay-customization.ts"],"mappings":";iBAgBsB,8BAAA,CAAA,GAAkC,OAAA"}
+{"version":3,"file":"overlay-customization.d.ts","sourceRoot":"","sources":["../src/overlay-customization.ts"],"names":[],"mappings":"AAgBA,wBAAsB,8BAA8B,IAAI,OAAO,CAAC,IAAI,CAAC,CAwCpE"}

package/dist/overlay-customization.js

@@ -1,50 +1,54 @@
-import { LogLevel, Logger } from "@contractspec/lib.logger";
+// @bun
+// src/overlay-customization.ts
 import { defineOverlay } from "@contractspec/lib.overlay-engine/spec";
 import { signOverlay } from "@contractspec/lib.overlay-engine/signer";
-import { OverlayEngine, OverlayRegistry } from "@contractspec/lib.overlay-engine";
-
-//#region src/overlay-customization.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"
+import {
+  OverlayEngine,
+  OverlayRegistry
+} from "@contractspec/lib.overlay-engine";
+import { Logger, LogLevel } from "@contractspec/lib.logger";
+var logger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableColors: true
 });
 async function runOverlayCustomizationExample() {
-	const registry = new OverlayRegistry({ allowUnsigned: true });
-	const engine = new OverlayEngine({ registry });
-	const signed = await signOverlay(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"
-		}]
-	}), 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 });
+  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 });
 }
-
-//#endregion
-export { runOverlayCustomizationExample };
-//# sourceMappingURL=overlay-customization.js.map
+export {
+  runOverlayCustomizationExample
+};

package/dist/workflow-extension.d.ts

@@ -1,8 +1,4 @@
-import { WorkflowSpec } from "@contractspec/lib.contracts/workflow/spec";
-
-//#region src/workflow-extension.d.ts
-declare function composeTenantWorkflowExample(): WorkflowSpec;
-declare function logTenantWorkflowSteps(workflow: WorkflowSpec): void;
-//#endregion
-export { composeTenantWorkflowExample, logTenantWorkflowSteps };
+import type { WorkflowSpec } from '@contractspec/lib.contracts/workflow/spec';
+export declare function composeTenantWorkflowExample(): WorkflowSpec;
+export declare function logTenantWorkflowSteps(workflow: WorkflowSpec): void;
 //# sourceMappingURL=workflow-extension.d.ts.map

package/dist/workflow-extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-extension.d.ts","names":[],"sources":["../src/workflow-extension.ts"],"mappings":";;;iBAiCgB,4BAAA,CAAA,GAAgC,YAAA;AAAA,iBAwBhC,sBAAA,CAAuB,QAAA,EAAU,YAAA"}
+{"version":3,"file":"workflow-extension.d.ts","sourceRoot":"","sources":["../src/workflow-extension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAgC9E,wBAAgB,4BAA4B,IAAI,YAAY,CAsB3D;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAKnE"}

package/dist/workflow-extension.js

@@ -1,67 +1,61 @@
-import { LogLevel, Logger } from "@contractspec/lib.logger";
+// @bun
+// src/workflow-extension.ts
 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"
+import { Logger, LogLevel } from "@contractspec/lib.logger";
+var logger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableColors: true
 });
-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"
-		}]
-	}
+var 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"
-	});
+  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)
-	});
+  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
+export {
+  logTenantWorkflowSteps,
+  composeTenantWorkflowExample
+};