Read the rate-limit headers, and hold a 429 once per client (#48)

* feat: read the rate-limit headers, and hold a 429 once per client

Same treatment as the Python sibling, same reasoning.

The SDK read exactly one header, Retry-After, and only after a 429 had already
happened. It could tell you that you had run out, never that you were about to.

Both meters are now on the client. The per-minute REST one, and the hourly
history budget the API started publishing today:

    tp.rateLimit.rest.remaining
    tp.rateLimit.history.remaining
    secondsUntilReset(tp.rateLimit.rest)

ABSENCE IS NOT ZERO, and the design turns on it. An unmetered plan advertises
no figures, and neither does a publicly cacheable response, because the numbers
are per-caller and a shared cache would hand one caller's budget to another --
so anonymous calls carry nothing. null means the server did not say.
isExhausted is true only when it said zero. Reading an unknown as zero would
stall every anonymous client permanently, which is the first thing the tests
pin.

reset is a relative countdown frozen when it was read, so secondsUntilReset
ages it. Using the raw value later is how a client waits an hour longer than it
needs to, and it is the same bug the server had in its cached headers.

The client acts on what it reads: a window the server said is spent is waited
out rather than walked into, because that request is a certain 429 that also
costs a unit of budget to refuse. retry: { respectRemaining: false } opts out.

A 429 IS NOW HELD ONCE FOR THE WHOLE CLIENT. The wait belongs to the caller,
not to whichever request met it. Ten concurrent requests each slept their own
Retry-After and then retried at the same instant, re-tripping the limit
together. It goes on a shared gate with a little jitter, taken once, and the
retry path no longer pays it a second time. A shorter wait arriving while a
longer one is in force no longer brings the gate forward. Past maxRetryAfterMs
the gate is deliberately left open: we throw instead, and blocking the next
call for most of an hour is the opposite of letting the caller checkpoint.

The cache wrapper gap that Python hit does not exist here -- the client holds
the inner transport directly -- but there is a test for it either way, because
caching is on by default and every other test turns it off.

Verified against production: reads limit=300 remaining=296 reset=40
policy="300;w=60" on a real anonymous call, with the history meter correctly
absent and isExhausted false.

123 tests, 21 new. Mutation-checked: treating an unknown remaining as exhausted
fails 3, letting a blank response erase what we knew fails 1, bringing the gate
forward fails 1, removing the jitter fails 1, and not ageing the reset fails 2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix: paged history crashed on the default cache, plus three more

Four review agents, two of them independently found the same blocker.

PAGED HISTORY CRASHED FOR EVERY DEFAULT CALLER. I added #gate and #hold as
ECMAScript private fields on Transport. client.ts wraps the transport in a
Proxy to add caching, and a Proxy forwards methods with `this` bound to the
proxy, so the private brand check fails:

    TypeError: Receiver must be an instance of class Transport

history.days() threw on page two for anyone who had not passed cache: false --
the paid feature, on the default configuration. 130 tests passed because the
paging test helper hardcodes cache: false, so every paging test took the one
path where the bug cannot fire. They are TS-private now, which compiles to a
plain property and forwards fine, and there is a paging test on the default
cache that fails if the # fields come back.

THE GATE TIMED OFF THE WALL CLOCK. closeFor stored Date.now() + ms and waitMs
subtracted Date.now(), so a backward NTP step turned a five-second wait into
however far the clock moved -- an hour, measured -- with nothing bounding it,
because the cap is applied when the gate is armed and never when it is served.
Monotonic now, which is what the Python sibling had from the start.

on429: false DID NOT OPT OUT. It threw the error the caller asked for and then
closed the shared gate anyway, so their NEXT call blocked for the full
Retry-After. An advertised switch that switches nothing is worse than none.

THE PREMISE WAS BACKWARDS. The docs said anonymous calls carry no figures.
Measured against production it is the other way round for the per-minute meter;
the hourly history set is the one withheld from cacheable responses. And a
cached response's figures belong to whoever populated the entry -- age: 9 with
an unmoving remaining: 285, served to everyone -- so a non-zero Age is now
treated as saying nothing. A cache MISS carries no Age and is still recorded.

Also: strict integer parsing, so "0.4" no longer reads as 0 and makes
isExhausted true; fifteen edge cases now agree byte for byte with Python. Two
timing tests made deterministic instead of asserting ranges around the real
clock. Gate, readRateLimits and the UNKNOWN_* sentinels unexported -- Gate had
no route to the client's instance and readRateLimits' parameter type was not
exported, so nobody could name what they were passing. A CHANGELOG Changed
section saying plainly that calls may now block before sending.

131 tests. tsc, eslint, prettier and the build clean. Mutation-checked:
restoring the # fields fails the new paging test, honouring cached figures
fails 1, and both opt-outs are pinned.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix: maxRetryAfterMs bounds the whole call, and three vacuous tests

Same per-call budget as the Python sibling, same measurement behind it: the
gate wait and the spent-window wait stack, so a 429 carrying both a
Retry-After and RateLimit-Remaining: 0 blocked for 180 seconds under a 120
second cap. Every leg was under the cap, so the per-leg check never fired.
maxRetryAfterMs is a per-call budget now.

Three tests could not fail, all found by mutation:

- The spent-window assertion was an upper bound only, on the single test
  covering the flagship behaviour. `sleep(left)` in place of
  `sleep(left * 1000)` -- seven milliseconds instead of seven seconds, a
  thousandfold too short -- passed green. Both bounds now.

- The jitter test was sound against Date.now()'s millisecond granularity and
  MY monotonic-clock change gutted it: performance.now() ticks between the 20
  calls, so the set is distinct with or without jitter. It asserted that time
  passes. It runs against a frozen clock now and bounds the spread.

- Nothing proved a sleep was AWAITED rather than merely requested. Dropping
  every await in hold() passed all 135 tests. A fake sleep that resolves on a
  later macrotask and counts itself pending now fails if a request starts
  while a hold is in flight. Honest limit: dropping ONE await is still masked
  by the other, because with one await remaining the hold does still block.

No test in either file had ever sent a 429 carrying rate-limit headers, which
is why none of this surfaced: both docstrings claimed to cover the gate and
every fixture was a 200.

136 tests. tsc, prettier and the build clean. Mutation-checked: removing the
budget fails 1, deleting the jitter fails 2, the thousandfold-short sleep
fails 1, dropping all awaits fails 1.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix: Retry-After parsing, two release herds, and a NaN that disabled the gate

Same three fixes as the Python sibling, same measurements behind them.

RETRY-AFTER PARSING. Only null reaches the exponential backoff, so a header
parsing to zero meant no wait at all -- and `Retry-After: 0` is legal per RFC
9110, as is a negative and an already-past date. Measured in Python, which had
the identical shape: four requests in 3ms against a server that had just said
429, and 204 a second across ten threads.

Number() was also far too generous for a `delta-seconds = 1*DIGIT` field: it
read '   ' as 0 and spun, and '0x10' as 16 and slept 48 seconds across three
retries where Python correctly took 2. The two parsers in this file now follow
the same rule, which they did not after the last round tightened only one.

THE SPENT-WINDOW PATH WAS A PURE HERD: ten waiters left inside the SAME
MILLISECOND, measured. Every one derived its deadline from the same observedAt
and slept to the same absolute instant with no spread. It runs through the same
jitter as the gate now.

A WAITER THAT WOKE INTO A RE-CLOSED GATE SENT ANYWAY -- measured waking at
584ms with the gate shut for another two seconds. It re-reads now, but only
when the deadline actually MOVED. My first attempt re-read unconditionally and
spun 57 times against a frozen test clock, which is the correct behaviour of a
wrong loop.

A NaN jitter would have made setTimeout fire immediately and silently disable
the gate rather than fail loudly. Guarded.

The new spread test is measured against a frozen clock, because against a live
one `left` varies by itself and the assertion passes with the spread deleted.

137 tests. Mutation-checked: removing either spread fails, and so does
removing the budget.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cubehouse

CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.2.0] - 2026-09-26
+
+### Added
+
+- **The client reads the rate-limit headers, and acts on them.** Both meters,
+  the per-minute REST one and the separate hourly history budget, on
+  `client.rateLimit`:
+
+  ```js
+  tp.rateLimit.rest.remaining;
+  tp.rateLimit.history.remaining;
+  secondsUntilReset(tp.rateLimit.rest);
+  ```
+
+  Every field can be null, and null means the server did not say rather than
+  "nothing left". Use `isExhausted`, true only when the server said zero. The
+  per-minute figures ride most responses; the hourly history ones are withheld
+  from anything a shared cache may store, because they are per-caller; an
+  unmetered plan advertises nothing. A response served from a cache is ignored
+  entirely, because its figures belong to whoever populated the entry. `reset` is a relative
+  countdown frozen when it was read, so `secondsUntilReset` ages it rather
+  than returning a stale number.
+
+  A window the server says is spent is now waited out instead of walked into,
+  since that request is a certain 429 that also spends budget being refused.
+  `retry: { respectRemaining: false }` opts out.
+
+  The hourly history budget is new on the wire; before it there was nothing to
+  read.
+
+### Changed
+
+- **Calls may now block before sending.** When the server has said your window
+  is spent, or has issued a 429 that is still in force, the client waits rather
+  than sending a request certain to be refused. A call that used to return in
+  200ms can now take up to `retry.maxRetryAfterMs` (120000) first. That is a
+  TOTAL across the call, not per wait: the shared 429 gate and the
+  spent-window wait stack, and before the budget existed a 429 carrying both a
+  `Retry-After` and a spent window blocked for 180 seconds under a 120 second
+  cap. Turn the two halves off with `retry: { respectRemaining: false }` and
+  `retry: { on429: false }`.
+
+### Fixed
+
+- **A paged history call crashed on the default configuration.** `#private`
+  fields on the transport failed their brand check through the caching Proxy,
+  so `history.days()` threw `TypeError: Receiver must be an instance of class
+Transport` on page two for anyone who had not passed `cache: false`. Every
+  test passed `cache: false`, so none of them saw it.
+
+- **`on429: false` did not opt out.** It threw the error the caller asked for
+  and then held their NEXT call for the full `Retry-After` anyway, because the
+  shared gate was closed regardless of the setting.
+
+- **The gate timed off the wall clock.** A backward NTP step turned a
+  five-second wait into however far the clock moved, unbounded, because the cap
+  is applied when the gate is armed and not when it is served. It uses a
+  monotonic clock now, as the Python sibling always did.
+
+- **A 429 was waited out once per in-flight request.** The wait belongs to the
+  caller, not to whichever request met it, so ten concurrent requests each
+  slept their own `Retry-After` and then retried at the same instant,
+  re-tripping the limit together. It is taken once now, on a gate shared by the
+  whole client, with a little jitter so waiters do not wake in unison. A
+  shorter wait arriving while a longer one is in force no longer brings the
+  gate forward.
+
 ## [8.1.0] - 2026-09-23
 
 ### Added

README.md

@@ -49,15 +49,15 @@ Jungle Cruise                                      40 min
 
 `new ThemeParks(options)` takes the following keyword options:
 
-| Option      | Type                                | Default                                            | Purpose                                                                                                                                                                                                                                        |
-| ----------- | ----------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`   | `string`                            | `https://api.themeparks.wiki/v1`                   | API base URL (point at a mock / staging if you need to).                                                                                                                                                                                       |
-| `userAgent` | `string`                            | `themeparks-sdk-js/<version>`                      | Sent as the `User-Agent` header. Set this to identify your app.                                                                                                                                                                                |
-| `apiKey`    | `string`                            | none                                               | API key from api.themeparks.wiki, sent as `X-API-Key`. Optional; a key raises the limits.                                                                                                                                                      |
-| `fetch`     | `typeof fetch`                      | `globalThis.fetch`                                 | Custom fetch implementation. Useful for logging, mocking, or older runtimes.                                                                                                                                                                   |
-| `timeoutMs` | `number`                            | `10000`                                            | Per-request timeout in milliseconds.                                                                                                                                                                                                           |
-| `retry`     | `Partial<RetryConfig>`              | `{ max: 3, on429: true, maxRetryAfterMs: 120000 }` | Retry/backoff behavior. `max` counts retries **beyond** the initial attempt (so `3` = up to 4 total). `maxRetryAfterMs` is the longest `Retry-After` the client will sleep through; past it you get `RateLimitError` instead of a silent wait. |
-| `cache`     | `Cache \| false \| { maxEntries? }` | in-memory LRU                                      | See [Caching](#caching) below. `false` disables caching entirely.                                                                                                                                                                              |
+| Option      | Type                                | Default                                                                    | Purpose                                                                                                                                                                                                                                        |
+| ----------- | ----------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`   | `string`                            | `https://api.themeparks.wiki/v1`                                           | API base URL (point at a mock / staging if you need to).                                                                                                                                                                                       |
+| `userAgent` | `string`                            | `themeparks-sdk-js/<version>`                                              | Sent as the `User-Agent` header. Set this to identify your app.                                                                                                                                                                                |
+| `apiKey`    | `string`                            | none                                                                       | API key from api.themeparks.wiki, sent as `X-API-Key`. Optional; a key raises the limits.                                                                                                                                                      |
+| `fetch`     | `typeof fetch`                      | `globalThis.fetch`                                                         | Custom fetch implementation. Useful for logging, mocking, or older runtimes.                                                                                                                                                                   |
+| `timeoutMs` | `number`                            | `10000`                                                                    | Per-request timeout in milliseconds.                                                                                                                                                                                                           |
+| `retry`     | `Partial<RetryConfig>`              | `{ max: 3, on429: true, maxRetryAfterMs: 120000, respectRemaining: true }` | Retry/backoff behavior. `max` counts retries **beyond** the initial attempt (so `3` = up to 4 total). `maxRetryAfterMs` is the longest `Retry-After` the client will sleep through; past it you get `RateLimitError` instead of a silent wait. |
+| `cache`     | `Cache \| false \| { maxEntries? }` | in-memory LRU                                                              | See [Caching](#caching) below. `false` disables caching entirely.                                                                                                                                                                              |
 
 Example:
 
@@ -161,6 +161,49 @@ const entries = await tp.entity(mk).schedule.range(new Date('2026-05-01'), new D
 console.log(`${entries.length} schedule entries`);
 ```
 
+## Rate limits
+
+The API meters requests per minute, and history requests again per hour. Both
+are read off every response that carries them:
+
+```js
+import { ThemeParks, isExhausted, secondsUntilReset } from 'themeparks';
+
+const tp = new ThemeParks({ apiKey: KEY });
+await tp.entity(parkId).live();
+
+tp.rateLimit.rest.remaining; // 299
+secondsUntilReset(tp.rateLimit.rest); // 40
+tp.rateLimit.history.remaining; // on a history call
+```
+
+**`null` means the server did not say, never "nothing left".** Use
+`isExhausted`, which is true only when the server actually said zero.
+
+Which figures you get depends on the response:
+
+- The **per-minute** figures ride most responses, anonymous ones included.
+- The **hourly history** figures are withheld from anything a shared cache may
+  store, because they are per-caller and a cache would hand one caller's budget
+  to another. In practice you get them on calls made with a key.
+- An **unmetered plan** advertises nothing at all.
+
+A response served from a cache is ignored entirely. Its figures belong to
+whoever populated the entry and its countdown is already wrong: a cached
+`remaining: 0` would otherwise make the client sleep out someone else's
+window.
+
+The client acts on what it reads. When a response says the window is spent, the
+next request waits for the advertised reset rather than sending one that is
+certain to be refused, and to cost a unit of budget being refused. Opt out with
+`retry: { respectRemaining: false }`.
+
+**A 429 is held once for the whole client.** The wait belongs to the caller,
+not to whichever request met it, so it goes on a shared gate with a little
+jitter. Without that, ten concurrent requests each sleep their own copy of
+`Retry-After` and then all retry at the same instant, re-tripping the limit
+together.
+
 ## History
 
 Three endpoints answer what an entity did in the past. Days are park-local; the

package.json

@@ -1,6 +1,6 @@
 {
   "name": "themeparks",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Official SDK for the ThemeParks.wiki API",
   "license": "MIT",
   "repository": "github:ThemeParks/ThemeParks_JavaScript",

src/client.ts

@@ -8,9 +8,10 @@ import {
   type FetchLike,
   type RetryConfig,
 } from './transport';
+import type { RateLimits } from './ratelimit';
 
 const DEFAULT_BASE_URL = 'https://api.themeparks.wiki/v1';
-const PACKAGE_VERSION = '8.1.0';
+const PACKAGE_VERSION = '8.2.0';
 const DEFAULT_USER_AGENT = `themeparks-sdk-js/${PACKAGE_VERSION}`;
 
 export interface ThemeParksOptions {
@@ -51,6 +52,7 @@ export class ThemeParks {
         max: options.retry?.max ?? 3,
         on429: options.retry?.on429 ?? true,
         maxRetryAfterMs: options.retry?.maxRetryAfterMs ?? DEFAULT_MAX_RETRY_AFTER_MS,
+        respectRemaining: options.retry?.respectRemaining ?? true,
       },
       fetch: fetchFn,
     });
@@ -60,6 +62,26 @@ export class ThemeParks {
     this.destinations = new DestinationsApi(this.raw);
   }
 
+  /**
+   * What the server last said about your two budgets.
+   *
+   * `rateLimit.rest` is the per-minute REST meter; `rateLimit.history` is the
+   * separate hourly history budget. Every field can be null, because every
+   * field can legitimately be absent: an unmetered plan advertises nothing,
+   * and neither does a publicly cacheable response, since the figures are
+   * per-caller and a shared cache would hand one caller's to another.
+   *
+   * null therefore means "the server did not say", never "nothing left". Use
+   * `isExhausted`, which is true only when it said zero.
+   *
+   * Read from the inner transport rather than a copy, so a cache HIT -- which
+   * sends no request and so learns nothing -- correctly leaves the last known
+   * figures standing. A hit spent no budget either.
+   */
+  get rateLimit(): RateLimits {
+    return this.transport.rateLimit;
+  }
+
   entity(id: string): EntityHandle {
     return new EntityHandle(this.raw, id);
   }

src/index.ts

@@ -39,4 +39,5 @@ export {
   type LiveDataEntry,
   type LiveQueue,
 } from './ergonomic/live';
+export { isExhausted, secondsUntilReset, type RateLimit, type RateLimits } from './ratelimit';
 export { parseApiDateTime } from './dates';