feat(api)!: fluent request builders, opaque transport error, drop Client::new

[OpenSauce]

Second of four PRs preparing the 0.1.0 release. This is the one that freezes the public API, so everything breaking lands here.

Fluent request builders replace the param structs

SearchParams, ListParams, ModelListParams and UserListParams are gone. client.tones(), .created(), .favorited(), .models(tone_id) and .users() return builders that implement IntoFuture, so they're awaited directly — no .send().

// before
client.search(SearchParams { query: Some("plexi".into()), ..Default::default() }).await?;
// after
client.tones().query("plexi").await?;

// browse, which has no endpoint of its own — it's search with no query
client.tones().sort(ToneSort::DownloadsAllTime).page_size(24).await?;

Beyond ergonomics, this makes adding a filter a non-breaking change (a new builder method), which matters for an API that keeps adding them. #[non_exhaustive] on the old structs couldn't do that — it forbids ..Default::default() from other crates entirely.

reqwest leaves the public API

Error::Http now wraps an opaque HttpError exposing is_timeout(), is_connect() and status(), mirrored by Error::is_timeout()/is_connect(). reqwest has shipped four breaking majors in seven years — the most recent in December 2025 — and each would otherwise force a breaking release here plus lockstep upgrades for consumers.

Client::new() removed

It built a client on which every call failed with Unauthenticated (every endpoint needs a user access token), while being the most discoverable constructor in the crate. Client::builder(key) is the only path that works.

architecture is ArchitectureVersion, not u32

Upstream types.ts declares architecture?: number. It's wrong. Probed live on 2026-08-11:

architecture=	Result
1	200, total 7,914
2	200, total 9,590
custom	200, total 1,233
banana	400 — "architecture must be '1', '2', or 'custom' when provided"

Three distinct result sets, and the API's own error message names the exact vocabulary ArchitectureVersion already models. As u32 the parameter both made custom unfilterable and let callers build requests the server rejects (.architecture(3) compiled, then 400'd). Input and output now share one type.

Second time types.ts has been wrong, after the platform → format rename.

Also

• Page::has_next() / has_prev()
• CLAUDE.md updated to describe the new surface

Verification

cargo fmt --check, cargo clippy --all-targets -D warnings, cargo test — 57 passing, live tests ignored as designed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR prepares the crate for a 0.1.0 “public API freeze” by switching list/search endpoints to fluent request builders (awaitable via IntoFuture), removing Client::new(), and introducing an HttpError wrapper intended to keep reqwest out of the public surface while preserving useful transport predicates.

Changes:

• Replaced *Params request structs with fluent request builders: tones(), created(), favorited(), models(tone_id), users() (await directly; no .send()).
• Introduced HttpError + Error::{is_timeout,is_connect} helpers and re-exported the new public endpoint builder types.
• Updated tests/examples/docs to the new API, and added Page::has_next() / has_prev() helpers.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/read_path.rs	Updates wiremock tests to new fluent builders; adds pagination serialization coverage.
tests/oauth.rs	Migrates OAuth refresh tests to client.tones().await style and builder construction.
tests/live_user.rs	Updates live contract test to new created()/favorited() builders.
tests/live_public.rs	Updates live contract tests to new tones()/models()/users() builders.
src/models/user.rs	Removes UserListParams model param struct.
src/models/tone.rs	Removes SearchParams/ListParams model param structs.
src/models/page.rs	Adds Page::has_next() / has_prev() plus tests.
src/models/model.rs	Removes ModelListParams model param struct.
src/models/mod.rs	Stops re-exporting removed params structs.
src/lib.rs	Updates crate docs; re-exports new endpoint builder types and HttpError.
src/error.rs	Replaces Error::Http(reqwest::Error) with Error::Http(HttpError) and adds transport predicates.
src/endpoints/users.rs	Converts Client::users(params) to Client::users() -> UserList fluent builder.
src/endpoints/tones.rs	Converts search/list endpoints to ToneSearch / ToneList builders implementing IntoFuture.
src/endpoints/models.rs	Converts Client::models(tone_id, params) to Client::models(tone_id) -> ModelList builder.
src/endpoints/mod.rs	Makes endpoint submodules public for re-exporting builder types from crate root.
src/client.rs	Removes Client::new() and updates tests accordingly.
examples/search_and_download.rs	Updates example to tones().query(...).await and models(tone_id).await.
CLAUDE.md	Updates repository guidance to reflect the new fluent surface and error approach.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.