@contractspec/example.personalization 1.56.1 → 1.58.0

package/dist/behavior-tracking.js

@@ -1,48 +1,45 @@
+// @bun
+// 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 { LogLevel, Logger } from "@contractspec/lib.logger";
-
-//#region src/behavior-tracking.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
 });
 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 insights = await new BehaviorAnalyzer(store).analyze({
-		tenantId: "acme",
-		userId: "user-123"
-	});
-	logger.info("Behavior insights computed", { insights });
+  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 });
 }
-
-//#endregion
-export { runBehaviorTrackingExample };
-//# sourceMappingURL=behavior-tracking.js.map
+export {
+  runBehaviorTrackingExample
+};

package/dist/browser/behavior-tracking.js

@@ -0,0 +1,44 @@
+// 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 });
+}
+export {
+  runBehaviorTrackingExample
+};

package/dist/browser/docs/index.js

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

package/dist/browser/docs/personalization.docblock.js

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

package/dist/browser/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/browser/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/browser/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/browser/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/docs/index.d.ts

@@ -1 +1,2 @@
-export { };
+import './personalization.docblock';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,4BAA4B,CAAC"}

package/dist/docs/index.js

@@ -1 +1,41 @@
-import "./personalization.docblock.js";
+// @bun
+// 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 \u2014 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);

package/dist/docs/personalization.docblock.d.ts

@@ -1 +1,2 @@
-export { };
+export {};
+//# sourceMappingURL=personalization.docblock.d.ts.map

package/dist/docs/personalization.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personalization.docblock.d.ts","sourceRoot":"","sources":["../../src/docs/personalization.docblock.ts"],"names":[],"mappings":""}