feat(query): support API-specific query serialization

[yordis]

• keeps query parameters as structured data so middleware and logging can still reason about them
• lets callers use API-specific serializers without forcing Tesla to depend on Plug
• closes Query parameters do not support nested maps #538 by covering nested maps and caller-provided query encoding in the request path

[cursor]

PR Summary

Medium Risk
Changes URL/query serialization and query merging behavior, which can subtly affect request URLs and logging output across clients. Added tests reduce risk but real-world APIs may rely on specific ordering/encoding edge cases.

Overview
Adds structured query param support by allowing Tesla.Env.query and request :query to be nested maps (in addition to keyword/tuple lists), and updates query encoding to flatten nested maps into bracketed keys.

Introduces custom query serialization via a query_encoding function (or existing :www_form/:rfc3986 atoms) used by Tesla.build_url/1 and logger formatting, plus guards to treat empty query maps like empty lists.

Updates Tesla.Middleware.Query to merge map queries without overriding existing keys and to safely combine map/list forms, and expands test coverage for nested maps, custom encoders, and empty-map behavior.

No new environment variables were introduced in this diff.

^{Reviewed by Cursor Bugbot for commit c4ca37e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Adds support for keeping query parameters as structured data (including nested maps) while allowing API-specific/custom query serialization (e.g., Plug’s encoder) without adding a Plug dependency.

Changes:

• Extend Tesla.Env query param types to support nested maps in addition to lists.
• Add support for passing a custom query_encoding function, and add nested-map expansion during query encoding.
• Add test coverage for nested-map query encoding and custom query encoder integration (including logger output).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

File	Description
lib/tesla.ex	Extends query encoding strategy to accept a function and adds nested-map flattening during encoding.
lib/tesla/env.ex	Updates typespecs to allow query params as nested maps.
test/tesla_test.exs	Adds tests for nested-map query encoding and custom encoder usage via build_url/3 and Tesla.build_url/1.
test/tesla/middleware/logger_test.exs	Adds tests ensuring logger formatting/debug output handles nested-map queries and custom encoders.

Comments suppressed due to low confidence (1)

lib/tesla.ex:391

• The build_url/3 docs still describe query as “a list of key-value pairs”, but this PR now supports maps (including nested maps) as well. Updating that bullet (and/or examples) to explicitly mention map support would keep the docs consistent with the new types and behavior.

  - `url` - the base URL to which the query params will be appended.
  - `query` - a list of key-value pairs to be encoded as query params.
  - `encoding` - the encoding strategy to use. Defaults to `:www_form`

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

lib/tesla.ex:391

• The build_url/3 docs still state that query is “a list of key-value pairs”, but the implementation/spec now accepts maps (including nested maps). Updating this bullet (and any surrounding wording) would keep the docs aligned with the new behavior.

  - `url` - the base URL to which the query params will be appended.
  - `query` - a list of key-value pairs to be encoded as query params.
  - `encoding` - the encoding strategy to use. Defaults to `:www_form`

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 334a670. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

lib/tesla.ex:391

• In the build_url/3 docs, the query parameter is still described as “a list of key-value pairs”, but the implementation and tests now support passing a map (including nested maps). Updating this bullet to mention maps will keep the public docs consistent with the new behavior.

  - `url` - the base URL to which the query params will be appended.
  - `query` - a list of key-value pairs to be encoded as query params.
  - `encoding` - the encoding strategy to use. Defaults to `:www_form`

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

lib/tesla.ex:391

• The build_url/3 docs still say query is “a list of key-value pairs”, but the function now accepts maps (including nested maps) as well. Updating this bullet to mention maps will keep the public docs consistent with the new behavior and examples.

  - `url` - the base URL to which the query params will be appended.
  - `query` - a list of key-value pairs to be encoded as query params.
  - `encoding` - the encoding strategy to use. Defaults to `:www_form`

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.