Add blob.download command and attachment metadata to email.read

[turian]

Summary

• blob.download: New command that downloads a blob to a local file path using the JMAP session downloadUrl URI template (RFC 8620 §6.2). Returns a JSON envelope with metadata — never writes binary to stdout, preserving the CLI's "every command returns a JSON envelope" convention.
• email.read attachments: Now includes an attachments array with partId, blobId, name, type, and size for each attachment, enabling a clean two-step agent workflow.

Agent workflow example

# Step 1: Read email, discover attachments
fastmail-cli email.read --id StqohozpQSO7 --json pretty
# → data.attachments[0] = {blobId: "G70a...", name: "Invoice.pdf", type: "application/pdf", size: 29174}

# Step 2: Download attachment
fastmail-cli blob.download \
  --blob-id "G70a0de1bb1905db4c4b6295951910d78877bf722" \
  --name "Invoice-99F05531-0017.pdf" \
  --type "application/pdf" \
  --output "./invoice.pdf"
# → {ok: true, data: {bytesWritten: 29174, sha256: "d4d2...", output: "./invoice.pdf"}}

blob.download envelope fields

Field	Description
blobId	The blob ID that was downloaded
name	Filename passed to the server
contentType	MIME type passed to the server
output	Local file path written to
bytesWritten	Number of bytes written
sha256	SHA-256 hex digest of the downloaded content

Test plan

Tested against live Fastmail API:

• email.query --filter '{"hasAttachment": true}' to find email with attachment
• email.read --id <id> returns attachments array with blobId, name, type, size, partId
• email.read on email without attachments returns attachments: []
• blob.download with blobId/name/type/output downloads file successfully
• Downloaded file verified as valid PDF (file command), correct size (29174 bytes matches attachment metadata)
• JSON envelope includes sha256 hash and bytesWritten
• API token redacted in envelope args
• describe blob.download shows all four required options
• help lists blob.download with correct summary

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e0f04a9e32

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Expand downloadUrl variables with URI encoding

downloadUrl is a URI template, but this code uses plain str.format(...) with raw blob_id/name/type values. When an attachment name contains reserved characters (for example #, /, ?, or non-ASCII text), the generated URL is malformed or semantically different (# becomes a fragment, / changes path segments), so blob.download can fail or fetch the wrong resource for valid inputs. Use proper URI-template expansion (or percent-encode each variable according to RFC6570 rules) before issuing the request.

Useful? React with 👍 / 👎.

[turian]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".