# @lssm-tech/integration.communication-os-client

Browser-safe typed REST and realtime client for CommunicationOS.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `2.0.4`
- Package path: `packages/integrations/communication-os-client`
- Manifest path: `packages/integrations/communication-os-client/package.json`
- Manifest Git blob: `b7fb39d6a420c302d1fe435dd3fe7fa08e318547`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/integration.communication-os-client](https://lssm.co/docs/packages/integration.communication-os-client/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.communication-os-client.txt)

## Package metadata

```json
{
  "layer": "integrations",
  "physicalArea": null,
  "primaryArea": "communication-and-notifications",
  "classification": {
    "privateDeclared": null,
    "catalogFamily": "runtime",
    "catalogKind": "integration",
    "catalogStatus": "active",
    "adoptionMode": "adoptable",
    "stability": "experimental"
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: not declared; publication is not verified.

Primary area: [Communication and notifications](https://lssm.co/docs/areas/communication-and-notifications/)

## Package guide

```json
{
  "status": "available",
  "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"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# CommunicationOS client

Browser-safe typed client for the central CommunicationOS REST and realtime
surfaces. Authentication is injected; service secrets and raw provider
credentials never enter this package.

Room list projections include `messageCount` and optional `lastActivityAt` as
authorized summary metadata. Hosts can render complete conversation ledgers
without fetching message bodies for every room; only the selected room needs a
message-list request.

The root client exposes typed `bootstrapScope`, `listSpaces`, `listRooms`,
`listMessages`, `sendMessage`, `listEvents`, and single-use realtime-ticket
helpers. Effect-bearing requests carry caller-supplied idempotency keys and
always omit browser cookies.

The `/v2/community` surface exposes typed Discord installation authorization,
policy update, revocation, coverage, insight, staff-scorecard, and Kaizen-digest
methods. Tenant, workspace, space, actor, and trust-zone authority remain
server-derived. Mutation idempotency keys are sent only in the
`idempotency-key` header, and public installation responses intentionally omit
credential references.

Message search and send use the canonical
`communication.message.search@3.0.0` and
`communication.message.send@3.0.0` REST operations. The authenticated host
derives tenant and author authority; callers select only an authorized
workspace, space, and room. The API must be upgraded before this client so the
`/communication/message/*/v3.0.0` routes are available during rollout.

`uploadAttachment`, attachment-aware `sendMessage`, and
`downloadAttachment` keep file access behind the authenticated, scope-bound API.
Messages expose only opaque file metadata; provider and storage URLs are never
part of the client contract.

`resolveAuthorizedThreadRoomId` keeps canonical thread deep links distinct from
room identifiers. It returns a room only when an active server projection binds
the opaque external thread reference to a room already present in the caller's
authorized room list; inactive, missing, and cross-scope-looking references fail
closed.

`startProviderOAuth(scope, { network, placement, providerKey, returnPath })`
starts the official provider flow without accepting tokens or vault references
from the public UI. `providerKey` selects a provider inside a network (`google`
or `microsoft` for `email`, `microsoft` for `teams`); without it the API uses
the first configured provider of the network. Provider callbacks return to the
origin the API maps to the session's host-exchange issuer
(`COMMUNICATION_OS_OAUTH_HOST_ORIGINS`, for example CompanyOS at
`/companyos/communication-os/connections`) or to the
standalone shell, with `?oauth=connected|provider_denied&network=…`; the client
never receives the PKCE verifier or exchanged credentials.

Threads: the v2 API groups conversations by room and exposes no separate
thread list. Messages may carry `replyToMessageId` (reply chains inside a
room) and room-channel bindings may carry `externalThreadId` (a provider
thread mirrored into a room), so hosts render one room as one thread and use
`resolveAuthorizedThreadRoomId` for provider thread deep links.

`exchangeDirectSession()` uses the first-party AuthOS cookie on web. Native
shells pass their device-vault-backed AuthOS session token to
`exchangeDirectSession(sessionToken)`; that transport omits cookies and sends the
session only in the authorization header.

CompanyOS-owned native shells configure `nativeSessionExchangeUrl` to the
protected CompanyOS BFF. The BFF verifies the device bearer, derives the active
organization scope, and performs the server-secret host assertion exchange;
the client receives only the short-lived CommunicationOS grant.

Canonical v2 request, result, error, cursor, and projection DTOs are re-exported
from the client. Journal, encrypted-envelope, and realtime payloads are
JSON-safe `CommunicationJsonObjectDto` values; unsupported provider behavior is
represented by the explicit `unsupported_feature` error code.

Realtime reconnect retains a bounded event-ID window in addition to the server
cursor. A gateway replay of the boundary event advances the cursor but does not
notify the host twice, preventing duplicate refresh or mutation effects.

## Session engine

`@lssm-tech/integration.communication-os-client/session-engine` is the
React-free client session engine shared by the standalone web/PWA, desktop
and mobile shells. `createCommunicationOsSessionEngine` owns:

- grant exchange through the first-party cookie (web) or a vault-held native
  session token, with `refreshSkewMs` re-exchange for web and fixed native
  grants whose `requestHeaders()` fail closed once expired;
- scoped bearer headers for sibling surfaces (forms, meetings, support);
- workspace load with initial room precedence (authorized requested room,
  then an actively bound thread room, then an authorized stored room, then the
  bootstrap or first room);
- send-or-queue under one idempotency key, ordered outbox replay that stops at
  the first failure, and `createCommunicationOsDurableOutbox` for
  principal-scoped durable storage with quarantine of malformed rows;
- platform-neutral per-row payload sealing for durable outboxes:
  `CommunicationOsOutboxPayloadCipher`, the scope-bound AES-GCM additional data
  (`communicationOsOutboxAdditionalData`: tenant, workspace, space, principal,
  room, idempotency key), the `v2.<iv>.<ciphertext+tag>` envelope codec and a
  strict, `TextDecoder`-free UTF-8 codec. Hosts keep the crypto adapter
  (WebCrypto on desktop, expo-crypto on mobile) and the key custody;
- governed-work transitions, including identity-review approve/reject mapped
  to merge/reject.
- `BrowserMessageOutbox`, a bounded (50 rows per key), scope-keyed browser
  storage outbox that never throws on blocked or full storage and stores only
  message bodies and ids, with `browserSessionOutbox` for the engine; and
  `classifyCommunicationOsSendFailure`, which maps a failed `message.send` to
  `denied` (403, terminal), `unauthorized` (401), `rejected` (other 4xx) or
  `transient` (network, 408/425/429, 5xx).

Capabilities come only from the server-issued grant. On a 401 the engine
drops its grant and, when the host provides `onUnauthorized`, lets the host
revoke its stored credential. Hosts keep React state, storage keys, timers,
window and network listeners, file encoding and redirects.

## Workspace projection

`@lssm-tech/integration.communication-os-client/workspace-projection` loads the
read model embedded hosts render: `loadCommunicationOsLiveRoom` binds the
scope and bootstrap within a read deadline (default 4 s), loads spaces, rooms,
connections, bindings, contacts, governed work and events as optional
projections, keeps an authorized requested room, and reports
`threadCollectionState` / `messageCollectionState` as `partial` instead of an
empty success when a projection stalls. Hosts inject the client (transport and
origin) and the scope loader.


## Declared capabilities

### Integration Communication Os Client

Capability ID: `package.lssm.tech.integration.communication.os.client`

Browser-safe typed REST and realtime client for CommunicationOS.

Use cases:

- Adopt browser-safe typed rest and realtime client for communicationos

Constraints:

```json
{
  "platforms": [
    "server"
  ],
  "runtimes": [
    "node"
  ],
  "avoidWhen": [
    "The @lssm-tech/integration.communication-os-client package constraints do not match the target runtime or platform."
  ],
  "requires": [
    "TypeScript"
  ]
}
```

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "integration",
    "communication",
    "client"
  ],
  "pythonEquivalents": [],
  "alternatives": [],
  "relationships": [],
  "resolutionPriority": 50
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.communication-os-client",
    "symbols": []
  }
]
```

## Catalogue metadata

```json
{
  "family": "runtime",
  "kind": "integration",
  "status": "active",
  "adoptionMode": "adoptable",
  "stability": "experimental",
  "platforms": [
    "server"
  ],
  "runtimes": [
    "node"
  ],
  "entrypoints": [
    "."
  ],
  "examples": [],
  "replacements": []
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[
  {
    "capabilityId": "package.lssm.tech.integration.communication.os.client",
    "from": "@lssm-tech/integration.communication-os-client",
    "symbols": []
  }
]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

- `@lssm-tech/integration.communication-os-client` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/index.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/community-intelligence` — subpath `./community-intelligence`
  - `unconditional`: `./src/community-intelligence.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/community-intelligence.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/community-intelligence-types` — subpath `./community-intelligence-types`
  - `unconditional`: `./src/community-intelligence-types.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/community-intelligence-types.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/customer-live-chat` — subpath `./customer-live-chat`
  - `unconditional`: `./src/customer-live-chat.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/customer-live-chat.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/latest-request` — subpath `./latest-request`
  - `unconditional`: `./src/latest-request.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/latest-request.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/realtime-subscription` — subpath `./realtime-subscription`
  - `unconditional`: `./src/realtime-subscription.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/realtime-subscription.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/session-engine` — subpath `./session-engine`
  - `unconditional`: `./src/session-engine.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/session-engine.ts); verified source file.

- `@lssm-tech/integration.communication-os-client/workspace-projection` — subpath `./workspace-projection`
  - `unconditional`: `./src/workspace-projection.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/communication-os-client/src/workspace-projection.ts); verified source file.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": "./dist/index.d.ts",
  "files": [
    "dist",
    "README.md"
  ],
  "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"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.communication-spec](https://lssm.co/docs/packages/lib.communication-spec/): `workspace:^`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@types/bun`: `catalog:types`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "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"
}
```

## Declared documentation links

- [Integration Communication Os Client documentation](https://www.npmjs.com/package/%40lssm-tech%2Fintegration.communication-os-client) — declared link; destination not verified.

```json
{
  "url": "https://www.npmjs.com/package/%40lssm-tech%2Fintegration.communication-os-client",
  "kind": "readme"
}
```

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/integration.communication-os-client.txt",
  "route": "/llms/integration.communication-os-client",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.communication-os-client.txt",
  "blobSha": "63cbfbec468ccb7369c4770540b40b88ece9444b",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```