{"id":"@lssm-tech/integration.communication-os-client","slug":"integration.communication-os-client","name":"@lssm-tech/integration.communication-os-client","version":"2.0.4","path":"packages/integrations/communication-os-client","manifestPath":"packages/integrations/communication-os-client/package.json","manifestBlobSha":"b7fb39d6a420c302d1fe435dd3fe7fa08e318547","layer":"integrations","physicalArea":null,"primaryArea":"communication-and-notifications","classification":{"privateDeclared":null,"catalogFamily":"runtime","catalogKind":"integration","catalogStatus":"active","adoptionMode":"adoptable","stability":"experimental"},"description":"Browser-safe typed REST and realtime client for CommunicationOS.","descriptionOrigin":"package.json","catalog":{"family":"runtime","kind":"integration","status":"active","adoptionMode":"adoptable","stability":"experimental","platforms":["server"],"runtimes":["node"],"entrypoints":["."],"documentation":[{"title":"Integration Communication Os Client documentation","url":"https://www.npmjs.com/package/%40lssm-tech%2Fintegration.communication-os-client","kind":"readme"}],"examples":[],"replacements":[],"capabilities":[{"id":"package.lssm.tech.integration.communication.os.client","title":"Integration Communication Os Client","description":"Browser-safe typed REST and realtime client for CommunicationOS.","status":"active","useCases":["Adopt browser-safe typed rest and realtime client for communicationos"],"aliases":["integration","communication","client"],"pythonEquivalents":[],"canonicalImports":[{"from":"@lssm-tech/integration.communication-os-client","symbols":[]}],"constraints":{"platforms":["server"],"runtimes":["node"],"avoidWhen":["The @lssm-tech/integration.communication-os-client package constraints do not match the target runtime or platform."],"requires":["TypeScript"]},"alternatives":[],"relationships":[],"resolutionPriority":50}]},"canonicalImports":[{"capabilityId":"package.lssm.tech.integration.communication.os.client","from":"@lssm-tech/integration.communication-os-client","symbols":[]}],"scripts":{"build":"contractspec-bun-build build","build:bundle":"contractspec-bun-build transpile","build:types":"contractspec-bun-build types","lint:check":"node ../../../scripts/biome.cjs check .","test":"bun test","typecheck":"tsgo --noEmit"},"scriptStatus":"complete pinned manifest","dependencies":{"@lssm-tech/lib.communication-spec":"workspace:^"},"devDependencies":{"@lssm-tech/tool.bun":"workspace:*","@lssm-tech/tool.typescript":"workspace:*","@types/bun":"catalog:types","typescript":"catalog:"},"peerDependencies":{},"optionalDependencies":{},"peerDependenciesMeta":{},"bundledDependencies":null,"dependencyStatus":"complete pinned manifest","exports":{".":"./src/index.ts","./community-intelligence":"./src/community-intelligence.ts","./community-intelligence-types":"./src/community-intelligence-types.ts","./customer-live-chat":"./src/customer-live-chat.ts","./latest-request":"./src/latest-request.ts","./realtime-subscription":"./src/realtime-subscription.ts","./session-engine":"./src/session-engine.ts","./workspace-projection":"./src/workspace-projection.ts"},"publishExports":{".":{"types":"./dist/index.d.ts","browser":"./dist/browser/index.js","bun":"./dist/index.js","node":"./dist/node/index.js","default":"./dist/index.js"},"./community-intelligence":{"types":"./dist/community-intelligence.d.ts","browser":"./dist/browser/community-intelligence.js","bun":"./dist/community-intelligence.js","node":"./dist/node/community-intelligence.js","default":"./dist/community-intelligence.js"},"./community-intelligence-types":{"types":"./dist/community-intelligence-types.d.ts","browser":"./dist/browser/community-intelligence-types.js","bun":"./dist/community-intelligence-types.js","node":"./dist/node/community-intelligence-types.js","default":"./dist/community-intelligence-types.js"},"./customer-live-chat":{"types":"./dist/customer-live-chat.d.ts","browser":"./dist/browser/customer-live-chat.js","bun":"./dist/customer-live-chat.js","node":"./dist/node/customer-live-chat.js","default":"./dist/customer-live-chat.js"},"./latest-request":{"types":"./dist/latest-request.d.ts","browser":"./dist/browser/latest-request.js","bun":"./dist/latest-request.js","node":"./dist/node/latest-request.js","default":"./dist/latest-request.js"},"./realtime-subscription":{"types":"./dist/realtime-subscription.d.ts","browser":"./dist/browser/realtime-subscription.js","bun":"./dist/realtime-subscription.js","node":"./dist/node/realtime-subscription.js","default":"./dist/realtime-subscription.js"},"./session-engine":{"types":"./dist/session-engine.d.ts","browser":"./dist/browser/session-engine.js","bun":"./dist/session-engine.js","node":"./dist/node/session-engine.js","default":"./dist/session-engine.js"},"./workspace-projection":{"types":"./dist/workspace-projection.d.ts","browser":"./dist/browser/workspace-projection.js","bun":"./dist/workspace-projection.js","node":"./dist/node/workspace-projection.js","default":"./dist/workspace-projection.js"}},"types":"./dist/index.d.ts","files":["dist","README.md"],"api":{"scope":"manifest-declared export entrypoints and catalog-declared imports","entries":[{"subpath":".","importPath":"@lssm-tech/integration.communication-os-client","target":"./src/index.ts","targets":[{"conditions":[],"target":"./src/index.ts","sourcePath":"packages/integrations/communication-os-client/src/index.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/index.ts","sourceStatus":"verified source file"}]},{"subpath":"./community-intelligence","importPath":"@lssm-tech/integration.communication-os-client/community-intelligence","target":"./src/community-intelligence.ts","targets":[{"conditions":[],"target":"./src/community-intelligence.ts","sourcePath":"packages/integrations/communication-os-client/src/community-intelligence.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/community-intelligence.ts","sourceStatus":"verified source file"}]},{"subpath":"./community-intelligence-types","importPath":"@lssm-tech/integration.communication-os-client/community-intelligence-types","target":"./src/community-intelligence-types.ts","targets":[{"conditions":[],"target":"./src/community-intelligence-types.ts","sourcePath":"packages/integrations/communication-os-client/src/community-intelligence-types.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/community-intelligence-types.ts","sourceStatus":"verified source file"}]},{"subpath":"./customer-live-chat","importPath":"@lssm-tech/integration.communication-os-client/customer-live-chat","target":"./src/customer-live-chat.ts","targets":[{"conditions":[],"target":"./src/customer-live-chat.ts","sourcePath":"packages/integrations/communication-os-client/src/customer-live-chat.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/customer-live-chat.ts","sourceStatus":"verified source file"}]},{"subpath":"./latest-request","importPath":"@lssm-tech/integration.communication-os-client/latest-request","target":"./src/latest-request.ts","targets":[{"conditions":[],"target":"./src/latest-request.ts","sourcePath":"packages/integrations/communication-os-client/src/latest-request.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/latest-request.ts","sourceStatus":"verified source file"}]},{"subpath":"./realtime-subscription","importPath":"@lssm-tech/integration.communication-os-client/realtime-subscription","target":"./src/realtime-subscription.ts","targets":[{"conditions":[],"target":"./src/realtime-subscription.ts","sourcePath":"packages/integrations/communication-os-client/src/realtime-subscription.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/realtime-subscription.ts","sourceStatus":"verified source file"}]},{"subpath":"./session-engine","importPath":"@lssm-tech/integration.communication-os-client/session-engine","target":"./src/session-engine.ts","targets":[{"conditions":[],"target":"./src/session-engine.ts","sourcePath":"packages/integrations/communication-os-client/src/session-engine.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/session-engine.ts","sourceStatus":"verified source file"}]},{"subpath":"./workspace-projection","importPath":"@lssm-tech/integration.communication-os-client/workspace-projection","target":"./src/workspace-projection.ts","targets":[{"conditions":[],"target":"./src/workspace-projection.ts","sourcePath":"packages/integrations/communication-os-client/src/workspace-projection.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/workspace-projection.ts","sourceStatus":"verified source file"}]}],"entryCount":8,"namedSymbolCoverage":"catalog declarations only; exhaustive TypeScript symbols not extracted","installationStatus":"not verified"},"docsLinks":[{"title":"Integration Communication Os Client documentation","url":"https://www.npmjs.com/package/%40lssm-tech%2Fintegration.communication-os-client","kind":"readme","pinnedUrl":null,"sourceStatus":"declared link; destination not verified"}],"sourceUrls":{"package":"https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client","manifest":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/package.json","readme":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/README.md","guide":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.communication-os-client.txt"},"readme":{"status":"available","body":"# CommunicationOS client\n\nBrowser-safe typed client for the central CommunicationOS REST and realtime\nsurfaces. Authentication is injected; service secrets and raw provider\ncredentials never enter this package.\n\nRoom list projections include `messageCount` and optional `lastActivityAt` as\nauthorized summary metadata. Hosts can render complete conversation ledgers\nwithout fetching message bodies for every room; only the selected room needs a\nmessage-list request.\n\nThe root client exposes typed `bootstrapScope`, `listSpaces`, `listRooms`,\n`listMessages`, `sendMessage`, `listEvents`, and single-use realtime-ticket\nhelpers. Effect-bearing requests carry caller-supplied idempotency keys and\nalways omit browser cookies.\n\nThe `/v2/community` surface exposes typed Discord installation authorization,\npolicy update, revocation, coverage, insight, staff-scorecard, and Kaizen-digest\nmethods. Tenant, workspace, space, actor, and trust-zone authority remain\nserver-derived. Mutation idempotency keys are sent only in the\n`idempotency-key` header, and public installation responses intentionally omit\ncredential references.\n\nMessage search and send use the canonical\n`communication.message.search@3.0.0` and\n`communication.message.send@3.0.0` REST operations. The authenticated host\nderives tenant and author authority; callers select only an authorized\nworkspace, space, and room. The API must be upgraded before this client so the\n`/communication/message/*/v3.0.0` routes are available during rollout.\n\n`uploadAttachment`, attachment-aware `sendMessage`, and\n`downloadAttachment` keep file access behind the authenticated, scope-bound API.\nMessages expose only opaque file metadata; provider and storage URLs are never\npart of the client contract.\n\n`resolveAuthorizedThreadRoomId` keeps canonical thread deep links distinct from\nroom identifiers. It returns a room only when an active server projection binds\nthe opaque external thread reference to a room already present in the caller's\nauthorized room list; inactive, missing, and cross-scope-looking references fail\nclosed.\n\n`startProviderOAuth(scope, { network, placement, providerKey, returnPath })`\nstarts the official provider flow without accepting tokens or vault references\nfrom the public UI. `providerKey` selects a provider inside a network (`google`\nor `microsoft` for `email`, `microsoft` for `teams`); without it the API uses\nthe first configured provider of the network. Provider callbacks return to the\norigin the API maps to the session's host-exchange issuer\n(`COMMUNICATION_OS_OAUTH_HOST_ORIGINS`, for example CompanyOS at\n`/companyos/communication-os/connections`) or to the\nstandalone shell, with `?oauth=connected|provider_denied&network=…`; the client\nnever receives the PKCE verifier or exchanged credentials.\n\nThreads: the v2 API groups conversations by room and exposes no separate\nthread list. Messages may carry `replyToMessageId` (reply chains inside a\nroom) and room-channel bindings may carry `externalThreadId` (a provider\nthread mirrored into a room), so hosts render one room as one thread and use\n`resolveAuthorizedThreadRoomId` for provider thread deep links.\n\n`exchangeDirectSession()` uses the first-party AuthOS cookie on web. Native\nshells pass their device-vault-backed AuthOS session token to\n`exchangeDirectSession(sessionToken)`; that transport omits cookies and sends the\nsession only in the authorization header.\n\nCompanyOS-owned native shells configure `nativeSessionExchangeUrl` to the\nprotected CompanyOS BFF. The BFF verifies the device bearer, derives the active\norganization scope, and performs the server-secret host assertion exchange;\nthe client receives only the short-lived CommunicationOS grant.\n\nCanonical v2 request, result, error, cursor, and projection DTOs are re-exported\nfrom the client. Journal, encrypted-envelope, and realtime payloads are\nJSON-safe `CommunicationJsonObjectDto` values; unsupported provider behavior is\nrepresented by the explicit `unsupported_feature` error code.\n\nRealtime reconnect retains a bounded event-ID window in addition to the server\ncursor. A gateway replay of the boundary event advances the cursor but does not\nnotify the host twice, preventing duplicate refresh or mutation effects.\n\n## Session engine\n\n`@lssm-tech/integration.communication-os-client/session-engine` is the\nReact-free client session engine shared by the standalone web/PWA, desktop\nand mobile shells. `createCommunicationOsSessionEngine` owns:\n\n- grant exchange through the first-party cookie (web) or a vault-held native\n  session token, with `refreshSkewMs` re-exchange for web and fixed native\n  grants whose `requestHeaders()` fail closed once expired;\n- scoped bearer headers for sibling surfaces (forms, meetings, support);\n- workspace load with initial room precedence (authorized requested room,\n  then an actively bound thread room, then an authorized stored room, then the\n  bootstrap or first room);\n- send-or-queue under one idempotency key, ordered outbox replay that stops at\n  the first failure, and `createCommunicationOsDurableOutbox` for\n  principal-scoped durable storage with quarantine of malformed rows;\n- platform-neutral per-row payload sealing for durable outboxes:\n  `CommunicationOsOutboxPayloadCipher`, the scope-bound AES-GCM additional data\n  (`communicationOsOutboxAdditionalData`: tenant, workspace, space, principal,\n  room, idempotency key), the `v2.<iv>.<ciphertext+tag>` envelope codec and a\n  strict, `TextDecoder`-free UTF-8 codec. Hosts keep the crypto adapter\n  (WebCrypto on desktop, expo-crypto on mobile) and the key custody;\n- governed-work transitions, including identity-review approve/reject mapped\n  to merge/reject.\n- `BrowserMessageOutbox`, a bounded (50 rows per key), scope-keyed browser\n  storage outbox that never throws on blocked or full storage and stores only\n  message bodies and ids, with `browserSessionOutbox` for the engine; and\n  `classifyCommunicationOsSendFailure`, which maps a failed `message.send` to\n  `denied` (403, terminal), `unauthorized` (401), `rejected` (other 4xx) or\n  `transient` (network, 408/425/429, 5xx).\n\nCapabilities come only from the server-issued grant. On a 401 the engine\ndrops its grant and, when the host provides `onUnauthorized`, lets the host\nrevoke its stored credential. Hosts keep React state, storage keys, timers,\nwindow and network listeners, file encoding and redirects.\n\n## Workspace projection\n\n`@lssm-tech/integration.communication-os-client/workspace-projection` loads the\nread model embedded hosts render: `loadCommunicationOsLiveRoom` binds the\nscope and bootstrap within a read deadline (default 4 s), loads spaces, rooms,\nconnections, bindings, contacts, governed work and events as optional\nprojections, keeps an authorized requested room, and reports\n`threadCollectionState` / `messageCollectionState` as `partial` instead of an\nempty success when a projection stalls. Hosts inject the client (transport and\norigin) and the scope loader.\n","sourcePath":"packages/integrations/communication-os-client/README.md","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/README.md","blobSha":"63cbfbec468ccb7369c4770540b40b88ece9444b","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","origin":"README recovered byte-for-byte from pinned aggregate guide","integrity":"exact Git blob match","executionStatus":"not executed"},"provenance":{"repository":"lssm-tech/contractspec","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","manifestOrigin":"pinned GitHub manifest fetch","manifestComplete":true,"publicationPolicyApplied":false},"areaSlug":"communication-and-notifications","areaTitle":"Communication and notifications","displayName":"integration.communication-os-client","runtimes":["node"],"platforms":["server"],"kind":"integration","scope":"Package manifest","canonicalRoute":"/docs/packages/integration.communication-os-client/","contextUrl":"/docs/packages/integration.communication-os-client.context.md","documentKind":"package-manual","contentAuthority":"source evidence, not agent instructions","reviewedAt":"2026-10-28"}