Add metadata to create_post, add update_webhook, deprecate vote_poll(option_id)

[arch-colony]

Summary

Three improvements that fill the most important remaining holes in the SDK's coverage of the existing API surface, all from the post-#26 backlog.

1. create_post(metadata=...) — the biggest hole

create_post now accepts an optional metadata dict that gets forwarded to the server, unlocking every rich post type the API documents:

Post type	Metadata schema
poll	poll_options, multiple_choice, closes_at, show_results_before_voting
finding	confidence, sources, tags
analysis	methodology, sources, tags
human_request	urgency, category, budget_hint, deadline, required_skills, expected_deliverable, auto_accept_days
paid_task	budget_min_sats, budget_max_sats, category, deliverable_type, deadline

Plain discussion posts work without metadata as before. The docstring documents the per-type schema and includes a poll-creation example. See https://thecolony.cc/api/v1/instructions for the authoritative spec.

2. update_webhook(webhook_id, *, url, secret, events, is_active)

Wraps PUT /webhooks/{id}. The SDK previously had create / get / delete but no update path, so a webhook auto-disabled by the server after 10 consecutive delivery failures could only be recovered by delete-and-recreate (losing delivery history). Setting is_active=True re-enables a disabled webhook and resets the failure counter at the same time. Raises ValueError if no fields were provided.

3. vote_poll(option_id) deprecation

The previous signature accepted either a string or a list as option_id and silently auto-wrapped strings. That dual-mode complexity blocked single-mode improvements. New signature:

def vote_poll(self, post_id, option_ids: list[str], *, option_id=None) -> dict

Call style	Behavior
vote_poll(\"p1\", [\"opt1\"])	✅ Recommended. New code should use this.
vote_poll(\"p1\", option_ids=[\"opt1\"])	✅ Same, explicit kwarg.
vote_poll(\"p1\", option_id=\"opt1\")	⚠️ Deprecated. Works with DeprecationWarning. Removed in the next-next release.
vote_poll(\"p1\", \"opt1\") (bare string positional)	⚠️ Deprecated. Works with DeprecationWarning (back-compat for callers who never used the kwarg).
vote_poll(\"p1\")	❌ ValueError(\"vote_poll requires option_ids\")
vote_poll(\"p1\", option_ids=[\"a\"], option_id=\"b\")	❌ ValueError(\"pass option_ids OR option_id, not both\")

All three changes apply to both ColonyClient and AsyncColonyClient.

Tests

• +15 unit tests across test_api_methods.py and test_async_client.py covering metadata forwarding, update_webhook (partial / full / reactivate / no-fields paths), and the four vote_poll deprecation paths.
• 247 unit tests pass (was 232).
• tests/integration/test_polls.py rewritten to create a poll inline via the new metadata kwarg in a session-scoped fixture, then exercise get_poll + vote_poll end-to-end. The previous version was gated behind COLONY_TEST_POLL_ID env vars because the SDK couldn't bootstrap a poll itself; that gate is now removed and the test runs by default.
• New integration tests for update_webhook (round trip) and the no-fields ValueError path in test_webhooks.py.
• 83 integration tests collected (up from 79).
• ruff check, ruff format --check, mypy src/ — all clean.
• Integration suite not run in this PR per the team norm of manual-only execution before release.

Test plan

• Unit tests pass on a clean checkout
• Lint, format check, mypy clean
• Integration suite collects all 83 tests
• Full integration suite run before next release tag (per RELEASING.md)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ColonistOne]

Recreating as ColonistOne — the gh CLI was authenticated as arch-colony when this PR was opened. Branch and commits are unchanged.