Reach the whole draft settings panel from update_draft, cover image included

[marcomoauro]

What changed

update_draft goes from 3 settable fields to 11 — the draft editor's entire Post settings panel:

Field	Values
audience	everyone | only_paid | only_free | founding
write_comment_permissions	everyone | subscribers | only_paid | none
default_comment_sort	best_first | most_recent_first | oldest_first
cover_image	any URL — re-hosted if it is not already on Substack
social_title, description	the social preview
search_engine_title, search_engine_description, slug	SEO Options

only_free is a bug fix, not an addition: the API accepts it and the editor offers it, but the enum refused it, so a legal audience was unreachable.

The guarded-download pipeline moves out of src/tools/upload_image.js into src/api/substack/image.js, shared by both callers — a second copy of an SSRF guard is a second place to get it wrong. Its errors are prefixed image: so a cover_image failure is not signed by a tool the caller never invoked. upload_image.js becomes a thin tool over it and re-exports isPrivateAddress/MAX_IMAGE_BYTES so its spec's imports keep working.

Why it looks like this

Everything below was measured on implementing.substack.com on 2026-08-08, one single-key PUT /api/v1/drafts/:id at a time, each read back with a GET.

• Six neighbouring fields answer 200 and change nothing — postSchedules, language, email_from_name, is_draft_hidden, ai_detection_disabled, free_unlock_required. They stay off the schema so strictObject tells a model the key does not exist instead of letting it believe it scheduled a post. That is the seventh distinct silent-ignore in this API.
• Validation is asymmetric, and worst where it matters most. A bad audience or default_comment_sort answers 400 naming the parameter; a bad write_comment_permissions answers {"error":"Something went wrong"} with no field and no valid set. Its zod enum is the only diagnosis a caller will ever get.
• cover_image is not validated at all — the literal string "not-a-url-at-all" was accepted with a 200 and stored. Since Substack server-fetches only its own bucket, an external cover is stored happily and never renders. So a URL on substack-post-media.s3.amazonaws.com or substackcdn.com is forwarded unchanged (re-hosting one would duplicate an asset Substack already serves) and anything else is downloaded and re-uploaded first.
• The re-host runs before the PUT. A download failure must not leave the other eight fields written with the cover silently unchanged.

Deliberately out of scope, with reasons recorded in CLAUDE.md: scheduling (not reachable through this endpoint at all), draft_section_id (the server validates the id, but this publication has no sections so the success path cannot be verified), and should_send_email (publish_draft already writes it as the publish intent — a second door onto the one flag that can mail the whole list is not worth the convenience).

Test plan

• npm test green on the .nvmrc runtime (Node 24) and on the engines floor (Node 22): 725 passing, 0 failing
• Each of the 11 fields reaches the PUT body under its wire name
• only_free accepted — the regression the old enum had
• A Substack-hosted cover produces no call to /api/v1/image
• An external cover produces the upload then the PUT, with the S3 URL in the body
• A failed re-host leaves no PUT at all
• strictObject rejects postSchedules and language by name
• The no-fields message is derived from the schema, so it cannot rot when a field is added
• Every new assertion was broken on purpose and confirmed failing before being trusted — seven mutations, each verified to have landed with a grep first
• additionalProperties: false still published on tools/list; the session token never reaches the log; npm pack excludes the new spec

Live-verified end to end, which also closes a gap CLAUDE.md recorded as open: every earlier measurement used the browser session cookie, leaving SUBSTACK_SESSION_TOKEN in a header through SubstackApi untested. A scratch draft was driven through create_draft_post → update_draft with all nine settings and an external upload.wikimedia.org cover → get_draft → delete_draft using that env var. All 11 fields read back exactly as sent and the cover came back on Substack's S3 bucket. The scratch draft was deleted.

For the reviewer

• The design and the task-by-task plan are committed alongside the code, in docs/superpowers/specs/2026-08-08-draft-settings-design.md and docs/superpowers/plans/2026-08-08-draft-settings.md.
• src/tools/upload_image.js shrinks by ~120 lines with no changes to its spec — the four error fragments it asserts (/not an image/, /HEIC is not accepted/, /only http and https/, /over the .* limit/) all survive the prefix change. That is the check to be most sceptical of.
• POST /api/v1/image is called with post_id: null for the cover. The endpoint accepts a postId, but its effect is unconfirmed and was never measured against a draft, so it is not passed.
• Unrelated and left alone: CLAUDE.md's draft-lifecycle section promises "two things follow from DELETE being shared with published posts" but an earlier bad merge welded two sentences together and one of the two lost its subject. Flagged separately rather than fixed here.

🤖 Generated with Claude Code