[Feature]: Improve headless client ergonomics for custom UI consumers

[Bccorb]

Problem statement

The headless client intentionally returns raw Response objects for many methods. That keeps it flexible, but it also pushes a lot of repetitive parsing and error-handling work onto downstream custom UIs.

We should make the custom UI path more ergonomic without hiding the low-level primitives.

Current behavior

Today many client methods return Promise<Response>, so consumers must repeatedly:

• check response.ok
• parse JSON
• normalize error messages
• map backend responses into UI state

This is workable, but it adds friction for the exact “headless SDK” use case this package now supports.

Goal

Offer a cleaner experience for common custom UI flows while preserving the current low-level access pattern where needed.

Proposed solution

Acceptance criteria

• There is a clearer and less repetitive path for common custom UI flows
• The low-level client surface remains available where flexibility is needed
• Types and docs make expected response handling more consistent
• Tests cover any new convenience helpers

Alternatives considered

No response