Fix export_subscribers aborting on the export's pending poll

[marcomoauro]

Fixes #25.

export_subscribers failed on every call, with any arguments. The reported symptom is real and 100% reproducible; the reported cause is not the one.

The cause is the poll, not the query

While Substack generates the file, GET /subscriber_set/export/<id> answers 400 {"error":"Export not ready","type":"single"} — not a 200 with an absent url, which is what this repo believed and what the suite mocked. The tool's first poll is immediate and generation takes ~3s even for 6 rows, so every export hit that 400 and readBody turned it into a fatal error.

Measured live 2026-09-03, polling a fresh 6-row export at 250ms:

+0.17s 400 Export not ready
 ...   400 Export not ready      (7 polls)
+2.71s 400 Export not ready
+3.29s 200 {"url":"/api/v1/subscriber_set/export/…/file"}

A 200 with an absent url was never observed at any point. The polling condition tested a state that does not exist, while the state that does exist threw.

The failure rate is 100% rather than intermittent because of a conjunction: the first poll is immediate and any non-2xx is fatal. Either alone would have been harmless — the optimisation meant to save one second is what guarantees the first poll lands inside the 400 window.

What the issue got wrong, for the record

The reported cause — buildSubscriberQuery passing sort_direction to createSubscriberSet — is not reachable. export_subscribers takes only the filters object and drops the rest (export_subscribers.js:111), sort_direction is never part of that function's output, and the tool's schema does not expose sorting at all. Live: POST /subscriber_set with {"query":{"activity_rating_gte":4}} → 200. Intercepting a real no-argument call gives {"query":{}}, the body the issue itself lists as 200. A test already pinned that body (export_subscribers.spec.js:122). Acting on the stated cause would have changed nothing and left the tool broken.

The change

• getSubscriberSetExport translates that one body into {pending: true} and rethrows every other 400 — an export that will never arrive has to fail now rather than poll out the caller's wait budget.
• readBody attaches status and body to the error it throws. The message carried only the status, so Substack's explanation of a refusal was readable in the log and nowhere else, and no caller could tell one 400 from another. That is why this presented as a bare 400 Bad Request naming none of the four steps — and, I'd argue, why the issue's diagnosis went wrong: an uninformative error does not just slow diagnosis down, it invites a plausible wrong one.

export_subscribers.js is unchanged: {pending: true} carries no url, so the existing loop, backoff, budget and timeout message all work as they are, and an absent url still means retry in case that state ever exists.

Verification

• Live, end to end, after the fix — the same call that previously threw SubstackAPIException: 400 Bad Request:

POST /subscriber_set              → 200
POST /subscriber_set/export       → 200
GET  /export/…  +0.2s             → 400  → substack.export.pending
GET  /export/…  +1.3s             → 400  → substack.export.pending
GET  /export/…  +6.3s             → 200  {url}
GET  /export/…/file               → 200  text/csv
export_subscribers.done  count: 6, waited_seconds: 6

• 5 new tests, confirmed red before the fix, covering the pending 400, a non-pending 400 still aborting, and status/body on the error.
• 753 pass / 0 fail on both supported runtimes (the engines floor, 22, and .nvmrc, 24).
• Protocol surface unchanged: handshake ok, 27 tools.

Why 748 green tests missed it

The pending state was mocked as 200 {}, so the suite stayed green while the tool failed every time in production. That mock described the wrong universe, so no assertion over it could have failed however thorough it was — the mocks are ours, so the suite measures this repo's model of Substack and never Substack.

CLAUDE.md therefore gains the two rules that follow, next to "A new test that passes on the first run has proven nothing":

1. A fixture representing an API state must cite where that state was observed; a transient or error-state fixture is corrected by nobody, unlike a happy-path one, so those are the ones to suspect.
2. A time-dependent flow is verified by running the real handler, never by hand. Hand-issued requests land seconds apart and cannot enter a 3-second window; the code polls 200ms in and cannot avoid it. The technique was already in the file — the token check drove the real handlers and read the log — it just had not been applied here.

Out of scope, noted while verifying

group_membership does export (measured: 46 columns requested → 45 returned, only tag_ids missing). CLAUDE.md and the tool's own description still claim two columns are undeliverable, which misleads a calling model. Left for a separate change rather than mixed into a bugfix.

🤖 Generated with Claude Code