feat: add rest client

[tchapacan]

Description

Following continuation of this PR #142, this one is related to the implementation of the REST mode support for the client part of a2a-js sdk. Following the same pattern as other sdk (agnostic transport).

---

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
  • Important Prefixes for release-please:
    • fix: which represents bug fixes, and correlates to a SemVer patch.
    • feat: represents a new feature, and correlates to a SemVer minor.
    • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.
• Ensure the tests and linter pass
• Appropriate docs were updated (if necessary)

Fixes #137, fixes #175 🦕

Release-As: 0.3.7

[gemini-code-assist]

Summary of Changes

Hello @tchapacan, 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 significantly enhances the client's communication capabilities by integrating a new REST client. This addition provides an alternative, HTTP-based transport layer to interact with agents, complementing the existing JSON-RPC. The change involves the creation of dedicated REST transport classes, a shared utility for parsing Server-Sent Events, and updates to the client factory to support the new transport by default. The overall impact is increased flexibility and broader compatibility for client-agent interactions.

Highlights

• New REST Client Implementation: Introduces RestTransport and RestTransportFactory to enable communication with agents via REST APIs, providing an alternative to JSON-RPC.
• SSE Parsing Utility: A new sse_parser.ts module provides a reusable function for parsing Server-Sent Events, which is now utilized by both JSON-RPC and REST transports for streaming data.
• Client Factory Integration: The ClientFactory now includes the RestTransportFactory as a default option, allowing clients to seamlessly use REST for agent interactions without explicit configuration.
• Updated E2E Tests: Comprehensive end-to-end tests have been refactored to validate functionality across both JSON-RPC and the new REST transport mechanisms, ensuring robust behavior.

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 introduces a new REST transport client, which is a significant and well-structured feature. The implementation in src/client/transports/rest_transport.ts is solid, and the refactoring of Server-Sent Events (SSE) parsing logic into a reusable sse_parser.ts module is a great improvement for code maintainability. The parameterization of end-to-end tests to cover both JSON-RPC and REST transports is also a commendable effort to ensure robustness. My review identifies a high-severity bug in getTaskPushNotificationConfig that could lead to incorrect behavior, and a medium-severity issue in setTaskPushNotificationConfig concerning redundant data in the request body. Addressing these points will enhance the correctness and clarity of the new REST client.

[tchapacan]

Hello @ishymko !

Following our last discussion in this PR #142, this my proposition for REST support in the client.

To summarize :

• Created a rest_transport.ts following same pattern as the jsonrpc
• Extracted some common part between rest and jsonrpc for the SseParsing into sse_parser.ts (but can rename or refacto it if necessary)
• Updated the test to make sure both jsonrpc and rest could be run in e2e.spec.ts
• I choose to go with only camelCase for the client, LMK if it's ok (I know server support both, but this is to be more aligned with the spec)

Not sure about the error handling, but this might be where the backward compability is for the jsonrpc, so I've simplified and be more straightforward for the rest one, so LMK if that's ok this way.

[ishymko]

Hello again @tchapacan, thank you for a quick follow-up with the client part of HTTP+JSON/REST transport!

Left a few minor comments and should be good to go, well done 👍

I choose to go with only camelCase for the client, LMK if it's ok (I know server support both, but this is to be more aligned with the spec)

Yep, agree.

Not sure about the error handling, but this might be where the backward compability is for the jsonrpc, so I've simplified and be more straightforward for the rest one, so LMK if that's ok this way.

Looks good to me.

[tchapacan]

Helo @ishymko ,

2 open questions crossed my mind while re-reading the PR.

• Do we plan to add a sort of dynamic way to escape a potential / suffix (using a regex for example) in the endpoint in case someone add it in the agentCard that could break the full path url construction? I don't like adding too much regex, it can be error prone, but well depending of the case sometimes can be helpful. Maybe it's enforced by the spec and not a subject, but just asking as I already saw this.
• Again the spec is quite obvious about the fact that in the agentCard it's HTTP+JSON in uppercase and respectively for other transports. But unfortunately I have already seen custom implementation that leave it lowercase. Does it make sense to always uppercase it at runtime to ensure compatibility?

What's your opinion regarding those 2?

[ishymko]

Hi @tchapacan, added some final minor comments and answered questions.

On your questions:

1. Great question. I believe it's not fully accurate in the spec now, spec operates on /v1... absolute paths, so strictly speaking combining them with something like https://example.com/a2a/rest/ should erase the path on the base URL according to the rules most libraries use which is going to result in https://example.com/v1... with a2a/rest removed. I think it makes sense to protect from this to be more developer friendly. Let's trim trailing slashes from the base URL provided by the user before concatenating, something like .replace(/\/+$/, "").
2. Another great question. I tend to agree that we should relax strictness for better compatibility with implementations "in the wild". Created #264, let's address it separately.

[tchapacan]

Helo @ishymko ,

I've tried to fixed all the comment and rebase LMK if that's good. I have added as well the trim of the trailing slash for the endpoint and tests for it.

According to this job https://github.com/a2aproject/a2a-js/actions/runs/20286295879/job/58260634940?pr=258 it seems that the token used might not have the correct scope, or might be a permission issue, maybe because coming from a fork ?

for the case insensitive comparison #264 I can have a look later if no one yet plan to work on it

[github-actions]

🧪 Code Coverage

⬇️ Download Full Report

Metric	Main	PR	Delta
lines	81.57%	82.21%	🟢 +0.64%
statements	81.33%	81.99%	🟢 +0.66%
functions	87.18%	88.67%	🟢 +1.49%
branches	69.98%	70.63%	🟢 +0.65%

Generated by coverage-comment.yml

[ishymko]

Thank you @tchapacan, LGTM! 🚀

Sorry for confusion with the failing coverage workflow, this was fixed in #270 and it passes on your PR now.

And of course your contribution is going to be welcome on #264 💯