@contractspec/example.integration-hub 1.57.0 → 1.58.0

package/dist/node/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/node/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/node/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);

package/dist/node/events.js

@@ -0,0 +1,211 @@
+// src/events.ts
+import { defineEvent } from "@contractspec/lib.contracts";
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+var IntegrationCreatedPayload = defineSchemaModel({
+  name: "IntegrationCreatedPayload",
+  description: "Payload when an integration is created",
+  fields: {
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    type: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var IntegrationCreatedEvent = defineEvent({
+  meta: {
+    key: "integration.created",
+    version: "1.0.0",
+    description: "Fired when a new integration is created",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration"]
+  },
+  payload: IntegrationCreatedPayload
+});
+var ConnectionCreatedPayload = defineSchemaModel({
+  name: "ConnectionCreatedPayload",
+  description: "Payload when a connection is established",
+  fields: {
+    connectionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    integrationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ConnectionCreatedEvent = defineEvent({
+  meta: {
+    key: "integration.connection.created",
+    version: "1.0.0",
+    description: "Fired when a new connection is established",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "connection"]
+  },
+  payload: ConnectionCreatedPayload
+});
+var ConnectionStatusChangedPayload = defineSchemaModel({
+  name: "ConnectionStatusChangedPayload",
+  description: "Payload when a connection status changes",
+  fields: {
+    connectionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    previousStatus: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    newStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    changedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ConnectionStatusChangedEvent = defineEvent({
+  meta: {
+    key: "integration.connection.statusChanged",
+    version: "1.0.0",
+    description: "Fired when a connection status changes",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "connection"]
+  },
+  payload: ConnectionStatusChangedPayload
+});
+var SyncConfigCreatedPayload = defineSchemaModel({
+  name: "SyncConfigCreatedPayload",
+  description: "Payload when a sync configuration is created",
+  fields: {
+    syncConfigId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    connectionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var SyncConfigCreatedEvent = defineEvent({
+  meta: {
+    key: "integration.syncConfig.created",
+    version: "1.0.0",
+    description: "Fired when a sync configuration is created",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "sync"]
+  },
+  payload: SyncConfigCreatedPayload
+});
+var SyncStartedPayload = defineSchemaModel({
+  name: "SyncStartedPayload",
+  description: "Payload when a sync run starts",
+  fields: {
+    syncRunId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    syncConfigId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var SyncStartedEvent = defineEvent({
+  meta: {
+    key: "integration.sync.started",
+    version: "1.0.0",
+    description: "Fired when a sync run starts",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "sync"]
+  },
+  payload: SyncStartedPayload
+});
+var SyncCompletedPayload = defineSchemaModel({
+  name: "SyncCompletedPayload",
+  description: "Payload when a sync run completes successfully",
+  fields: {
+    syncRunId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    syncConfigId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    recordsProcessed: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false
+    },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var SyncCompletedEvent = defineEvent({
+  meta: {
+    key: "integration.sync.completed",
+    version: "1.0.0",
+    description: "Fired when a sync run completes successfully",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "sync"]
+  },
+  payload: SyncCompletedPayload
+});
+var SyncFailedPayload = defineSchemaModel({
+  name: "SyncFailedPayload",
+  description: "Payload when a sync run fails",
+  fields: {
+    syncRunId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    syncConfigId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    error: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    failedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var SyncFailedEvent = defineEvent({
+  meta: {
+    key: "integration.sync.failed",
+    version: "1.0.0",
+    description: "Fired when a sync run fails",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "sync"]
+  },
+  payload: SyncFailedPayload
+});
+var RecordSyncedPayload = defineSchemaModel({
+  name: "RecordSyncedPayload",
+  description: "Payload when a single record is synced",
+  fields: {
+    syncRunId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    recordId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    sourceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    targetId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var RecordSyncedEvent = defineEvent({
+  meta: {
+    key: "integration.record.synced",
+    version: "1.0.0",
+    description: "Fired when a single record is synced",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "sync"]
+  },
+  payload: RecordSyncedPayload
+});
+var FieldMappingAddedPayload = defineSchemaModel({
+  name: "FieldMappingAddedPayload",
+  description: "Payload when a field mapping is added to a sync config",
+  fields: {
+    syncConfigId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    sourceField: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    targetField: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var FieldMappingAddedEvent = defineEvent({
+  meta: {
+    key: "integration.fieldMapping.added",
+    version: "1.0.0",
+    description: "Fired when a field mapping is added to a sync config",
+    stability: "experimental",
+    owners: ["@integration-team"],
+    tags: ["integration", "sync"]
+  },
+  payload: FieldMappingAddedPayload
+});
+export {
+  SyncStartedEvent,
+  SyncFailedEvent,
+  SyncConfigCreatedEvent,
+  SyncCompletedEvent,
+  RecordSyncedEvent,
+  IntegrationCreatedEvent,
+  FieldMappingAddedEvent,
+  ConnectionStatusChangedEvent,
+  ConnectionCreatedEvent
+};

package/dist/node/example.js

@@ -0,0 +1,42 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "integration-hub",
+    version: "1.0.0",
+    title: "Integration Hub",
+    description: "Provider-agnostic integration center with connectors, connections, field mappings, and sync logs.",
+    kind: "template",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["integrations", "sync", "etl", "connectors"]
+  },
+  docs: {
+    rootDocId: "docs.examples.integration-hub",
+    goalDocId: "docs.examples.integration-hub.goal",
+    usageDocId: "docs.examples.integration-hub.usage",
+    constraintsDocId: "docs.examples.integration-hub.constraints"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.integration-hub",
+    feature: "./feature",
+    contracts: "./contracts",
+    presentations: "./presentations",
+    handlers: "./handlers",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ["playground", "specs", "builder", "markdown", "evolution"]
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};