Implement sync HTTP client wrapper using httpx

[codebestia]

Description

All sync resource methods need a shared internal HTTP client. This should wrap httpx.Client, set default headers (Content-Type, Accept, User-Agent), and expose a clean internal interface (get, post, patch, delete) used only by resource classes — never exposed in the public API.

Proposed Steps

• Create src/shade/http_client.py with class _SyncHTTPClient.
• Accept api_key, api_base, timeout in the constructor.
• Implement request(method, path, params, json) that builds the full URL and returns a parsed response dict.
• Set User-Agent: shade-python/{version} on every request.
• Use httpx.Client as a context manager internally; keep a single instance alive per ShadeClient.

Acceptance Criteria

• GET/POST/PATCH/DELETE requests are issued to the correct fully-qualified URLs.
• User-Agent header is present on every request.
• Content-Type: application/json is set on POST/PATCH bodies.
• The client does not expose httpx types in its public interface.
• Closing a ShadeClient closes the underlying httpx.Client.

[okeolaolatun23-glitch]

Experienced in backend development, APIs, and OOP, with a strong interest in building scalable and maintainable software systems.

[Perruchok]

I'd like to work on this issue.

I have experience designing Python SDKs and internal client abstractions, and I understand the importance of keeping transport details isolated from the public API. Encapsulating HTTP concerns behind a dedicated internal client improves maintainability, consistency, and makes future enhancements (retries, telemetry, auth changes) much easier.

My approach would be to introduce a private _SyncHTTPClient in src/shade/http_client.py that serves as the shared transport layer for all synchronous resource methods.

Specifically, I would:

• Implement _SyncHTTPClient with api_key, api_base, and timeout parameters.

• Maintain a single underlying httpx.Client instance for the lifetime of a ShadeClient, ensuring connection reuse and efficient resource management.

• Add a common request(method, path, params=None, json=None) method that constructs fully-qualified URLs and returns parsed response dictionaries rather than exposing any httpx response objects.

• Ensure all requests include consistent default headers, including:

  • User-Agent: shade-python/{version}
  • Accept: application/json
  • Content-Type: application/json for requests with JSON bodies

• Expose simple internal helpers (get, post, patch, delete) for use by resource classes while keeping the transport layer entirely private and absent from the public SDK surface.

• Ensure ShadeClient.close() properly closes the underlying httpx.Client, preventing connection leaks and allowing the client to participate cleanly in context-manager workflows.

• Add tests verifying:

  • GET, POST, PATCH, and DELETE requests are sent to the correct fully-qualified URLs,
  • required headers are attached to every request,
  • JSON requests set the appropriate content type,
  • no httpx types leak through the public interface,
  • and closing a ShadeClient correctly closes the shared HTTP client.

The goal is to provide a clean and reusable internal transport layer while preserving a stable, user-friendly SDK interface.

Could you please assign this issue to me? Thank you.

[grantfox-oss]

🦊 GrantFox — @Perruchok has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #7)
2. Your PR will be reviewed by the ShadeProtocol maintainers

Good luck! Track your progress on GrantFox.