[sergical]

Stacked on #66. Merge #65 and #66 first; GitHub then retargets this PR to main.

Problem

User feedback PLAUSIBLE-MCP-Q (from our own deployment, release 0.9.0): get_breakdown with date_range: "1h" returned Plausible API returned 400: #/date_range: Invalid date range "1h". The user wanted the custom events from the last ~10 minutes, and get_timeseries had no sub-day buckets.

Plausible's query schema accepts "24h" as its only hour shorthand. Our dateRangeSchema accepted any \d+h, so the error reached Plausible instead of failing at our schema. The same schema also accepts two things we did not expose: a pair of ISO 8601 datetimes (date_time_range) and the time:hour dimension.

Changes

• Nh works for any N. encodeDateRange sends "Nh" as [now - N hours, now] in UTC, to second precision. This includes "24h", so all hour ranges follow one rule.
• Sub-day windows. date_range accepts "<datetime>,<datetime>", where each datetime is YYYY-MM-DDTHH:MM:SS with Z or ±HH:MM. A pair that mixes a date and a datetime is rejected, as Plausible also rejects it.
• Hourly buckets. get_timeseries accepts granularity: "hour", which maps to time:hour.
• No silent truncation. Plausible returns at most 10,000 rows and drops the rest without a flag, which an hourly series over a long range reaches. get_timeseries now fails at that limit and tells the caller to narrow date_range or use a coarser granularity. PLAUSIBLE_MAX_ROWS moves to plausible.ts, so get_breakdown uses the same constant.
• Docs. SERVER_INSTRUCTIONS and the field descriptions show the new forms. They also say that minute buckets are not available, because time:minute is internal to Plausible.

Tests

• dateRangeSchema accepts and rejects each form.
• The client encodes a datetime pair as a tuple, and "1h" as a rolling window under fake timers.
• get_timeseries maps "hour" to time:hour, and rejects a 10,000-row result.

pnpm typecheck, pnpm build and pnpm test (288 tests, on top of the updated #66) pass locally.

Created with Claude Code