docs(relay): a repeated idempotency key replays, it does not 409

[ZhukMax]

Follows nautilus v1.7.3, which gave /v1/relay/* a translation layer so the gateway answers the contract we publish instead of its upstream's.

Docs and one test — no behaviour change. The request this SDK builds was already the documented one.

The test asserted a promise the API does not keep

test_send_throws_on409_duplicate mocked a 409 and expected an exception. A second send with an idempotency_key that was already accepted returns 202 with the originally accepted message — same id, same timestamp. That is the more useful contract: a retry of a request whose response you never saw needs no special handling, because there is no duplicate to tell apart from a success.

Replaced with test_send_replays_a_repeated_idempotency_key, which drives two sends under one key and asserts the same message comes back. Error mapping is not lost with it — test_send_throws_verne_api_exception_on400 and test_send_throws_on401 already cover that, on statuses the API really returns.

Worth knowing: until v1.7.3 the key did nothing at all. It is a body member in our reference and a header at the upstream, and the upstream drops body members it does not recognise — so every send was non-idempotent no matter what the caller passed. The gateway now maps it across.

MessagesResource had no docblocks

So the parameters now say what they do:

• the idempotency semantics above
• limit above 100 is clamped to 100 rather than rejected
• cursor takes a previous nextCursor, which is null on the last page — paginate until hasMore is false, not until data comes back empty

Until v1.7.3 cursor and eventType were forwarded to an upstream that names them differently and ignores what it does not recognise, so both were silently no-ops.

Message::$status is documented as always accepted: it records that Relay took the event, not what each subscriber endpoint did with it.

Companion PRs

Same correction in vrn-sdk-node, vrn-sdk-python and nautilus-rs.

🤖 Generated with Claude Code