Expose rate limit data via optional block on API responses

[ProdigyTom]

Changes

Adds an optional block to Management API methods that yields rate limit information alongside the response, without changing the return value for existing callers. Resolves the request in #606 to monitor rate-limit headroom without monkey-patching.

• New Auth0::RateLimit value object (lib/auth0/mixins/rate_limit_struct.rb) built from the x-ratelimit-limit / x-ratelimit-remaining / x-ratelimit-reset response headers. Exposes limit (Integer), remaining (Integer), and reset (UTC Time); fields are nil when a header is absent.
• HTTPProxy now threads an optional block through the request path and, on a successful (2xx) response, yields (response_body, rate_limit). Existing callers are unaffected — the return value is unchanged and the block is entirely optional.
• Users#user_sessions accepts and forwards the block, matching the usage in Rate limit data returned from API methods #606:

  auth0_client.user_sessions(auth0_id) do |response, rate_limit|
    puts "Remaining: #{rate_limit.remaining}/#{rate_limit.limit}, resets at #{rate_limit.reset}"
  end

• Added an EXAMPLES.md section documenting the usage.

The plumbing is generic, so extending the block to additional endpoints is a one-line forward per method; kept to user_sessions here to match the issue and keep the change to a single concern.

References

• Closes Rate limit data returned from API methods #606

Testing

Unit tests cover the new value object (header parsing incl. symbol/dashed keys and missing headers), the proxy yielding (body, rate_limit) on success while leaving the return value unchanged, and user_sessions forwarding the block. Full suite passes locally (bundle exec rspec).

• This change adds unit test coverage
• This change adds integration test coverage
• This change has been tested on the latest version of Ruby

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors
• Rubocop passes on all added/modified files
• All active GitHub checks have passed