Reject --sort-by where the API has no sortBy parameter

[arcaputo3]

Closes #4. Stacked on #9 (review the second commit only).

What the API actually does

Verified against the live API rather than inferred:

Request	Result
/events?sortBy=bogus	400 — sortBy must be one of the following values: id, date
/documents/transcripts?sortBy=date	400 — property sortBy should not exist
/documents/transcripts?direction=desc	200, and it does reverse the order

So /events is the only list endpoint with a sortBy parameter, and its enum is id, date. The issue reports the flag as "silently dropped" — it is: toParams gates every parameter on a per-resource allow-list and sortBy is only in the events set, so the flag never reaches the wire and nothing complains.

That silence is the whole bug. Document endpoints return rows in insertion order, so transcripts list --tickers X --sort-by date --direction desc yields the oldest transcripts on page one, looking exactly like a correct answer.

Change

• resource.sortFields records the accepted enum per resource; only events has one.
• validateSortBy rejects an unknown field on events, and any --sort-by on a resource that cannot sort, before any request goes out.
• Usage failures now exit 2 (new usageError type, mapped in Run) so scripts can tell a bad command line from a failed request.
• pages/chapters reject --sort-by too — they inherit the shared list flags but sort by nothing.
• The error and --help share one recipe paragraph, so they cannot drift apart.

--direction is deliberately untouched: it is accepted everywhere and works, it just reverses insertion order rather than date order. The message says so, since that distinction is what makes the flag misleading.

$ quartr transcripts list --tickers AAPL --sort-by date
--sort-by is not supported by `quartr transcripts list`: the Quartr endpoint has no
sortBy parameter, so rows come back in insertion order and the newest items may be
missing from the first page.

Sort events first, then fetch by event id:
  quartr events list --tickers AAPL --sort-by date --direction desc --limit 5
  quartr transcripts list --event-ids <id>

`--direction asc|desc` is accepted here, but it reverses insertion order, not date order.
$ echo $?
2

On companies list, where --event-ids does not exist, the recipe collapses to "only events list supports --sort-by".

Tests

Four cases: rejection on an unsortable resource (asserting no HTTP request is made), unknown field on events, sortBy/direction still forwarded for a valid events sort, and rejection on pages.

🤖 Generated with Claude Code