Skip to content
ContractSpec
Start here

Package manual · platform

·Integrations and provider selection

module.integration-hub

Scoped integration-hub module — 3 genuinely reusable primitives (useIntegrationData, useCredentialSetup, renderIntegrationMarkdown) promoted from examples/integration-hub. RSC-directive boundaries are explicit.

platformmodulev2.0.5experimentalservernode
@lssm-tech/module.integration-hub
bun add @lssm-tech/module.integration-hub
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Scoped module hosting four reusable integration-hub primitives. Intentionally narrow — any new export requires a planning loop.

Installation

bash
bun add @lssm-tech/module.integration-hub

Exports

Import pathExportsRSC-safe?
@lssm-tech/module.integration-hub/hooksuseIntegrationData, useCredentialSetupNo — use in client components only
@lssm-tech/module.integration-hub/modelbuildCredentialSetupModel, credential-setup types, deployment-topology types and validatorYes
@lssm-tech/module.integration-hub/renderersrenderIntegrationMarkdownYes
@lssm-tech/module.integration-hubAll of the aboveUse sub-paths to preserve RSC boundaries

Quick start

Loading integration data (client component)

typescript
'use client';
import { useIntegrationData, type IntegrationDataPort } from '@lssm-tech/module.integration-hub/hooks';

const port: IntegrationDataPort = {
  listIntegrations: (input) => fetch(`/api/integrations?projectId=${input.projectId}`).then(r => r.json()),
  listConnections:  () => fetch('/api/connections').then(r => r.json()),
  listSyncConfigs:  () => fetch('/api/syncs').then(r => r.json()),
};

export function IntegrationCatalog({ projectId }: { projectId: string }) {
  const { integrations, loading, error, stats } = useIntegrationData({ projectId, port });

  if (loading) return <p>Loading…</p>;
  if (error)   return <p>Error: {error.message}</p>;

  return (
    <ul>
      {integrations.map(i => <li key={i.id}>{i.name} — {i.status}</li>)}
    </ul>
  );
}

Credential setup wizard (client component)

typescript
'use client';
import { useCredentialSetup } from '@lssm-tech/module.integration-hub/hooks';
import { buildCredentialSetupModel, type CredentialManifest } from '@lssm-tech/module.integration-hub/model';

const manifest: CredentialManifest = {
  modes: {
    managed: { secretFields: [{ key: 'API_KEY', required: true }] },
    byok:    { configFields: [{ key: 'ENDPOINT', required: true }] },
  },
};

export function CredentialWizard() {
  const { state, advance, reset, setMode } = useCredentialSetup();

  const model = buildCredentialSetupModel({
    mode: state.mode,
    manifest,
    environment: { variables: {}, targets: {} },
    runtime: { configValues: {}, secretRefs: {}, targetIds: [] },
  });

  return (
    <div>
      <p>Step {state.step} / 3 — mode: {state.mode}</p>
      <p>Missing secrets: {model.missingSecrets.length}</p>
      <button onClick={advance}>Next</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Rendering a markdown card (RSC-safe)

typescript
// Works in React Server Components — no 'use client' needed
import { renderIntegrationMarkdown } from '@lssm-tech/module.integration-hub/renderers';

export async function IntegrationCard({ id }: { id: string }) {
  const integration = await fetchIntegration(id);
  const markdown = renderIntegrationMarkdown({
    id: integration.id,
    name: integration.name,
    description: integration.description,
    category: integration.category,
    status: integration.status,
    connectionCount: integration.connections.length,
  });
  return <MarkdownRenderer content={markdown} />;
}

RSC directive boundaries

Hooks carry 'use client' — import them only in client components. Model types and the markdown renderer have no directive and are safe to import anywhere, including React Server Components. See AGENTS.md for the full boundary table and lint rules.

Deployment topology

validateIntegrationDeploymentTopology models service operator, runtime and data placement, credential custody, identity trust, API commercial mode, network policy, residency, and evidence placement as independent axes. It is a pure fail-closed validator: customer API keys cannot be assigned to an LSSM-only vault, and air-gapped profiles cannot depend on live central identity or remote managed data.

The model subpath re-exports the canonical provider-neutral topology contract from @lssm-tech/lib.contracts-integrations. The Hub accepts an optional integration.topology-evidence read port for a secret-free, freshness-bounded provider receipt tied to an exact workspace or connection digest. Installing the port does not verify the provider by itself; only an adapter that has verified its native durable receipt may project this evidence.

What this package does NOT include

  • CompanyOS-specific chrome or view-models (those live in bundle.managed-companyos)
  • RedactedCredentialChip (stays in the bundle pending second consumer)
  • Any example fixtures or mock data (see examples/integration-hub)

Development

bash
bun test --cwd packages/platform/delivery/integration-hub
bun run --cwd packages/platform/delivery/integration-hub typecheck

Feature Hub profile

./hub exports IntegrationFeatureHub, defineIntegrationHub, and installIntegrationHub. The profile uses the canonical platform.integrations feature registry, mounts at /integrations, and depends only on the provider-neutral integration.catalog and integration.connection ports. Its route catalog covers detail, connections, syncs, configuration, credentials/secrets, health, audit, and installation; activation supports both managed credentials and BYOK secret references. integration.topology-evidence is optional so existing installations remain compatible and missing proof remains explicit.

Relationships

THIS PACKAGEmodule.integration-hub14 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

4 declarations

Declared capabilities

Module Integration Hub

Scoped integration-hub module — 3 genuinely reusable primitives (useIntegrationData, useCredentialSetup, renderIntegrationMarkdown) promoted from examples/integration-hub. RSC-directive boundaries are explicit.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test --pass-with-no-tests
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit