@contractspec/example.integration-hub 1.57.0 → 1.58.0

package/dist/connection/connection.schema.js

@@ -1,76 +1,49 @@
-import { ConnectionStatusEnum } from "./connection.enum.js";
-import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+// @bun
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
 
-//#region src/connection/connection.schema.ts
-/**
-* A connection to an external system.
-*/
-const 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
-		}
-	}
+// 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 }
+  }
 });
-/**
-* Input for creating a connection.
-*/
-const 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
-		}
-	}
+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 }
+  }
 });
-
-//#endregion
-export { ConnectionModel, CreateConnectionInputModel };
-//# sourceMappingURL=connection.schema.js.map
+export {
+  CreateConnectionInputModel,
+  ConnectionModel
+};

package/dist/connection/index.d.ts

@@ -1,4 +1,7 @@
-import { ConnectionStatusEnum } from "./connection.enum.js";
-import { CreateConnectionContract } from "./connection.operation.js";
-import { ConnectionModel, CreateConnectionInputModel } from "./connection.schema.js";
-export { ConnectionModel, ConnectionStatusEnum, CreateConnectionContract, CreateConnectionInputModel };
+/**
+ * Connection domain - Connection management.
+ */
+export { ConnectionStatusEnum } from './connection.enum';
+export { ConnectionModel, CreateConnectionInputModel, } from './connection.schema';
+export { CreateConnectionContract } from './connection.operation';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connection/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,eAAe,EACf,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/connection/index.js

@@ -1,5 +1,105 @@
-import { ConnectionStatusEnum } from "./connection.enum.js";
-import { ConnectionModel, CreateConnectionInputModel } from "./connection.schema.js";
-import { CreateConnectionContract } from "./connection.operation.js";
+// @bun
+// src/connection/connection.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ConnectionStatusEnum = defineEnum("ConnectionStatus", [
+  "PENDING",
+  "CONNECTED",
+  "DISCONNECTED",
+  "ERROR",
+  "EXPIRED"
+]);
 
-export { ConnectionModel, ConnectionStatusEnum, CreateConnectionContract, CreateConnectionInputModel };
+// 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/docs/index.d.ts

@@ -1 +1,2 @@
-export { };
+import './integration-hub.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,105 @@
-import "./integration-hub.docblock.js";
+// @bun
+// 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 \u2014 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 \u2014 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 \u2014 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/docs/integration-hub.docblock.d.ts

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

package/dist/docs/integration-hub.docblock.d.ts.map

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

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

@@ -1,21 +1,16 @@
+// @bun
+// src/docs/integration-hub.docblock.ts
 import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
-
-//#region src/docs/integration-hub.docblock.ts
-registerDocBlocks([
-	{
-		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
+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.
@@ -41,16 +36,16 @@ registerDocBlocks([
 - 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
+  },
+  {
+    id: "docs.examples.integration-hub.goal",
+    title: "Integration Hub \u2014 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.
 
@@ -61,16 +56,16 @@ registerDocBlocks([
 ## 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
+  },
+  {
+    id: "docs.examples.integration-hub.usage",
+    title: "Integration Hub \u2014 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.
 
@@ -83,20 +78,16 @@ registerDocBlocks([
 - 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
+  },
+  {
+    id: "docs.examples.integration-hub.constraints",
+    title: "Integration Hub \u2014 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.
@@ -109,8 +100,6 @@ registerDocBlocks([
 - 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.`
-	}
-]);
-
-//#endregion
-//# sourceMappingURL=integration-hub.docblock.js.map
+  }
+];
+registerDocBlocks(integrationHubDocBlocks);