feat(iii-browser): expose addConnectionStateListener on ISdk

[ytallo]

Summary

• Adds addConnectionStateListener(handler) to the ISdk public interface
• Returns an unsubscribe function; multiple listeners supported
• Fires immediately with current state on subscribe
• Exports IIIConnectionState type from package root

Why

Consumers of iii-browser-sdk need an observable connection state to drive WS-based UI. Today setConnectionState is private and IIIConnectionState isn't exported, so consumers have no way to read or react to connection transitions (connect / disconnect / reconnect / failed).

Test plan

• Added tests/connection.test.ts covering subscribe / unsubscribe / multi-listener / initial-fire / connecting->connected transition
• Existing suite passes (46/46 tests)
• pnpm build succeeds (tsdown)

Summary by CodeRabbit

• New Features

  • Introduced addConnectionStateListener method enabling developers to monitor WebSocket connection-state transitions. Listeners are invoked immediately with the current state and on subsequent changes, with built-in unsubscribe functionality.

• Tests

  • Added test coverage for the connection state listener API, verifying immediate invocation, multiple listener support, proper cleanup via unsubscribe, and connection state transitions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
iii-website	Skipped		May 7, 2026 2:32am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6336af5e-ed9a-4057-86b9-a3de1e417326

📥 Commits

Reviewing files that changed from the base of the PR and between dba627d and 2458759.

📒 Files selected for processing (4)

• sdk/packages/node/iii-browser/src/iii.ts
• sdk/packages/node/iii-browser/src/index.ts
• sdk/packages/node/iii-browser/src/types.ts
• sdk/packages/node/iii-browser/tests/connection.test.ts

---

📝 Walkthrough

Walkthrough

The SDK adds a addConnectionStateListener method that allows consumers to register callbacks for WebSocket connection-state transitions. Listeners are invoked immediately upon subscription and subsequently when state changes. The implementation adds a listener registry, notification logic during state transitions, and exports the IIIConnectionState type.

Changes

Connection State Listener

Layer / File(s)	Summary
Type Definition & Exports src/types.ts, src/index.ts	ISdk interface gains addConnectionStateListener(handler: (state: IIIConnectionState) => void): () => void method declaration. IIIConnectionState type is re-exported from package entrypoint.
Core Implementation src/iii.ts	A connectionListeners set is added to store registered handlers. addConnectionStateListener registers a handler, invokes it immediately with current state (with try/catch error logging), and returns an unsubscribe function. setConnectionState is extended to notify all listeners when state transitions.
Tests tests/connection.test.ts	Comprehensive test suite validates: listener unsubscribe mechanism, immediate invocation with initial state, multiple listeners receiving synchronized events, unsubscribe preventing further invocations, and state transitions reaching 'connected'.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• iii-hq/iii#1376: Introduces the iii-browser SDK modules that are now extended with the connection listener feature.

Poem

🐰 A listener born, with hearts that chime,
Connection states, now tracked in time!
Subscribe, unsubscribe, the dance so sweet,
WebSocket whispers, make life complete! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers the main changes (new listener method, type export), motivation (need for observable connection state), and testing (new test file, passing tests). However, it doesn't follow the repository's template structure with 'What', 'Why', and 'Notes' sections, and lacks the required Apache 2 license checkbox confirmation.	Restructure the description to match the template: use 'What', 'Why', 'Notes' sections and include the checked Apache 2 license checkbox at the end.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: exposing a new public method on the ISdk interface for connection state listening.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/browser-sdk-connection-listener

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}