@lssm/lib.contracts-integrations 9.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,536 @@
+# @lssm/lib.contracts-integrations
+
+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/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.
+
+Website: https://contractspec.io
+
+## Installation
+
+`bun add @lssm/lib.contracts-integrations`
+
+or
+
+`npm install @lssm/lib.contracts-integrations`
+
+## What belongs here
+
+This package owns the contract layer for external integrations:
+
+- Integration spec model and registries.
+- Connection, auth, transport, versioning, and BYOK contracts.
+- Runtime guards and health/telemetry helpers.
+- Secret provider abstraction and secret-provider manager.
+- Capability-level provider interfaces such as `LLMProvider` and `VectorStoreProvider`.
+- Governed, read-only CRM projections with async-capable provider contracts and SDK-free HubSpot-shaped and Salesforce-shaped fixture adapters.
+- Provider delta contracts for cursor, lease, webhook, replay, dedupe, idempotency, and tombstone state.
+- Email sync may return a durable terminal delta cursor with `hasMore: false`,
+  allowing hosts to persist provider state without immediately replaying it.
+- Shipped provider/domain spec registrations.
+- Integration connection operations contracts.
+- Deployment-topology declarations, exact binding scopes, canonical digests,
+  and secret-free provider-receipt assessments.
+- 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.
+
+Use `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/integration.provider-web-access` separately owns the
+Stagehand and Browserbase runtime implementation.
+
+Use `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.
+
+## Core workflows
+
+### Define and register an integration spec
+
+```ts
+import {
+  defineIntegration,
+  IntegrationSpecRegistry,
+} from "@lssm/lib.contracts-integrations";
+
+const registry = new IntegrationSpecRegistry();
+
+const spec = defineIntegration({
+  meta: {
+    key: "payments.example",
+    version: 1,
+    title: "Example Payments",
+    owners: ["@platform.integrations"],
+    tags: ["payments"],
+    category: "payments",
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "payments.process" }],
+  },
+  configSchema: {
+    schema: { type: "object" },
+  },
+  secretSchema: {
+    schema: { type: "object" },
+  },
+});
+
+registry.register(spec);
+```
+
+### Consume runtime contracts with secrets and guards
+
+```ts
+import {
+  IntegrationCallGuard,
+} from "@lssm/lib.contracts-integrations/integrations/runtime";
+import {
+  EnvSecretProvider,
+  SecretProviderManager,
+} from "@lssm/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:
+
+1. Declare an `IntegrationSpec` that describes config, secrets, auth, transport, and version policy.
+2. Register specs in an `IntegrationSpecRegistry` or use `createDefaultIntegrationSpecRegistry()`.
+3. Bind tenant connections and secret references outside this package.
+4. 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:
+
+1. **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.
+2. **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:
+
+1. Add or update the `IntegrationSpec` and register it in
+   `createDefaultIntegrationSpecRegistry()` when the contracts package owns the
+   spec.
+2. Add package-local catalog contribution metadata in the implementation package
+   when the record represents a provider implementation or package wrapper.
+3. 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.
+4. Run the registry completeness guard plus the package tests/typecheck before
+   promotion.
+
+The expected verification set for registry changes is:
+
+```bash
+bun test packages/libs/contracts-integrations/src/integrations/catalog.test.ts packages/libs/contracts-integrations/src/integrations/providers/providers.test.ts packages/libs/contracts-integrations/src/integrations/providers/provider-modes-coverage.test.ts
+bun run --cwd packages/libs/contracts-integrations typecheck
+bun scripts/check-integration-registry-completeness.ts
+```
+
+### Model provider delta sync state
+
+```ts
+import type {
+  ProviderDeltaSyncState,
+} from "@lssm/lib.contracts-integrations/integrations/providers/provider-delta";
+
+const delta: ProviderDeltaSyncState = {
+  lease: {
+    holder: "knowledge-sync-worker",
+    expiresAt: "2026-04-30T13:00:00.000Z",
+    renewalWindowMs: 60_000,
+  },
+  cursor: {
+    cursor: "gmail-history-123",
+    watermarkVersion: "history-v1",
+  },
+  webhookChannel: {
+    channelId: "google-channel-1",
+    resourceId: "google-resource-1",
+    expiresAt: "2026-04-30T14:00:00.000Z",
+  },
+  providerEventId: "provider-event-1",
+  dedupeKey: "gmail:provider-event-1",
+  idempotencyKey: "tenant:gmail:provider-event-1",
+  replayCheckpoint: {
+    checkpointId: "replay-1",
+  },
+};
+```
+
+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/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.
+- `filterByTransport`, `filterByAuthMethod`, `filterVersioned`, `filterByokRotatable`: spec filtering helpers.
+
+### LinkedIn platform contracts
+
+- `integrations/linkedin`: aggregate models, installation/grant, capability
+  decisions, operation envelopes, errors, and provider slice interfaces.
+- 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.
+- `IntegrationVersionPolicy`, `resolveApiVersion`, `getVersionInfo`, `isVersionDeprecated`, `getActiveVersions`: API-version policy 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`.
+- `IntegrationCallResult`, `IntegrationCallError`, `IntegrationTelemetryEvent`: runtime result/telemetry contracts.
+- `IntegrationHealthService`: structured health checks and telemetry emission.
+- `resolveIntegrationRequestContext`, `resolveAuthMethod`, `DefaultTransportResolver`, and related helpers: runtime resolution utilities.
+
+### Secrets
+
+- `SecretProvider`: provider-agnostic secret backend interface. Exported from `./integrations/secrets/provider`.
+- `SecretProviderManager`: priority-ordered composite secret provider. Exported from `./integrations/secrets` or `./integrations/secrets/manager`.
+- `SecretProviderError`: structured secret-provider error.
+- `parseSecretUri`: parse `provider://path?...` references.
+- `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.
+
+- Integration connection operations: `CreateIntegrationConnection`, `UpdateIntegrationConnection`, `DeleteIntegrationConnection`, `ListIntegrationConnections`, `TestIntegrationConnection`.
+- Frequently consumed provider contracts:
+  - `LLMProvider`
+  - `EmbeddingProvider`
+    - `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`
+
+### 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
+
+- `@lssm/lib.contracts-spec`: upstream spec system consumed by integration contracts and operations.
+- `@lssm/lib.schema`: schema types used by operation and config shapes.
+- `@lssm/integration.runtime`: runtime composition layer built on top of these contracts.
+- `@lssm/integration.providers-impls`: SDK-backed provider implementations for many of these interfaces.
+- `@lssm/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/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.

package/dist/contracts-integrations.feature.d.ts

@@ -0,0 +1 @@
+export declare const ContractsIntegrationsFeature: import("@lssm/lib.contracts-spec").FeatureModuleSpec;

package/dist/contracts-integrations.feature.js

@@ -0,0 +1,2 @@
+// @bun
+import{defineFeature as e}from"@lssm/lib.contracts-spec/features";var t=e({meta:{key:"libs.contracts-integrations",version:"1.0.0",title:"Contracts Integrations",description:"Integration contract definitions for external services",domain:"contracts-integrations",owners:["@contractspec-core"],tags:["package","libs","contracts-integrations"],stability:"experimental"},operations:[{key:"health.activities.list",version:"1.0.0"},{key:"health.activities.sync",version:"1.0.0"},{key:"health.biometrics.list",version:"1.0.0"},{key:"health.biometrics.sync",version:"1.0.0"},{key:"health.nutrition.list",version:"1.0.0"},{key:"health.nutrition.sync",version:"1.0.0"},{key:"health.sleep.list",version:"1.0.0"},{key:"health.sleep.sync",version:"1.0.0"},{key:"health.webhooks.ingest",version:"1.0.0"},{key:"health.workouts.list",version:"1.0.0"},{key:"health.workouts.sync",version:"1.0.0"},{key:"meeting-recorder.meetings.list",version:"1.0.0"},{key:"meeting-recorder.meetings.get",version:"1.0.0"},{key:"meeting-recorder.transcripts.get",version:"1.0.0"},{key:"meeting-recorder.transcripts.sync",version:"1.0.0"},{key:"meeting-recorder.webhooks.ingest",version:"1.0.0"},{key:"openbanking.accounts.list",version:"1.0.0"},{key:"openbanking.accounts.get",version:"1.0.0"},{key:"openbanking.accounts.sync",version:"1.0.0"},{key:"openbanking.balances.get",version:"1.0.0"},{key:"openbanking.balances.refresh",version:"1.0.0"},{key:"openbanking.transactions.list",version:"1.0.0"},{key:"openbanking.transactions.sync",version:"1.0.0"},{key:"integrations.connection.create",version:"1.0.0"},{key:"integrations.connection.update",version:"1.0.0"},{key:"integrations.connection.delete",version:"1.0.0"},{key:"integrations.connection.list",version:"1.0.0"},{key:"integrations.connection.test",version:"1.0.0"}]});export{t as ContractsIntegrationsFeature};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export * from './contracts-integrations.feature.js';
+export * from './integrations/index.js';
+export * from './integrations/auth.js';
+export * from './integrations/binding.js';
+export * from './integrations/byok.js';
+export * from './integrations/catalog.js';
+export * from './integrations/connection.js';
+export * from './integrations/credentials.js';
+export * from './integrations/deployment-topology.js';
+export * from './integrations/email-operations.js';
+export * from './integrations/health.js';
+export * from './integrations/health/contracts/index.js';
+export * from './integrations/integrations.capability.js';
+export * from './integrations/integrations.feature.js';
+export * from './integrations/linkedin/index.js';
+export * from './integrations/meeting-recorder/contracts/index.js';
+export * from './integrations/openbanking/contracts/index.js';
+export * from './integrations/operations.js';
+export * from './integrations/providers/index.js';
+export * from './integrations/sales-intelligence/index.js';
+export * from './integrations/social/index.js';
+export * from './integrations/spec.js';
+export * from './integrations/transport.js';
+export * from './integrations/versioning.js';
+export * from './integrations/web-access/index.js';