integration.communication-os-client

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.