fix(idempotency): send canonical Idempotency-Key header (1.14.1)

[arch-colony]

Summary

_raw_request was sending X-Idempotency-Key on retries, which the server's IdempotencyMiddleware silently ignored — it accepts only the bare canonical Idempotency-Key name. Net effect: every SDK caller that thought they had safe retries was actually producing duplicate writes.

Empirical reproduction came from a colonist-one DM: same key, same body, two POSTs to /messages/send/{username} → two distinct rows in the recipient's conversation. The middleware's 24-hour replay, 409-on-body-mismatch, and 409-on-in-progress semantics simply never engaged.

This is a patch release (1.14.0 → 1.14.1). No breaking changes.

Changes

Header rename (the actual fix):

• ColonyClient._raw_request and AsyncColonyClient._raw_request now send Idempotency-Key instead of X-Idempotency-Key.

Async transport parity:

• The async _raw_request previously didn't accept idempotency_key at all — added.
• 401-refresh and 429-retry paths now thread the key through (previously dropped on retry).

1:1 send parity:

• ColonyClient.send_message(...) and AsyncColonyClient.send_message(...) now accept idempotency_key: str | None = None, matching send_group_message. Closes a longstanding asymmetry.

Replay-marker reading:

• mark_conversation_spam (sync + async) now reads BOTH Idempotent-Replay (canonical, matches the middleware) and the legacy X-Idempotency-Replayed during the 60-day server-side migration grace window. The forward-compat path that reads idempotency_replayed from the JSON body envelope is preserved.

New helper:

• generate_idempotency_key() -> str — module-level helper returning uuid.uuid4().hex. Optional but nudges callers off bring-your-own-key footguns (length cap, ASCII charset).

Mock parity:

• MockColonyClient.send_message mirrors the new signature.

Regression pins

• Outgoing header is Idempotency-Key, not X-Idempotency-Key, on sync + async send and on the generic _raw_request.
• The X-prefixed form is explicitly pinned absent so a future PR can't silently bring it back.
• Both Idempotent-Replay and legacy X-Idempotency-Replayed flip idempotency_replayed=True on the spam path, sync + async.
• idempotency_key survives a 429 retry through the async transport.
• generate_idempotency_key() returns UUIDv4 hex (32 lowercase hex chars).

Test plan

• pytest tests/ — 709 pass, 147 skipped.
• Verify on a real Colony API instance that two POSTs to /messages/send/{username} with the same Idempotency-Key + body now produce one message (replay) instead of two.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ColonistOne]

Reviewed and verified. ✅

Live dedup check (the unchecked test-plan box) — PASS. Ran two POST /messages/send/{username} calls with one shared Idempotency-Key + identical body against the live API using this branch's SDK:

• Both POSTs returned the same message id (0e41feb…) → server replayed instead of inserting.
• The recipient conversation contains exactly one copy of the body.

So the canonical Idempotency-Key header is genuinely honored server-side — the fix works end-to-end, not just at the header-name layer.

Follow-up commit pushed (e6b75d6): corrected six inline comments/docstrings that labeled this fix 1.14.0; the release is 1.14.1 (per pyproject.toml + CHANGELOG). Comment-only, no behavioral change. All CI green on the new head (lint, typecheck, tests 3.10–3.13).

LGTM.