feat: history endpoints and an API key option

[BeyondVertical]

Summary

Three commits:

1. chore: regenerate schema from upstream spec. Same three paths as chore: regenerate schema from upstream spec #41, with the spec's current wording, which has moved on since that branch was cut. If chore: regenerate schema from upstream spec #41 merges first this commit becomes empty on rebase.
2. feat: accept an API key and send it as X-API-Key.
3. feat: expose the history endpoints.

API key

The spec's ApiKeyAuth scheme is the X-API-Key header, and the client had no way to send one short of wrapping fetch. Every endpoint still answers without a key, but the history endpoints size their window and hourly budget by it: 7 days and 60 requests an hour anonymously, 30 days and 600 with a free key.

const tp = new ThemeParks({ apiKey: 'your-api-key' });

The header is sent when the key is a non-empty string and not at all otherwise; a client without a key sends the same two headers as before. The cache key is still the path.

History

call	path	answers
tp.entity(id).history.changes(query)	GET /entity/{id}/history	one row per change: the live-data object plus time, changed
tp.entity(id).history.daily(query)	GET /entity/{id}/history/daily	one row per park-local day: operating minutes, standby stats
tp.entity(id).history.coverage()	GET /entity/{id}/history/coverage	which days and which live-data fields are held

tp.raw.getEntityHistory, getEntityHistoryDaily and getEntityHistoryCoverage sit underneath. The query type is the generated operation's own ({ date } or { from, to }), so it cannot drift from the spec, and it is sent through URLSearchParams:

{ from: '2026-09-17T10:00:00+02:00', to: '2026-09-17T12:00:00+02:00' }
→ /entity/{id}/history?from=2026-09-17T10%3A00%3A00%2B02%3A00&to=…

A bare + in a query string is a space, so concatenation would have shifted every instant with a positive offset by its own offset.

The response types are the spec's unions. A PARK answers with entities[] for every entity in it; every other entity type, a DESTINATION included, answers for itself with history[] / days[]. 'entities' in res narrows them, and the README shows that.

Cache policy: coverage for an hour, as its values are whole days; changes and daily uncached, since a range that holds today is not final. Documented in the TTL table.

Errors surface as they do elsewhere: a day outside the window is a 403 ApiError whose body.error.earliestAllowedDate names the first day allowed; over the hourly budget is a 429 RateLimitError. The README notes that the budget's Retry-After can be most of an hour and that the default retry.on429 honours it, and shows retry: { on429: false } for a poller that would rather fail fast.

Fixtures

Real responses from 2026-09-17, trimmed to a few rows and entities: The Barnstormer's day (history[]), Magic Kingdom's day (entities[], including a restaurant with history: [], present but unchanged), Magic Kingdom's daily statistics, Magic Kingdom's coverage, and the real 403 body for a day outside the anonymous window.

Test plan

• npm test: 86 unit tests across 12 files (64 on main): 4 for the key, 18 for history (paths, query encoding including the + case, the four fixtures, the 403 body, the entity handle, the cache policy)
• npm run test:live: 6 passed, including the two new cases (Magic Kingdom coverage; today's history answers for the whole park)
• npm run lint, npx prettier --check ., npm run typecheck, npm run build
• The README example compiled under the repository's strict settings before it went in

Not in this PR

• Stitching a range longer than 31 days out of several calls, the way schedule.range() stitches months.
• Dedicated error classes for HISTORY_WINDOW_EXCEEDED / HISTORY_RATE_LIMITED; the typed bodies are on err.body.
• Capping how long the transport sleeps on a Retry-After.
• Unrelated observation: PACKAGE_VERSION in src/client.ts is still 7.0.0-alpha.0, so the default user agent reads themeparks-sdk-js/7.0.0-alpha.0 on 8.0.0. Happy to send a one-line PR.

🤖 Generated with Claude Code

[cubehouse]

Reviewed and merging. Thank you for this, particularly the cache TTLs and the URLSearchParams point about a bare + in an offset, which is a genuinely easy one to get wrong.

Two things I found that I will fix in a follow-up rather than hold this up for.

EntityHistoryCoverage needs to be a union. /history/coverage answers a PARK with HistoryParkCoverageDocument, the same way /history and /history/daily do, and the type here names only HistoryCoverageDocument. The two shapes do not overlap where it counts: a park carries summary and fields, an entity carries firstRecordedAt, lastRecordedAt and kinds. So a TypeScript user reads .kinds off a park's coverage, gets undefined at runtime, and the compiler says nothing.

Checked against production just now for Magic Kingdom:

keys = destinationId, entities, entityType, fields, id, name, parentId, summary, timezone

The live smoke test will fail on the next drift run for the same reason:

const c = await tp.entity(MK_ID).history.coverage();
expect(typeof c.kinds).toBe('object');   // 'undefined' - MK is a PARK

CI did not catch it because the live suite only runs in the drift workflow. I will widen the type, branch the assertion, and add a park fixture alongside your entity one.

The follow-up also adds what sits above these calls: following next on a paged park daily response, flattening a park envelope to the same row stream as an entity one, and not sleeping through a history 429 (that budget is hourly, so honouring Retry-After three times can park the process for hours).