example.integration-hub

@lssm-tech/example.integration-hub

Website: https://contractspec.io

Integration Hub example with sync engine and field mappings for ContractSpec.

What This Demonstrates

• Connection management with typed schemas and enums.
• Integration lifecycle (create, configure, sync).
• Sync engine with field mapping and status tracking.
• MCP server example for tool integration.
• Capability and feature definition patterns.
• React UI with a cockpit-style Integration Hub command center, screen navigation, hooks, markdown renderers, and shared ContractSpec tables for connections and sync configs.
• Contract-backed visualizations for integration mix, connection health, and sync-state comparison.
• Client-mode table capabilities including sorting, pagination, column visibility, pinning, resizing, and expanded operational details.
• Event definitions and operation test-specs.
• Managed/BYOK credential setup metadata with monorepo-aware Next and Expo env aliases plus an interactive mode switch in the hub UI.
• Registry-derived provider seeding from createDefaultIntegrationSpecRegistry() so the preview covers the complete shipped integration catalog, including BYOK-only entries with explicit managed-mode exemption metadata.
• Redacted connection credential previews; handlers return secret placeholders instead of raw key material.
• Runtime resolver and governance screens that explain managed/BYOK fallback, policy evidence, and release-review posture.
• Managed/BYOK database mutation examples in src/setup/database-mutation-examples.ts route durable writes through the provider-database ./governed-mutation helper only after an owning domain command emits domainCommandRef, policyDecisionRef, idempotencyKey, transactionBoundary, expectedWriteSet, auditEventRefs, replayRef, and correlationRef evidence; fixtures use redacted refs only and never embed raw database credentials.
• Phase 5 DS1/DS4: all UI cards in the catalog use IntegrationCardSurface (hover elevation + focus ring) and IntegrationHealthDot from @lssm-tech/bundle.managed-companyos/ui/integrations. Empty states use EmptyStateIllustrated. The credential setup flow is wrapped in WizardStepper. A dedicated Rich Interactions screen demonstrates every DS1 atom and molecule in one place.

Reusable bundle integration

The example demonstrates the Integration Hub but does not own the reusable Managed CompanyOS production surfaces. Hosts should compose the canonical bundle surfaces directly:

• View-model builders from @lssm-tech/bundle.managed-companyos/view-models/integration-*.
• Templates from @lssm-tech/bundle.managed-companyos/ui/templates.
• Capability atoms and design primitives from @lssm-tech/bundle.managed-companyos/ui/integrations.

Example UI files should remain demo/adaptation layers over those imports. Do not fork credential, secret, connection, sync, audit, or role-morph logic locally. Managed/BYOK turn-on flows must require an explicit ownership-mode choice and may render only redacted credential references.

Design System Integration (Phase 5 DS1)

The example imports DS1 primitives from the bundle — it does not re-implement them.

Consumers that want to adopt these primitives directly should import from @lssm-tech/bundle.managed-companyos/ui/integrations — not from this example package.

Running Locally

From examples/integration-hub:

• bun run dev
• bun run build
• bun run test
• bun run typecheck

Usage

Utiliser @lssm-tech/example.integration-hub as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

Architecture

• src/connection is part of the package's public or composition surface.
• src/docs/ contains docblocks and documentation-facing exports.
• src/events.ts is package-level event definitions.
• src/example.ts is the runnable example entrypoint.
• src/handlers/ contains handlers or demo adapters wired to contract surfaces.
• src/index.ts is the root public barrel and package entrypoint.
• src/integration is part of the package's public or composition surface.
• src/setup exposes BYOK credential manifests, secret-reference fixtures, and monorepo env aliases.
• src/ui/IntegrationDashboard.* subpaths expose advanced UI composition pieces for hosts that want to reuse the command-center shell, navigation, screen model, or individual rich screens. The default ./ui/IntegrationDashboard export wraps its command center in the shared NestedCommandShell from @lssm-tech/lib.example-shared-ui; keep local navigation inside that reusable nested-safe shell unless a preview-specific containment guardrail requires otherwise. Prefer ./ui/IntegrationDashboard unless custom composition is required.
• Production apps should consume bundle Integration Hub view-models/templates directly; this package remains an example adapter and documentation surface.

Public Entry Points

• Export . resolves through ./src/index.ts.
• Export ./connection resolves through ./src/connection/index.ts.
• Export ./connection/connection.enum resolves through ./src/connection/connection.enum.ts.
• Export ./connection/connection.operation resolves through ./src/connection/connection.operation.ts.
• Export ./connection/connection.presentation resolves through ./src/connection/connection.presentation.ts.
• Export ./connection/connection.schema resolves through ./src/connection/connection.schema.ts.
• Export ./docs resolves through ./src/docs/index.ts.
• Export ./docs/integration-hub.docblock is an alias of ./docs and resolves through ./src/docs/index.ts.
• Export ./events resolves through ./src/events.ts.
• Export ./example resolves through ./src/example.ts.
• Export ./setup resolves through ./src/setup/index.ts.
• Export ./setup/credential-setup resolves through ./src/setup/credential-setup.ts.
• The package publishes 52 total export subpaths; keep docs aligned with package.json.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run validate — contractspec validate "src/**/*"
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run run:mcp — bun tsx src/run-mcp.ts
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Vnext ai-native.
• Missing contract layers.
• Resolve lint, build, and type errors across nine packages.
• Add Composio universal fallback, fix provider-ranking types, and expand package exports.
• Add first-class transport, auth, versioning, and BYOK support across all integrations.
• Add Integration Hub BYOK credential setup metadata and Next/Expo alias previews.
• Seed Integration Hub from the shipped provider registry and expose typed ownership mode plus redacted credential previews through handler flows.
• Upgrade the Integration Hub dashboard into a rich command-center demo with provider catalog, managed/BYOK credential, connection, sync, runtime governance, and assistant screens.

Notes

• Works alongside @lssm-tech/lib.ai-agent, @lssm-tech/lib.contracts-spec, @lssm-tech/lib.design-system, @lssm-tech/lib.example-shared-ui, @lssm-tech/lib.runtime-sandbox, ...

UI projection imports use existing domain-specific view-model subpaths to avoid loading unrelated server domains through the all-domain barrel.