Repository navigation
feat(forward): add realtime conversations and history - #17
Merged
Merged
Conversation
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
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.
Summary
Add Forward Realtime Beta Conversation creation, authenticated Node.js WebSocket connections and persisted History with independent
beforepagination. Connections expose text/PCM16 input, typed and unknown events, Work progress, playback receipts, interruption and acknowledged graceful closure.Why
The TypeScript SDK cannot currently use Forward's Realtime API. This adds the public creation/connection/history surface while reusing the existing authentication and HTTP resource conventions. The Node transport loads only when connecting so existing browser HTTP imports remain usable.
Verification
npm run buildnpm run typechecknpm testnpm run docs:check--helpsmoke checks)After merging the latest main: 3676 offline tests passed, 0 skipped; 59 focused Realtime checks. Package checks covered Node 20.12, CJS/ESM, HTTP/browser imports, public types and a local WebSocket connection from an installed tarball. Changelog/release-notes checks passed.
CN/Global × PAT/Forward-bound SAT: 4 text and 4 PCM scenarios passed through
npm run test:live:realtime. These verify creation, ready, ping/pong, nonempty transcripts, decoded output audio, matching close acknowledgements and filtered History pagination. Temporary test Identities were cleaned up; existing Templates were preserved. Conversation IDs are retained because there is no public delete API. Audio devices were not tested.Additional live Work checks observed accepted/running/completed and persisted announcements. The first matrix had 3 passes and a Global PAT History assertion failure. That single unchanged case passed on rerun after adding diagnostic detail; the initial cause remains undetermined and is not represented as a fixed SDK bug. Offline tests also cover receive handoff, iteration without connection closure, protocol validation, cancellation, redirects and bounded queues.
Impact
CHANGELOG.mdunderUnreleased.env.live, logs, or generated test output committedThis is additive; migration notes are not required. Adds
wsand its development types while retaining Node >=20.12. Realtime connections are Node-only. Stage deadlines are separate from HTTP request timeouts; connections do not automatically reconnect or replay input. Playback receipts remain application-owned.Realtime SA access currently requires a Forward-issued bound SAT. The platform
ServiceAccountCredentialexchange does not create that binding; its SAT returned 403 during the initial live checks. Passing a Forward-issued SAT through the existing direct-token interface passed. The SAT issuance API is already merged into main (#16); this PR builds on it and does not change platform credential renewal. Template Realtime configuration APIs are outside this PR.