Source snapshot bcc79fcc · Declared package version 9.0.4. This page combines the checked-in package guide and manifest; commands and runtime behavior were not executed in this review.
The ./operations/integrations family owns integration management operations and shared wire schemas. The ./database family owns provider-neutral database operations, capabilities, views, physical-table declarations and their registry. Legacy contracts-spec paths forward these exact values, including table singleton state and the original nominal operation/capability/data-view registry signatures. Provider implementations remain outside these declaration families; database mutation policy and tenant authority requirements are unchanged.
The provider surface includes MeetingBotCaptureProvider and its mandatory
MeetingCaptureAuthorityPort for authorized bot lifecycle control, transcript retrieval and ambiguity reconciliation. Implementations remain provider-specific and server-only; these contracts do not grant recording consent or tenant access.
@lssm-tech/lib.contracts-integrations defines provider-agnostic contracts for integration specs, connection/runtime handling, secret resolution, health and telemetry, and capability-level provider interfaces such as LLM, embeddings, vector stores, email, and storage.
Capability-ledger, hosted-MCP, preflight, Attio, Clay, and FullEnrich GTM contracts.
Governed web-access contracts, provider inventories, transport metadata, and capability evidence for Bright Data, Massive, Browserbase, Serper, Linkup, and Tavily.
Use this package when you need shared integration contracts. Do not use it as the SDK-backed implementation layer or as the integration persistence runtime.
Deployment-topology evidence
./integrations/deployment-topology keeps service operation, runtime and data placement, credential custody, identity trust, API commercial mode, network policy, residency, and evidence placement independent. A canonical SHA-256 digest binds all nine axes to either one workspace or one exact integration connection.
assessIntegrationTopologyProviderReceipt validates structure, freshness, safe references, success state, and the exact scope/topology binding. It is not a cryptographic or provider-native verifier. A provider adapter must first verify the durable native receipt and authorized execution, then project the secret-free IntegrationTopologyProviderReceiptV1. Environment declarations, fixtures, and locally valid topology values never establish provider proof.
GTM provider surfaces
Attio and Clay operations are exposed through stable ContractSpec keys and project to generic REST and local MCP surfaces. FullEnrich retains its existing
sales-intelligence.fullenrich.* operation keys.
Utiliser preflightGtmCapability before execution to validate connection readiness, account entitlements, scopes, preview opt-ins, surface support, webhook setup, and approval availability. Vendor-hosted MCP descriptors are metadata for external client sessions: they are never proxied and their OAuth tokens remain client-held.
The pinned capability ledgers and evidence digests are exported from
./integrations/gtm/capability-ledger. Raw webhook ingress is intentionally not projected into local MCP.
Web-access provider surfaces
The ./integrations/web-access subpath defines normalized search, fetch, extract, map, crawl, research, job, browser-session, proxy, delivery-event, and MCP-discovery contracts. It also exports composable provider ports, schemas, operation definitions, a provider inventory, and a pinned capability ledger. Original operation envelopes remain registered as v1.0. The concrete operation-family schemas and typed error catalogs are published additively as v1.1, provider expansion remains pinned as v1.2, and provider-neutral browser act, observe, and structured extract contracts are available as v1.3.
Every supported capability cell pins both the complete preserved evidence packet and the claim-level official-documentation excerpt with independently verified SHA-256 digests. Adapter references include a concrete exported symbol, and surface mappings enumerate only the operations implemented by that symbol.
Provider-specific operations remain typed: Bright Data scraper and dataset jobs, Massive usage reporting, Browserbase contexts, and Serper result categories do not require an unrestricted raw-request escape hatch. Massive and Tavily v1 metadata remain compatible; their expanded surfaces are registered additively as v1.1.
The browser automation operations form an SDK-neutral Stagehand v4 compatibility profile over session and optional page identifiers, natural-language instructions, opaque element references, and JSON-shaped extraction schemas. The capability ledger reports this profile as supported through the concrete
BrowserbaseStagehandAdapter and executable adapter/tool tests. Contracts remain SDK-neutral here; @lssm-tech/integration.provider-web-access separately owns the Stagehand and Browserbase runtime implementation.
Utiliser WebAccessPolicyMode to select governed, provider-pass-through, or
public-only. Every mode retains the same SSRF, secret-redaction, bounded-body, and HTTPS control-plane baseline. Vendor-native webhook, WebSocket, SSE, MCP, SDK, and proxy surfaces are advertised only when the pinned capability evidence supports them; every normalized operation can still be projected through ContractSpec MCP.
import {
IntegrationCallGuard,
} from "@lssm-tech/lib.contracts-integrations/integrations/runtime";
import {
EnvSecretProvider,
SecretProviderManager,
} from "@lssm-tech/lib.contracts-integrations/integrations/secrets";
const secretProvider = new SecretProviderManager({
providers: [
{ provider: new EnvSecretProvider(), priority: 100 },
],
});
const guard = new IntegrationCallGuard(secretProvider);
const result = await guard.executeWithGuards(
"primary-llm",
"chat",
{},
resolvedAppConfig,
async (connection, secrets) => {
return llmAdapter.chat(connection, secrets, input);
}
);
Typical flow:
Declare an IntegrationSpec that describes config, secrets, auth, transport, and version policy.
Register specs in an IntegrationSpecRegistry or use createDefaultIntegrationSpecRegistry().
Bind tenant connections and secret references outside this package.
Resolve secrets and execute guarded runtime calls through IntegrationCallGuard.
Default shipped provider specs are additive catalog entries. Most providers in
createDefaultIntegrationSpecRegistry() advertise both managed and byok, while BYOK-only providers carry explicit credential-manifest exemption metadata for unsupported managed mode. Consumers can still narrow a concrete tenant connection through app-config slot allowedModes or connection ownership mode validation.
Publish and query the integration catalog
The production registry is split into two layers:
Static catalog definitions describe what can appear in an integration catalog: shipped integration specs, integration package wrappers, provider implementation manifests, and explicit exception records for helper modules that are not user-facing integrations.
Tenant overlays describe runtime state outside this package: catalog availability (available, hidden, disabled, or exception) and connection activation (not-connected, active, inactive, pending,
disabled, error, or unknown).
Keep these layers separate. Static definitions must be deterministic metadata only; they must not contain tenant connection state, raw credentials, provider SDK clients, network calls, filesystem discovery, or app/example imports. Apps and bundles should join catalog definitions with overlays through provider-neutral view records before rendering or filtering.
When adding a provider:
Add or update the IntegrationSpec and register it in
createDefaultIntegrationSpecRegistry() when the contracts package owns the spec.
Add package-local catalog contribution metadata in the implementation package when the record represents a provider implementation or package wrapper.
Include managed/BYOK support metadata for every user-facing record. If a module is helper-only or a mode is unsupported, add an explicit exception rationale rather than letting guard checks infer intent.
Run the registry completeness guard plus the package tests/typecheck before promotion.
The expected verification set for registry changes is:
bash
bun test packages/platform/delivery/contracts-integrations/src/integrations/catalog.test.ts packages/platform/delivery/contracts-integrations/src/integrations/providers/providers.test.ts packages/platform/delivery/contracts-integrations/src/integrations/providers/provider-modes-coverage.test.ts
bun run --cwd packages/platform/delivery/contracts-integrations typecheck
bun scripts/check-integration-registry-completeness.ts
Delta-aware providers should attach this state before runtime sync starts so callers can renew leases, resume from provider cursors/watermarks, preserve webhook expiry, dedupe provider events, run idempotently, replay from checkpoints, and skip tombstoned source records.
Bind LinkedIn capabilities without overstating access
Import LinkedIn contracts from the aggregate subpath or a narrow capability subpath:
ts
import type {
LinkedInCapabilityDecision,
LinkedInCommunityProvider,
LinkedInInstallation,
} from "@lssm-tech/lib.contracts-integrations/integrations/linkedin";
The LinkedIn provider family registers separate member, community, communications, Sales Navigator, and marketing product specs. A shared
LinkedInInstallation owns developer-app approvals, OAuth grants, resources, child connections, and capability/certification evidence. Tokens remain in a secret provider and contracts expose only LinkedInCredentialReference.
Always discover capability access before dispatch. Restricted LinkedIn products remain approval_required until the exact developer application, product, scopes, actor role, resource, and agreement are evidenced. Fixture certification is operation- and effect-scoped; a certified read never certifies a write or spend operation. These contracts describe official LinkedIn APIs only and do not permit scraping, cookie authentication, or browser automation.
API map
Spec model and registries
IntegrationSpec: provider-agnostic contract for a shipped or custom integration.
IntegrationSpecRegistry: registry for integration specs with category-based lookup.
defineIntegration: helper for authoring specs.
makeIntegrationSpecKey: canonical key formatter for spec identity.
createDefaultIntegrationSpecRegistry: registry builder for shipped provider specs.
Narrow identity, community, messaging, sales, analytics,
advertising, and webhooks subpaths support capability-only consumers.
operation-catalog gives every stable operation exact capability, effect, transport, and query/command/event metadata, while
LINKEDIN_OPERATION_PORT_METHODS proves each operation has a provider port.
sync models governed delta, tombstone, checkpoint, and backfill flows;
host models bounded raw webhook requests, replay windows, complete subscription-to-tenant binding, and host-neutral OAuth/webhook handlers.
integrations/providers/communication-channel is the lib-owned, provider-neutral CommunicationOS compatibility port. Provider packages can implement or re-export it without importing sibling integration packages.
Product-specific specs are catalog metadata; they do not imply that a tenant or developer application has received LinkedIn product approval.
Newly registered AI and web-research providers
ai-voice.slng: SLNG API-key HTTP/WebSocket contract for TTS, STT, and voice-agent infrastructure. Public docs do not currently expose official MCP or OAuth app support.
ai-voice.gradium: Gradium REST/WebSocket contract for realtime TTS/STT. Public docs expose API-key access and Python SDK; no public JS SDK, MCP, or OAuth app surface is documented.
ai-voice.fal: Fal generative-media contract with official @fal-ai/client, REST, hosted MCP, queue, realtime, storage, and media capabilities. Public MCP auth is API-key based.
web-research.tavily: Tavily search/extract/crawl/research contract with official @tavily/core, REST, local/remote MCP, and OAuth-enabled remote MCP.
Connections, auth, transport, versioning, and BYOK
IntegrationConnection and ConnectionStatus: tenant-bound connection shape and readiness state.
IntegrationAuthConfig, findAuthConfig, supportsAuthMethod: auth contract and helpers.
IntegrationTransportConfig, findTransportConfig, supportsTransport: transport contract and helpers.
ByokKeyLifecycle and BYOK metadata/result types: key validation and rotation contracts.
IntegrationCredentialManifest and helpers from ./integrations/credentials: managed/BYOK credential requirements, env aliases, validation strategy, rotation policy, and compatibility mapping from legacy schemas.
Runtime, health, and telemetry
IntegrationCallGuard: guarded execution with secret resolution, retries, and telemetry. Exported from ./integrations/runtime.
normalizeSecretPayload: normalize text/binary/base64 payloads before writes.
Operations and provider interfaces
CRM reference reads use CrmReadProvider and CrmReadRequest to bind every page to a tenant/workspace boundary, authority evidence, legal basis, optional consent evidence, and a retention policy. Normalized projections preserve source provenance, replay evidence, dedupe/idempotency keys, and opaque cursor scope. createHubSpotCrmFixtureAdapter and
createSalesforceCrmFixtureAdapter are deterministic fixture adapters only; they perform no OAuth, network, webhook, SDK, or CRM write operations.
EmbeddingUsageReceipt records provider/model token use, request and document counts, dimensions, and an explicit recorded-or-unavailable cost state. The optional result field preserves compatibility with legacy providers.
VectorStoreProvider
EmailInboundProvider
EmailOutboundProvider
GoogleDriveProvider
ObjectStorageProvider
ProjectManagementProvider
PaymentPlatformProvider
Delta-aware provider contracts:
ProviderDeltaSyncState
ProviderDeltaEnvelope
isProviderDeltaTombstoned
ProjectManagementDeltaEntry
ProjectManagementWebhookIngestResult
The project-management port is typed on the structural ProjectManagementWork* vocabulary (object kinds, refs, status categories, sync modes, field groups, external bindings, sync conflicts, capability manifest and mutation envelope). These types are identical to the Work Sync v2 types in @lssm-tech/lib.work-spec, so values typed with either package are interchangeable. This contract layer has no runtime dependency on the work domain spec; a type-only parity test (project-management-work.test.ts, work-spec as a devDependency) fails typecheck on drift.
Social tracking contracts
integrations/social defines provider-neutral creator and content records, source provenance, 30-minute metric snapshots, UTC rollups, configurable retention, tracking targets, webhook receipts, analytics queries, and the
SocialTrackingSource, SocialTrackingStore, and SocialTrackingService
ports. The default retention policy keeps 30-minute observations for 90 days, hourly rollups for 18 months, daily rollups for five years, and leaves weekly retention unbounded.
Official API, approved connector, and public fallback observations share the same evidence model. Missing provider metrics remain absent and collection gaps remain explicit; adapters must not synthesize zeros or historical points. Credential material stays behind opaque references and is never part of a creator, content, snapshot, analytics, or webhook record.
Payment platform contracts
integrations/providers/payments exports a provider-neutral payment platform contract with operation-level capability discovery and separate customer, payment-method, checkout, payment, subscription, invoice, dispute, payout, marketplace, and raw-body webhook slices. Mutations require tenant/actor, sandbox-or-live environment, idempotency, and an authorization decision; the decision must be unexpired and scoped to the exact tenant, actor, account, operation, resource, amount, and idempotency key. approval_required decisions must include approval evidence. The shipped PayPal catalog spec is available from integrations/providers/paypal under
payments.paypal.
Adapters must call assertPaymentMutationAuthorized before provider-side effects. It rejects denied/review, expired, scope-mismatched, and approval-required decisions without evidence with a normalized throwable
PaymentProviderError.
This is a breaking replacement for PaymentsProvider: migrate implementations to PaymentPlatformProvider, replace Money.amount with
MoneyAmount.amountMinor, return normalized PaymentPage resources, and bind every mutation to PaymentMutationContext.
Public surface
The root barrel re-exports common integration contracts from:
spec and registry helpers
auth, binding, BYOK, connection, transport, and versioning
health helpers
operations contracts
provider interfaces
selected domain contracts such as health, meeting-recorder, and openbanking
Runtime and secret-management helpers live under ./integrations/runtime and ./integrations/secrets*.
The exhaustive public surface lives under ./integrations/* in package.json.
Use the README as a guide to the main clusters. Use package.json as the authoritative export map for all subpaths, including the many provider and domain-specific entrypoints.
Operational semantics and gotchas
IntegrationCallGuard fails fast when a slot is missing or a connection is not ready.
IntegrationCallGuard defaults to 3 attempts with 250 ms backoff.
Retry only happens when shouldRetry() returns true; the default implementation looks for a truthy retryable field on the error.
IntegrationSpec carries config and secret schemas, but raw secrets live behind secretRef and SecretProvider.
SecretProviderManager delegates in descending priority order and preserves registration order for ties.
resolveApiVersion() uses connection override first, then policy default.
IntegrationHealthService.check() returns structured results instead of throwing health failures upward.
Registry filters only match specs that explicitly declare auth methods, transports, version policies, or BYOK support.
Credential manifests describe required config and secret references per ownership mode; they do not carry raw credential values.
ProviderDeltaSyncState is the shared contract for sync leases, provider cursors/watermarks, webhook channel expiry, replay checkpoints, dedupe/idempotency keys, provider event IDs, and tombstones.
Gmail and Google Drive specs advertise provider.delta.watch; Drive also advertises knowledge.ingestion.drive.
This package defines contracts and shipped spec registrations. SDK-backed implementations live elsewhere.
When not to use this package
Do not use it as a provider SDK implementation layer.
Do not use it as the secret storage backend itself.
Do not use it as the integration persistence database layer.
Do not use it as the app-config slot/binding resolver.
Related packages
Canonical Core declarations, Kernel registries, RuntimeCore host contracts, Observability telemetry and Utils helpers supply integration contracts and operations. Documentation registers through the actual seeded SurfaceRuntime doc registry; Legacy forwards refer to that same registry and singleton.
@lssm-tech/lib.schema: schema types used by operation and config shapes.
@lssm-tech/integration.runtime: runtime composition layer built on top of these contracts.
@lssm-tech/integration.providers-impls: SDK-backed provider implementations for many of these interfaces.
@lssm-tech/lib.knowledge: major consumer of embedding, vector-store, email, storage, and LLM provider interfaces.
Local commands
bun run lint:check
bun run typecheck
bun test
Matrix and bridge-aware messaging
messaging.matrix models Matrix as an additive managed/BYOK messaging integration. It declares matrix-js-sdk as the preferred SDK transport with REST/WebSocket hints, Matrix homeserver and room configuration, bearer token secrets, and optional bridge metadata.
Bridge metadata is descriptive and provider-agnostic: it can explain that Matrix rooms bridge to Slack, Telegram, WhatsApp, Discord, email, SMS, IRC, XMPP, or other channels, but it must not replace direct provider specs when first-party integrations are configured. This package does not provision homeservers, automate hosted provider signup, install bridges, or endorse a hosting provider.
Sales intelligence providers
crm.fullenrich: FullEnrich contact enrichment, reverse-email lookup, people/company search, credits, API-key validation, webhook-first async result handling, and remote MCP metadata. REST calls are BYOK and must resolve API keys through runtime secret providers; remote MCP is represented as OAuth metadata at https://mcp.fullenrich.com/mcp without proxying OAuth secrets.
crm.sillage: Sillage GTM intelligence metadata for Slack/CRM buying-signal and account-intelligence workflows. Executable operations remain disabled with SILLAGE_VENDOR_DOCS_REQUIRED until official API, MCP, SDK, webhook, and auth docs or vendor-confirmed schemas exist.
Sales-intelligence operation contracts are exported from @lssm-tech/lib.contracts-integrations/integrations/sales-intelligence. FullEnrich operation keys are additive and keep REST paths derived from defaultRestPath; long generated MCP names use explicit short transport.mcp.toolName overrides while keeping operation keys stable.
Voice STT contracts include optional transcribeMedia support for encoded audio containers, explicit timestamp requests, cancellation/deadlines and model identity. Implementers must declare unsupported media/options through failure rather than inventing sample rates, timestamps or speaker identities.
The LinkedIn native-publication subpath describes reviewed native post materialization without credentials. Member/organization authors, media variants and revision identity remain explicit; the concrete adapter implements the core scoped V2 publication port.
integrations/social/x-publication owns versioned native X thread records and their atomic store port. Scoped request digests bind tenant/account/author/publication key, part index and native payload. Confirmations preserve reply/media facts and authority; unknown parts cannot transition back to pending.
The additive integrations/social/x-upload and x-upload-state contracts describe qualified asset manifests, sequential chunk execution, native processing/expiry and durable store/authority ports. xUploadedAsset projects only a scoped, ready, unexpired native attachment. Runtime adapters must verify bytes and never resend uncertain writes.
integrations/linkedin/media adds optional typed native media methods and transient image/video upload sessions. Media upload/read have independent capability IDs and initialize/transfer/finalize/get operation identities; existing post authority does not cover them. Signed upload material belongs in secret storage, not public job records.
LinkedIn media-session, media-job and media-job-state own private-session vault ports, durable job/claim contracts and ready-media projection. Session references bind the exact scope, content and backend version. Job histories carry no signed upload URLs or upload tokens. Native processing availability and upload-session expiry are distinct.
Bot capture authority receives the exact attempted request: start includes its immutable meeting URL/media/schedule intent; existing-bot actions include providerCaptureId; reconciliation includes the durable idempotencyKey. The host must compare these supplied values with its owner-scoped persisted capture ledger before invoking the effect. Supplied values are evidence to verify, never authority. Attendee snapshots start/reconcile inputs before asynchronous authorization. This contract does not install a permissive default or constitute deployment qualification.
AsyncMediaGeneration.artifactRefs is an immutable ordered prefix of completed imports and may be partial while generation ingestion is running.
AsyncMediaGeneration optionally records expectedOutputCount when completed provider outputs are first observed. The count is immutable thereafter and bounded to 100 outputs.
AsyncMediaGenerationReader defines authorized durable inspection without provider polling or submission.
Read-only object storage
ObjectStorageReadProvider and StorageObjectReadInput add a narrow object-read capability with optional cancellation. Existing ObjectStorageProvider contracts remain unchanged. A reader exposes no mutation, list or signed-URL authority; implementations document cancellation and credential-scope support explicitly.
Canonical health and openbanking ownership
Existing integrations/health and integrations/openbanking contract, model, feature, capability and telemetry subpaths forward to the personal-health-spec and personal-finance-spec domain owners. Provider ports and integration readiness guards stay here. Operation keys, IO, policy, telemetry and registration order remain unchanged; existing imports continue to work.
Complete provider-neutral analytics request, reader and writer contracts are owned by Observability. Existing Integration provider leaves forward to the same full declarations. Concrete adapters and query execution remain with their existing implementations.
Meeting recorder and openbanking capability declarations and registration helpers are available at /capabilities/meeting-recorder and /capabilities/openbanking. Historical ContractSpec imports retain the same objects and registry identity.
Declared capabilities.
Lib Contracts Integrations
Integration contract definitions for external services
Use it to
Adopt integration contract definitions for external services
Requires
TypeScript
Choose another boundary when
The @lssm-tech/lib.contracts-integrations package constraints do not match the target runtime or platform.
These are package-manifest entry points. Named symbols listed above come from the capability catalogue; this is not an exhaustive TypeScript symbol reference.