chat-client: v1 prep PR 1 — AbortSignal, ChatError, options-bag, api-extractor

[vicancy]

Summary

First of two release-prep PRs for @azure/web-pubsub-chat-client v1. Scope kept deliberately small: cancellation, error uniformity, and an options-bag tidy-up — orthogonal to the upcoming model PR that will rewrite the public type re-exports.

Public-surface changes

AbortSignal across the public surface

• New base OperationOptions { abortSignal?: AbortSignalLike } and per-method aliases (StartOptions, StopOptions, GetRoomOptions, CreateRoomOptions, SendToRoomOptions, GetUserInfoOptions, AddUserToRoomOptions, RemoveUserFromRoomOptions, ListRoomMessagesOptions).
• Threaded through every public async method, invokeWithReturnType, and connection.start / LOGIN / GET_ROOM invocations inside startCore. Per-page listRoomMessages invocations are also cancellable.
• @azure/abort-controller@^2.1.2 added as an explicit dependency so AbortSignalLike is reachable from consumer typings.

Uniform ChatError

• ensureStarted, the userId getter, unknown-room rejections in sendToRoom / listRoomMessages, and the malformed-response guard in sendToConversation now throw ChatError (name: "ChatError", code: string) instead of plain Error.
• New runtime constants object KnownChatErrorCode re-exports ERRORS (matches the Azure SDK Known<Name> convention used by KnownErrorCode, etc.). Three new codes added: NotStarted, UnknownRoom, InvalidServerResponse.

Options-naming convention: <methodName>Options

• SendMessageOptions → SendToRoomOptions
• RoomMemberOperationOptions → split into AddUserToRoomOptions and RemoveUserFromRoomOptions
• Private internals (sendToConversation, manageRoomMember) use the base OperationOptions rather than synthesising one-off non-exported aliases.

Event-listener surface: drop Disposable, rename MessageEvent

api-extractor flagged two local types that collide with global names, surfacing as _2-suffixed re-exports in the report:

• MessageEvent → ChatMessageEvent — clashed with the DOM MessageEvent interface in lib.dom.d.ts.
• Disposable dropped entirely — clashed with the TypeScript 5.2+ built-in Disposable interface ({ [Symbol.dispose](): void }). Rather than rename, the unsubscribe-by-returned-callable pattern was removed. All on*() listener methods now return void and are removed via off(event, callback), matching WebPubSubClient.on/off on the underlying transport. This eliminates having two competing unsubscribe idioms on adjacent APIs (client.on(...) vs client.connection.on(...)).

// Before
const dispose = client.on("message", cb);
dispose();

// After
client.on("message", cb);
client.off("message", cb);

Additionally, ChatMessageEvent is tightened: conversationId is dropped entirely (last public reference to a concept already privatised everywhere else by 515f5f2 / a9e31a5), and roomId flips from roomId?: string to roomId: string. The previous optional was defensive coding for two anomalous paths — a forward-protocol-reservation null in the notification path, and a narrow RoomLeft-during-send race in the sender-echo path — both of which now log a warning and skip emission inside the SDK rather than pushing the undefined onto every caller. The sender-echo path still returns the msgId so the send result is unaffected.

Move trailing optional positionals into the options bag

• getRoom(roomId, withMembers, options?) → getRoom(roomId, options?: { withMembers?, abortSignal? }) — withMembers defaults to false.
• createRoom(title, members, roomId?, options?) → createRoom(title, members, options?: { roomId?, abortSignal? }).

ListRoomMessagesOptions.pageSize → maxPageSize

Matches the @azure/core-paging PageSettings.maxPageSize convention already used by listRoomMessages(...).byPage({ maxPageSize }). The same name now applies at both the iterator-level default and the per-page override, so the two knobs stop looking like unrelated concepts.

Static ChatClient.start() accepts StartOptions

The instance start(options?: StartOptions) has propagated abortSignal end-to-end since the original AbortSignal pass, but the static one-shot helper was still calling chatClient.start() with no arguments — so a stuck construct-and-start couldn't be cancelled. Construction options and start options are now kept as separate parameters on the URL/credential overloads (the wpsClient overload only takes start options since the transport is already built):

static start(clientAccessUrl, webPubSubClientOptions?: WebPubSubClientOptions, options?: StartOptions): Promise<ChatClient>
static start(credential,      webPubSubClientOptions?: WebPubSubClientOptions, options?: StartOptions): Promise<ChatClient>
static start(wpsClient,                                                        options?: StartOptions): Promise<ChatClient>

Why two parameters instead of WebPubSubClientOptions & StartOptions? Upstream WebPubSubClientOptions lives in a separate package (@azure/web-pubsub-client) on a separate release cadence, and upstream itself deliberately separates construction options from operation options (its own StartOptions interface carries abortSignal). Intersecting the two would be fragile against upstream field additions. Keeping them positional preserves the full transport-config surface (autoReconnect, reconnectRetryOptions, keep-alive intervals, etc.) without exposing the intersection.

Tighten ChatMessageEvent: drop conversationId, require roomId

The pre-existing event shape leaked the very conversationId concept that the rest of this PR is hiding (sendToConversation → private; _conversationIds → private; unknown-room is now a ChatError). It also marked roomId optional with a TODO-flavoured comment ("Undefined for non-room conversations (currently unused)"), forcing every consumer to null-check a field that always carries a value in supported paths.

// Before
interface ChatMessageEvent { conversationId: string; roomId?: string; message: ChatMessage }

// After
interface ChatMessageEvent { roomId: string; message: ChatMessage }

Notification dispatch now warns and skips if the wire frame lacks roomId, rather than handing callers an inconsistent event.

Privatize isStarted

The public isStarted getter was a thin wrapper over the private _isStarted backing field. It was removed because:

• TOCTOU-racy. if (client.isStarted) { await client.getRoom(...) } gives a false sense of safety — a stop() from another caller or a network drop between the check and the call still throws. The check cannot be made meaningful without a lock the SDK does not own.
• Redundant. Every operation method calls ensureStarted() and throws ChatError(KnownChatErrorCode.NotStarted). Callers must handle that exception anyway, so the proactive check pays no rent.
• No sibling precedent. Upstream WebPubSubClient exposes no equivalent state-check getter; it is exception-driven throughout.

userId is left as-is: it's a getter-only property (TypeScript renders this to consumers as effectively readonly userId: string — assignment is a compile error), and its lazy throw-on-not-started guard is preferable to a string | undefined field that would force null-checks at every call site.

Mirror WebPubSubClient.on/off shape: overload-per-event, On<X>Args, kebab-case

The previous generic indexed-map shape (on<K extends ChatEventName>(event: K, callback: ChatEventListener<K>)) plus on<Verb>(cb) convenience helpers has been replaced with explicit overloads — one per event — so the chat-domain client.on(...) reads identically to the connection-lifecycle client.connection.on(...). Three coupled changes:

• One overload per event for both on and off (5 events × 2 directions = 10 overloads). Drops ChatEventMap, ChatEventName, ChatEventListener<K> — they only existed to back the generic.
• Event payloads renamed to On<Event>Args, matching the upstream OnConnectedArgs / OnGroupDataMessageArgs convention: ChatMessageEvent → OnMessageArgs, RoomJoinedEvent → OnRoomJoinedArgs, RoomLeftEvent → OnRoomLeftArgs, MemberJoinedEvent → OnMemberJoinedArgs, MemberLeftEvent → OnMemberLeftArgs.
• Event names switched to kebab-case to match upstream literals: "roomJoined" → "room-joined", "roomLeft" → "room-left", "memberJoined" → "member-joined", "memberLeft" → "member-left" ("message" unchanged).
• Dropped the on<Verb>(cb) convenience helpers. Upstream has none, and they had an asymmetric-removal smell: there was never a paired offMessage(cb), so callers still had to use off("message", cb) to unregister. One entry point per event in each direction now.

// Before
client.onMessage((event) => { /* event: ChatMessageEvent */ });
client.onRoomJoined((event) => { /* event: RoomJoinedEvent */ });

// After (mirrors client.connection.on("server-message", ...) on the sibling)
client.on("message",     (event) => { /* event: OnMessageArgs */ });
client.on("room-joined", (event) => { /* event: OnRoomJoinedArgs */ });
client.off("message", handler);

Collapse to single (wpsClient) constructor; drop URL/credential overloads

The URL and credential constructor overloads were a footgun: they left callers with a half-constructed ChatClient that threw ChatError(NotStarted) on every method call until the instance start() was awaited. The static ChatClient.start(url, ...) / start(credential, ...) factories already construct the underlying WebPubSubClient and atomically start the chat client, so there's no reason to keep the parallel path. After this change:

new ChatClient(wpsClient: WebPubSubClient)                       // only constructor

ChatClient.start(url,        wpsOpts?,  startOpts?): Promise<…>  // builds & starts
ChatClient.start(credential, wpsOpts?,  startOpts?): Promise<…>  // builds & starts
ChatClient.start(wpsClient,             startOpts?): Promise<…>  // starts existing

Internally the static URL/credential branches now new WebPubSubClient(...) first and pass the result to new ChatClient(wpsClient), so there is exactly one transport-construction path.

New chat-domain started and stopped events

The pre-existing client.connection.on("connected", ...) and connection.on("stopped", ...) events fire at the transport boundary. They miss the chat-domain transition: connected fires before LOGIN + room hydration complete, so a UI that flips to a "ready" state on connected will still hit ChatError(NotStarted) on subsequent operations. The new events fire on the chat-domain transition:

client.on("started", (e) => {
  console.log(`Chat ready as ${e.userId}`); // OnStartedArgs { userId: string }
});
client.on("stopped", () => {
  console.log("Chat stopped");              // OnStoppedArgs {}
});

OnStartedArgs carries { userId }, mirroring upstream OnConnectedArgs.userId. OnStoppedArgs is empty, matching the upstream OnStoppedArgs shape exactly.

Emission rules — exactly one fire per transition:

• started fires at the end of a successful startCore(), after _isStarted = true and _userId / _rooms are live. Re-calling start() on an already-started client is a no-op and does not re-emit.
• stopped fires from inside resetState(), guarded on a local wasStarted = this._isStarted snapshot taken on entry. This guarantees one emission per started→not-started transition, covering both explicit stop() and transport-driven termination (the connection.on("stopped") callback installed in the constructor). Reset paths that run before _isStarted was ever set to true (the pre-start resetState() at the top of startCore() and the post-failure rollback) do not emit.

Two new lifecycle.test.ts cases pin the rules (8/8 green): "started event fires once after start() completes with userId payload" and "stopped event fires on started→not-started transitions only".

Tooling

• @microsoft/api-extractor@^7.58.7 wired in as a devDependency with a minimal api-extractor.json. Two new scripts:
  • npm run extract-api — update the report
  • npm run check-api — fail in CI if the report is stale
• The generated review/web-pubsub-chat-client.api.md is committed so every public-surface change shows up as a diff on PR review.
• _conversationIds: Set<string> demoted from protected to private (caught by api-extractor — internal cache leaking into the API surface).
• TSDoc cleanup driven by api-extractor warnings (ambiguous {@link ChatClient.start} refs, {@link WebPubSubClientCredential} not re-exported, fenced @example).
• .gitignore: ignore temp/ and package-lock.json (yarn.lock is the lockfile).

Breaking changes (small, contained)

Change	Migration
sendToConversation → private	Use sendToRoom(roomId, message, options?) (already the supported public path).
getRoom(roomId, true)	getRoom(roomId, { withMembers: true })
createRoom(title, members, "my-id")	createRoom(title, members, { roomId: "my-id" })
listRoomMessages({ pageSize: N })	listRoomMessages({ maxPageSize: N })
SendMessageOptions	SendToRoomOptions
RoomMemberOperationOptions	AddUserToRoomOptions / RemoveUserFromRoomOptions
MessageEvent (DOM-clashing type name)	ChatMessageEvent
Disposable returned from on*() listener registrations	on*() return void; remove with off(event, callback)
ChatMessageEvent.conversationId removed; roomId is now required	Drop reads of event.conversationId; rely on event.roomId being defined
client.isStarted removed	Rely on the ChatError(KnownChatErrorCode.NotStarted) thrown by operation methods (or track state in your own UI layer)
Plain Error thrown for unknown-room / not-started / bad response	ChatError with KnownChatErrorCode.* code
ChatEventMap / ChatEventName / ChatEventListener<K> exported types	Removed; use the explicit on(event, listener) overloads — each overload narrows the listener type automatically
on<Verb>(cb) convenience helpers (onMessage, onRoomJoined, onRoomLeft, onMemberJoined, onMemberLeft)	on("event-name", cb) and off("event-name", cb)
Event-payload types (ChatMessageEvent, RoomJoinedEvent, ...)	Renamed to OnMessageArgs, OnRoomJoinedArgs, ... (matches upstream On<X>Args)
Event names ("roomJoined", "roomLeft", "memberJoined", "memberLeft")	Kebab-case ("room-joined", "room-left", "member-joined", "member-left")
new ChatClient(clientAccessUrl, options?) constructor	Use await ChatClient.start(clientAccessUrl, webPubSubClientOptions?, startOptions?)
new ChatClient(credential, options?) constructor	Use await ChatClient.start(credential, webPubSubClientOptions?, startOptions?)

Explicitly out of scope (deferred to the model PR)

• Hand-curated public Message/Room/UserProfile types (Pick/Omit aliases over generated wire types)
• Sender-echo createdAt/bodyType synthesis
• connection getter JSDoc, isWebPubSubClient OR → AND, dead decodeMessageBody
• Empty ChatMessage extends MessageInfo {} interface cleanup
• Full README API-table rewrite, LICENSE / CHANGELOG

Validation

• tsc -p tsconfig.json clean.
• tsx --test tests/lifecycle.test.ts — 6/6 green.
• api-extractor run --local — 0 warnings; the committed review/web-pubsub-chat-client.api.md reflects the exact public surface.
• Integration tests typecheck against the new API; the seven createRoom(..., roomId) call sites, the single getRoom(..., true) call, and the listRoomMessages({ ..., pageSize }) call in tests/integration.test.ts were updated to the new bag form. They require a live Web PubSub backend and were not executed locally — please run in CI.

[xingsy97]

rename to getRoomDetail before merge