chat-client: curate public models - hide generated schemas & conversation concept, document public API#894
Open
vicancy wants to merge 6 commits into
Open
Conversation
…tion concept, document public API Stops the auto-generated OpenAPI aggregates from leaking into the public API and hides the internal "conversation" concept, then documents every remaining public member. The generated API report shrinks by ~280 lines. - Add src/models.ts: hand-curated, standalone public domain types (MessageInfo, RoomInfo, RoomInfoWithMembers, UserProfile). index.ts no longer re-exports the generated `components`/`Schemas` aggregates and has zero reference to generatedTypes. - Add src/modelGuards.ts: a type-only, compile-time guard that fails the build if a field the public models expose drifts from the generated wire schema. One-directional (wire must satisfy the model) so internal-only fields can be intentionally omitted. - Hide the conversation concept from the public surface: drop RoomInfo.defaultConversationId and UserProfile.conversationIds. Internal code keeps them via aliased wire types (WireRoomInfo, WireUserProfile, WireRoomInfoWithMembers); public signatures use the curated models. Login room hydration keeps its explicit `withMembers: false`. - Document all previously-undocumented public APIs: the ChatClient and ChatError classes, `connection`, `getUserProfile`, `sendToRoom`, `getRoomDetail`, `userId`, the event-argument fields, and the on/off/static-start overloads. Verified: build, tsc --noEmit, api-extractor (no ae-forgotten-export, no undocumented members), and the lifecycle unit tests (8/8) all pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…omInfoWithMembers -> RoomDetail
getRoomDetail() previously always returned RoomInfoWithMembers even though
`members` is only populated when called with `withMembers: true`, so the
type guaranteed a field that was usually absent. Split it into overloads
so the return type reflects the argument:
getRoomDetail(id, { withMembers: true }) -> RoomDetail (members populated)
getRoomDetail(id) -> RoomInfo (lightweight)
Also:
- Rename the public type RoomInfoWithMembers -> RoomDetail (future-proof:
reserved to carry further room detail such as conversations). The
generated wire schema name is unchanged; internal code keeps using the
WireRoomInfoWithMembers alias.
- Rename GetRoomOptions -> GetRoomDetailOptions for method/type consistency.
- Fix the misleading "extra round-trip" note (withMembers is a
response-shaping flag on a single call) in the options doc and README.
Verified: build, tsc --noEmit, api-extractor (no ae-forgotten-export, 0
undocumented), and the lifecycle unit tests (8/8) all pass.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
….members optional Drop the separate RoomInfo-returning overload of getRoomDetail in favor of a single signature that always returns RoomDetail, and make RoomDetail.members optional so the type stays honest whether or not members were requested. The `withMembers` option is retained and now simply controls whether `members` is populated (left undefined otherwise). Verified: build, tsc --noEmit, integration test type-check, api-extractor (0 undocumented), and the lifecycle unit tests (8/8) all pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…p WebPubSubClientOptions Encapsulate the transport so consumers no longer deal with WebPubSubClient or its options: - The public constructor now takes a client-access URL or WebPubSubClientCredential (constructor(credential: string | WebPubSubClientCredential)) and builds the connection internally. The WebPubSubClient-injecting constructor is retained only as an @internal test seam. - The WebPubSubClient instance is now a private `_connection` field (previously the public `connection` property). - ChatClient.start collapses to a single start(credential, options?) signature; the WebPubSubClientOptions and pre-built-WebPubSubClient forms are removed. - testUtils and the quickstart example now construct via a credential; README updated (construction, static methods, properties, and the connection-lifecycle section). Verified: build, tsc --noEmit, api-extractor (no ae-forgotten-export, 0 undocumented), and the lifecycle unit tests (8/8) all pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ential) overloads Per API review, narrow the public construction surface: - One public constructor: constructor(credential: WebPubSubClientCredential). WebPubSubClient no longer appears anywhere in the public API. The WebPubSubClient-injecting form remains only as a hidden implementation signature (test seam), distinguished at runtime via isWebPubSubClient. - Two static start overloads: start(clientAccessUrl: string, options?) and start(credential: WebPubSubClientCredential, options?). A string URL is wrapped into a credential internally so both funnel through the single constructor. - Update the lifecycle test injection cast and the README accordingly. Verified: build, tsc --noEmit, api-extractor (no ae-forgotten-export, 0 undocumented), and the lifecycle unit tests (8/8) all pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xingsy97
force-pushed
the
chat-client-curate-public-models
branch
from
3b905e3 to
07f9496
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Follow-up to #892 that finishes curating the chat client's public API surface.
src/models.ts;index.tsno longer exports the generatedcomponents/Schemasaggregates (these dragged ~50 internal schema types plusnever-typed members into the public API). The generated API report shrinks by ~280 lines.conversationconcept.RoomInfo.defaultConversationIdandUserProfile.conversationIdsare removed from the public surface. Internal code still uses them via aliased wire types (WireRoomInfo,WireUserProfile,WireRoomInfoWithMembers).src/modelGuards.tsis a type-only compile-time check that fails the build if a field the public models expose diverges from the generated wire schema, while still allowing intentional omission of internal-only fields (one-directional: wire must satisfy the model).ChatClient/ChatErrorclasses,connection,getUserProfile,sendToRoom,getRoomDetail,userId, the event-argument fields, and theon/off/staticstartoverloads). The API report now has zero(undocumented)markers.Verification
npm run build,tsc --noEmit,npm run extract-api(noae-forgotten-export, 0 undocumented members) ✅No runtime behavior change — this is a type-surface and documentation refactor.