@contractspec/example.integration-hub 1.56.1 → 1.58.0

package/README.md

@@ -2,12 +2,13 @@
 
 Website: https://contractspec.io/
 
-
 A comprehensive integration hub example demonstrating ContractSpec principles for data synchronization.
 
 ## Features
 
 - **Multi-Provider Support**: Connect to various external systems (Salesforce, HubSpot, etc.)
+- **Voice Provider Coverage**: Includes seeded examples for `ai-voice.gradium` and `ai-voice.fal`
+- **Analytics Coverage**: Includes seeded examples for PostHog analytics
 - **Bidirectional Sync**: INBOUND, OUTBOUND, or BIDIRECTIONAL data flow
 - **Field Mapping**: Configurable field mappings with transforms
 - **Sync Engine**: Change detection, deduplication, and error handling
@@ -18,12 +19,14 @@ A comprehensive integration hub example demonstrating ContractSpec principles fo
 ## Entities
 
 ### Core
+
 - `Integration` - Integration definition
 - `Connection` - Authenticated connection to external system
 - `SyncConfig` - Sync configuration for object pairs
 - `FieldMapping` - Field-level mapping configuration
 
 ### Sync Execution
+
 - `SyncRun` - A single sync execution
 - `SyncLog` - Log entries for a sync run
 - `SyncRecord` - Tracks synced records for deduplication
@@ -31,14 +34,17 @@ A comprehensive integration hub example demonstrating ContractSpec principles fo
 ## Contracts
 
 ### Integration Management
+
 - `integration.create` - Create a new integration
 - `integration.connection.create` - Create a connection
 
 ### Sync Configuration
+
 - `integration.syncConfig.create` - Create sync config
 - `integration.fieldMapping.add` - Add field mapping
 
 ### Sync Execution
+
 - `integration.sync.trigger` - Trigger manual sync
 - `integration.syncRun.list` - List sync history
 
@@ -101,11 +107,11 @@ const result = engine.transformRecord(
 ## Usage
 
 ```typescript
-import { 
+import {
   CreateIntegrationContract,
   CreateSyncConfigContract,
   TriggerSyncContract,
-  integrationHubSchemaContribution 
+  integrationHubSchemaContribution
 } from '@contractspec/example.integration-hub';
 
 // Create integration
@@ -138,19 +144,3 @@ const run = await executeContract(TriggerSyncContract, {
 - `@contractspec/lib.files` - Import/export file handling
 - `@contractspec/lib.jobs` - Background sync jobs
 - `@contractspec/module.audit-trail` - Action auditing
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/dist/browser/connection/connection.enum.js

@@ -0,0 +1,12 @@
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
+export {
+  ConnectionStatusEnum
+};

package/dist/browser/connection/connection.operation.js

@@ -0,0 +1,101 @@
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
+
+// src/connection/connection.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ConnectionModel = defineSchemaModel({
+  name: "ConnectionModel",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ConnectionStatusEnum, isOptional: false },
+    authType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    externalAccountName: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    connectedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    lastHealthCheck: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    healthStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var CreateConnectionInputModel = defineSchemaModel({
+  name: "CreateConnectionInput",
+  fields: {
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    authType: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    credentials: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+
+// src/connection/connection.operation.ts
+import { defineCommand } from "@contractspec/lib.contracts/operations";
+var OWNERS = ["@example.integration-hub"];
+var CreateConnectionContract = defineCommand({
+  meta: {
+    key: "integration.connection.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["integration", "connection", "create"],
+    description: "Create a connection to an external system.",
+    goal: "Authenticate with external systems.",
+    context: "Connection setup."
+  },
+  io: { input: CreateConnectionInputModel, output: ConnectionModel },
+  policy: { auth: "user" },
+  sideEffects: {
+    emits: [
+      {
+        key: "integration.connection.created",
+        version: "1.0.0",
+        when: "Connection created",
+        payload: ConnectionModel
+      }
+    ],
+    audit: ["integration.connection.created"]
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "create-connection-happy-path",
+        given: ["User is authenticated"],
+        when: ["User creates connection with valid credentials"],
+        then: ["Connection is created", "ConnectionCreated event is emitted"]
+      }
+    ],
+    examples: [
+      {
+        key: "connect-crm",
+        input: {
+          name: "Salesforce Prod",
+          integrationId: "salesforce",
+          credentials: { clientId: "xxx" }
+        },
+        output: {
+          id: "conn-123",
+          status: "connected",
+          connectedAt: "2025-01-01T12:00:00Z"
+        }
+      }
+    ]
+  }
+});
+export {
+  CreateConnectionContract
+};

package/dist/browser/connection/connection.presentation.js

@@ -0,0 +1,99 @@
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
+
+// src/connection/connection.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ConnectionModel = defineSchemaModel({
+  name: "ConnectionModel",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ConnectionStatusEnum, isOptional: false },
+    authType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    externalAccountName: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    connectedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    lastHealthCheck: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    healthStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var CreateConnectionInputModel = defineSchemaModel({
+  name: "CreateConnectionInput",
+  fields: {
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    authType: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    credentials: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+
+// src/connection/connection.presentation.ts
+import { definePresentation, StabilityEnum } from "@contractspec/lib.contracts";
+var ConnectionListPresentation = definePresentation({
+  meta: {
+    key: "integration.connection.list",
+    version: "1.0.0",
+    title: "Connection List",
+    description: "List of integration connections",
+    domain: "integration",
+    owners: ["@integration-team"],
+    tags: ["integration", "connection", "list"],
+    stability: StabilityEnum.Experimental,
+    goal: "Provide an overview of all established integration connections.",
+    context: "The primary management view for integration hubs."
+  },
+  source: {
+    type: "component",
+    framework: "react",
+    componentKey: "ConnectionList",
+    props: ConnectionModel
+  },
+  targets: ["react", "markdown"],
+  policy: {
+    flags: ["integration.enabled"]
+  }
+});
+var ConnectionSetupPresentation = definePresentation({
+  meta: {
+    key: "integration.connection.setup",
+    version: "1.0.0",
+    title: "Connection Setup",
+    description: "Setup wizard for creating integration connections",
+    domain: "integration",
+    owners: ["@integration-team"],
+    tags: ["integration", "connection", "setup"],
+    stability: StabilityEnum.Experimental,
+    goal: "Guide users through the multi-step process of connecting to a new integration.",
+    context: "The onboarding flow for new integrations."
+  },
+  source: {
+    type: "component",
+    framework: "react",
+    componentKey: "ConnectionSetup",
+    props: ConnectionModel
+  },
+  targets: ["react"],
+  policy: {
+    flags: ["integration.enabled"]
+  }
+});
+export {
+  ConnectionSetupPresentation,
+  ConnectionListPresentation
+};

package/dist/browser/connection/connection.schema.js

@@ -0,0 +1,48 @@
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
+
+// src/connection/connection.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ConnectionModel = defineSchemaModel({
+  name: "ConnectionModel",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ConnectionStatusEnum, isOptional: false },
+    authType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    externalAccountName: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    connectedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    lastHealthCheck: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    healthStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var CreateConnectionInputModel = defineSchemaModel({
+  name: "CreateConnectionInput",
+  fields: {
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    authType: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    credentials: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+export {
+  CreateConnectionInputModel,
+  ConnectionModel
+};

package/dist/browser/connection/index.js

@@ -0,0 +1,104 @@
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
+
+// src/connection/connection.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ConnectionModel = defineSchemaModel({
+  name: "ConnectionModel",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ConnectionStatusEnum, isOptional: false },
+    authType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    externalAccountName: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    connectedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    lastHealthCheck: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    healthStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var CreateConnectionInputModel = defineSchemaModel({
+  name: "CreateConnectionInput",
+  fields: {
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    authType: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    credentials: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+
+// src/connection/connection.operation.ts
+import { defineCommand } from "@contractspec/lib.contracts/operations";
+var OWNERS = ["@example.integration-hub"];
+var CreateConnectionContract = defineCommand({
+  meta: {
+    key: "integration.connection.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["integration", "connection", "create"],
+    description: "Create a connection to an external system.",
+    goal: "Authenticate with external systems.",
+    context: "Connection setup."
+  },
+  io: { input: CreateConnectionInputModel, output: ConnectionModel },
+  policy: { auth: "user" },
+  sideEffects: {
+    emits: [
+      {
+        key: "integration.connection.created",
+        version: "1.0.0",
+        when: "Connection created",
+        payload: ConnectionModel
+      }
+    ],
+    audit: ["integration.connection.created"]
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "create-connection-happy-path",
+        given: ["User is authenticated"],
+        when: ["User creates connection with valid credentials"],
+        then: ["Connection is created", "ConnectionCreated event is emitted"]
+      }
+    ],
+    examples: [
+      {
+        key: "connect-crm",
+        input: {
+          name: "Salesforce Prod",
+          integrationId: "salesforce",
+          credentials: { clientId: "xxx" }
+        },
+        output: {
+          id: "conn-123",
+          status: "connected",
+          connectedAt: "2025-01-01T12:00:00Z"
+        }
+      }
+    ]
+  }
+});
+export {
+  CreateConnectionInputModel,
+  CreateConnectionContract,
+  ConnectionStatusEnum,
+  ConnectionModel
+};

package/dist/browser/docs/index.js

@@ -0,0 +1,104 @@
+// src/docs/integration-hub.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var integrationHubDocBlocks = [
+  {
+    id: "docs.examples.integration-hub",
+    title: "Integration Hub",
+    summary: "Generic integration center with connectors, connections, sync configs, field mappings, and sync logs.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/integration-hub",
+    tags: ["integrations", "sync", "etl", "connectors"],
+    body: `## Entities
+
+- Integration, Connection, SyncConfig, FieldMapping, SyncLog.
+- Sync engine config lives in \`src/sync-engine\` to map remote <-> local entities.
+
+## Contracts
+
+- \`integration.create\`, \`integration.connect\`, \`integration.configureSync\`, \`integration.mapFields\`, \`integration.runSync\`.
+- Uses Jobs module for scheduled syncs and retries; Files module for payload archives.
+
+## Events
+
+- sync.started/completed/failed, connection.connected/disconnected, mapping.updated.
+- Forward to Notifications and Audit for observability.
+
+## UI / Presentations
+
+- Dashboard, integration list, connection detail, sync config editor.
+- Templates registered as \`integration-hub\` in Template Registry.
+
+## Notes
+
+- Providers remain agnostic; keep mappings declarative for safe regeneration.
+- Seed data includes voice integrations for \`ai-voice.gradium\` and \`ai-voice.fal\`.
+- Feature flags can gate specific providers; metering can track sync volume.
+`
+  },
+  {
+    id: "docs.examples.integration-hub.goal",
+    title: "Integration Hub — Goal",
+    summary: "Why this integration hub exists and what success looks like.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/integration-hub/goal",
+    tags: ["integrations", "goal"],
+    body: `## Why it matters
+- Gives a regenerable, provider-agnostic integration hub with explicit mappings.
+- Prevents drift between sync configs, mappings, and event/log outputs.
+
+## Business/Product goal
+- Model connectors, connections, sync jobs, and mappings with governance and retries.
+- Support staged provider rollouts via Feature Flags and observability via Audit/Notifications.
+
+## Success criteria
+- Connections and mappings regenerate safely after spec edits.
+- Sync events and logs provide auditability; payloads are stored and PII-scoped.`
+  },
+  {
+    id: "docs.examples.integration-hub.usage",
+    title: "Integration Hub — Usage",
+    summary: "How to configure connectors, mappings, and scheduled syncs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/integration-hub/usage",
+    tags: ["integrations", "usage"],
+    body: `## Setup
+1) Seed integrations/connections (if available) or create connector definitions.
+2) Configure sync jobs with Jobs module; store payload archives via Files.
+
+## Extend & regenerate
+1) Add mapping fields or provider configs in the spec; include validation and PII paths.
+2) Regenerate to align UI/API/events/logs; verify Notifications/Audit hooks.
+3) Gate risky providers behind Feature Flags; meter sync volume if needed.
+
+## Guardrails
+- Keep mappings declarative; avoid hardcoded transforms.
+- Emit events for sync lifecycle; persist logs for audit.
+- Redact sensitive payload paths in presentations.`
+  },
+  {
+    id: "docs.examples.integration-hub.constraints",
+    title: "Integration Hub — Constraints & Safety",
+    summary: "Internal guidance for sync lifecycle, mappings, and regeneration safety.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/integration-hub/constraints",
+    tags: ["integrations", "constraints", "internal"],
+    body: `## Constraints
+- Mappings and sync states must remain declarative in spec; no hidden code transforms.
+- Events to emit at minimum: sync.started, sync.completed, sync.failed; connection.connected/disconnected.
+- Regeneration should not alter retry/backoff semantics without explicit spec change.
+
+## PII & Payloads
+- Treat payload archives as potentially sensitive; mark policy.pii paths.
+- For MCP/web, avoid exposing raw credentials/tokens; store via provider adapters only.
+
+## Verification
+- Include fixtures for mapping changes and sync retries.
+- Validate that scheduled jobs (cron) are spec-driven; Jobs module wiring intact.
+- Ensure Audit/Notifications receive sync lifecycle events.`
+  }
+];
+registerDocBlocks(integrationHubDocBlocks);

package/dist/browser/docs/integration-hub.docblock.js

@@ -0,0 +1,104 @@
+// src/docs/integration-hub.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var integrationHubDocBlocks = [
+  {
+    id: "docs.examples.integration-hub",
+    title: "Integration Hub",
+    summary: "Generic integration center with connectors, connections, sync configs, field mappings, and sync logs.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/integration-hub",
+    tags: ["integrations", "sync", "etl", "connectors"],
+    body: `## Entities
+
+- Integration, Connection, SyncConfig, FieldMapping, SyncLog.
+- Sync engine config lives in \`src/sync-engine\` to map remote <-> local entities.
+
+## Contracts
+
+- \`integration.create\`, \`integration.connect\`, \`integration.configureSync\`, \`integration.mapFields\`, \`integration.runSync\`.
+- Uses Jobs module for scheduled syncs and retries; Files module for payload archives.
+
+## Events
+
+- sync.started/completed/failed, connection.connected/disconnected, mapping.updated.
+- Forward to Notifications and Audit for observability.
+
+## UI / Presentations
+
+- Dashboard, integration list, connection detail, sync config editor.
+- Templates registered as \`integration-hub\` in Template Registry.
+
+## Notes
+
+- Providers remain agnostic; keep mappings declarative for safe regeneration.
+- Seed data includes voice integrations for \`ai-voice.gradium\` and \`ai-voice.fal\`.
+- Feature flags can gate specific providers; metering can track sync volume.
+`
+  },
+  {
+    id: "docs.examples.integration-hub.goal",
+    title: "Integration Hub — Goal",
+    summary: "Why this integration hub exists and what success looks like.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/integration-hub/goal",
+    tags: ["integrations", "goal"],
+    body: `## Why it matters
+- Gives a regenerable, provider-agnostic integration hub with explicit mappings.
+- Prevents drift between sync configs, mappings, and event/log outputs.
+
+## Business/Product goal
+- Model connectors, connections, sync jobs, and mappings with governance and retries.
+- Support staged provider rollouts via Feature Flags and observability via Audit/Notifications.
+
+## Success criteria
+- Connections and mappings regenerate safely after spec edits.
+- Sync events and logs provide auditability; payloads are stored and PII-scoped.`
+  },
+  {
+    id: "docs.examples.integration-hub.usage",
+    title: "Integration Hub — Usage",
+    summary: "How to configure connectors, mappings, and scheduled syncs.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/integration-hub/usage",
+    tags: ["integrations", "usage"],
+    body: `## Setup
+1) Seed integrations/connections (if available) or create connector definitions.
+2) Configure sync jobs with Jobs module; store payload archives via Files.
+
+## Extend & regenerate
+1) Add mapping fields or provider configs in the spec; include validation and PII paths.
+2) Regenerate to align UI/API/events/logs; verify Notifications/Audit hooks.
+3) Gate risky providers behind Feature Flags; meter sync volume if needed.
+
+## Guardrails
+- Keep mappings declarative; avoid hardcoded transforms.
+- Emit events for sync lifecycle; persist logs for audit.
+- Redact sensitive payload paths in presentations.`
+  },
+  {
+    id: "docs.examples.integration-hub.constraints",
+    title: "Integration Hub — Constraints & Safety",
+    summary: "Internal guidance for sync lifecycle, mappings, and regeneration safety.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/integration-hub/constraints",
+    tags: ["integrations", "constraints", "internal"],
+    body: `## Constraints
+- Mappings and sync states must remain declarative in spec; no hidden code transforms.
+- Events to emit at minimum: sync.started, sync.completed, sync.failed; connection.connected/disconnected.
+- Regeneration should not alter retry/backoff semantics without explicit spec change.
+
+## PII & Payloads
+- Treat payload archives as potentially sensitive; mark policy.pii paths.
+- For MCP/web, avoid exposing raw credentials/tokens; store via provider adapters only.
+
+## Verification
+- Include fixtures for mapping changes and sync retries.
+- Validate that scheduled jobs (cron) are spec-driven; Jobs module wiring intact.
+- Ensure Audit/Notifications receive sync lifecycle events.`
+  }
+];
+registerDocBlocks(integrationHubDocBlocks);