fix: browser WebSocket authentication via query param

[pedrocrvz]

Summary

• Fixes WebSocket connections failing in browsers because the native WebSocket class doesn't support custom headers — the { headers: { Authorization: ... } } options object was being interpreted as a subprotocol string ("[object Object]")
• Detects browser vs Node.js environment and uses apiKey as a URL query parameter (wss://host/ws?apiKey=xxx) in browsers, keeping header-based auth for Node.js
• Adds browser-ws example project

Test plan

• All 183 existing + new tests pass (pnpm test)
• Build succeeds with no type errors (pnpm build)
• Verify backend accepts apiKey query parameter on the /ws endpoint
• Test in a real browser environment with the examples/browser-ws project

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @pedrocrvz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical authentication compatibility issue for WebSocket connections in browser environments. By dynamically adjusting the authentication method based on the execution environment, it ensures that browser-based applications can reliably establish WebSocket connections, which was previously hindered by limitations in native browser WebSocket implementations regarding custom headers. The inclusion of a dedicated browser example further facilitates adoption and testing of this new functionality.

Highlights

• Browser WebSocket Authentication Fix: Resolved an issue where WebSocket connections failed in browser environments due to the native WebSocket class not supporting custom Authorization headers. The fix introduces a mechanism to detect the environment and use API keys as URL query parameters for browser-based connections.
• Environment-Specific Authentication: Implemented logic to differentiate between browser and Node.js environments. Browser clients now authenticate via apiKey query parameters, while Node.js clients continue to use header-based authentication, ensuring compatibility and security across different platforms.
• New Browser WebSocket Example: Added a new browser-ws example project to demonstrate and test the new browser-compatible WebSocket authentication flow, providing a clear reference for integrating the gasless SDK in web applications.

Changelog

• .changeset/config.json
  • Added 'browser-ws' to the ignore list to prevent changeset generation for the new example.
• examples/account/ws/src/global.ts
  • Renamed the taskId variable to id for consistency in transaction logging.
• examples/browser-ws/.env.example
  • Added a new example environment file for the browser WebSocket example.
• examples/browser-ws/index.html
  • Added a new HTML file for the browser WebSocket example, including UI elements for connection and transaction logging.
• examples/browser-ws/package.json
  • Added a new package.json for the browser WebSocket example, defining dependencies and scripts.
• examples/browser-ws/src/main.ts
  • Added a new TypeScript file implementing the client-side logic for the browser WebSocket example, including connection, subscription, and transaction sending.
• examples/browser-ws/src/vite-env.d.ts
  • Added a new TypeScript declaration file for Vite client types in the browser example.
• examples/browser-ws/tsconfig.json
  • Added a new tsconfig.json for the browser WebSocket example, extending the base configuration.
• examples/browser-ws/vite.config.ts
  • Added a new Vite configuration file for the browser WebSocket example, setting up a path alias.
• examples/relayer/sponsored/README.md
  • Updated the description for sendTransaction to use 'ID' instead of 'task ID' for broader applicability.
• pnpm-lock.yaml
  • Updated the pnpm lockfile to reflect new dependencies for the browser-ws example.
  • Updated esbuild and vite versions and their associated platform-specific dependencies.
• src/version.ts
  • Updated the package version to 0.0.9.
• src/ws/env.ts
  • Added a new utility file to detect if the code is running in a browser environment.
• src/ws/manager.test.ts
  • Modified WebSocket manager tests to capture MockWebSocket constructor arguments.
  • Added new test cases to verify environment-specific WebSocket authentication (header vs. query parameter).
  • Mocked the isBrowser utility for testing different environments.
• src/ws/manager.ts
  • Imported the isBrowser utility to determine the execution environment.
  • Modified the WebSocket connection logic to use URL query parameters for API keys in browser environments and Authorization headers in Node.js environments.

Activity

• The author has implemented the necessary changes to fix browser WebSocket authentication.
• A new browser-specific example project has been added to demonstrate the functionality.
• Existing tests have been updated, and new tests have been added to cover the browser authentication logic.
• The author has verified that all existing and new tests pass, and the build succeeds without type errors.
• The author has outlined further manual verification steps for the backend and real browser environments.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly fixes WebSocket authentication for browser environments by switching from authorization headers to an apiKey query parameter. While this addresses a technical limitation, it introduces a security risk by exposing sensitive information in the URL. The core logic changes in src/ws/manager.ts are sound and well-supported by tests, and the browser-ws example is a valuable addition. I've also provided suggestions on the new example file to improve error handling in UI event listeners.