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 [email protected] and [email protected] 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, returnPath }) starts the official provider flow without accepting tokens or vault references from the public UI. Provider callbacks return directly to the configured standalone shell; the client never receives the PKCE verifier or exchanged credentials.

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.