[Feature]: Expose supported HTTP response metadata hooks on sync and async clients

[ConBrp]

Summary

Please expose a supported, opt-in way to observe HTTP response metadata from SecureClient and AsyncSecureClient requests without changing their typed return values.

This is needed to monitor the new per-signer CLOB trading token buckets. Covered order and cancellation responses can include:

• Poly-RateLimit-Remaining
• Poly-RateLimit-Reset
• Poly-RateLimit-Tier
• Poly-RateLimit-Warning
• Retry-After on HTTP 429

Documentation: https://docs.polymarket.com/api-reference/trading-rate-limits

Current behavior

The transport receives an httpx.Response, but public client methods parse and return the response body as typed models. SecureClient.create() and AsyncSecureClient.create() do not expose a public response hook or transport configuration, so applications cannot observe headers from successful requests.

The internal TransportOptions.event_hooks facility is not reachable through the public client constructors. Reaching through private client context or globally monkey-patching HTTPX would be fragile, especially in concurrent trading applications.

Issue #182 is related for rejected responses and Retry-After, but this request also covers successful responses and general response metadata observation.

Requested API

One possible design would be an optional response callback accepted by both client factories:

def observe_response(metadata: ResponseMetadata) -> None:
    remaining = metadata.headers.get("Poly-RateLimit-Remaining")

client = SecureClient.create(
    private_key=private_key,
    wallet=wallet,
    credentials=credentials,
    response_hook=observe_response,
)

The exact API shape is flexible. The important properties would be:

1. Supported on both synchronous and asynchronous clients.
2. Invoked for successful and unsuccessful HTTP responses, before an exception discards response metadata.
3. Provides at least method/path, status code, and response headers.
4. Does not expose authentication request headers or request bodies by default.
5. Preserves all existing typed return values and behavior when no hook is supplied.
6. Applies to all transports owned by the client, or clearly identifies which service produced the response.

Exposing a public TransportOptions argument could also solve this, provided it is supported and stable.

Environment

• Package: polymarket-client==0.2.0
• Clients: SecureClient and AsyncSecureClient
• Use case: production monitoring of per-signer CLOB order and cancellation rate limits

[kartojal]

thanks for requesting this feature @ConBrp , we will look at this

[chatball]

Narrow sub-request for the 429 case:

_raise_for_response_status() raises a bare RateLimitError on 429, while the branch right below it passes retry_after=_extract_retry_after(response) to RequestRejectedError. The helper already exists, and the CLOB trading rate-limit docs say Retry-After is present on 429 — so the one status code where the platform guarantees backoff guidance is the one that drops it.

Suggested fix: add status: int = 429 and retry_after: float | None = None to RateLimitError and populate them from the existing helper in the 429 branch. No new parsing, additive, and existing except RateLimitError handlers are unaffected. I'd suggest adding the attributes rather than reparenting onto RequestRejectedError, since reparenting would make existing except RequestRejectedError handlers start catching 429s.