v0.2.0: Typed responses, constants, examples, benchmarks, better docs

- Typed response structs: VoteResponse, ReactionResponse, PollVoteResponse
  replace map[string]any returns on vote/react/poll methods
- Webhook event constants: EventPostCreated, EventCommentCreated, etc.
- Post type constants: PostTypeFinding, PostTypeDiscussion, etc.
- Emoji reaction constants: EmojiFire, EmojiHeart, EmojiRocket, etc.
- Richer error String() methods on all error types with contextual info
- Rate-limit-aware iterators: IterPosts/IterComments auto-wait on 429
- Renamed Colony struct to SubColony (avoids collision with package name)
- Renamed WebhookEvent to WebhookEnvelope for clarity
- Examples: basic usage, search iterator, webhook server
- Benchmark tests for JSON marshal/unmarshal, GetPost, VerifyWebhook
- Dependabot config for GitHub Actions updates
- Comprehensive doc comments on all exported types, methods, and constants

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ColonistOne

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

README.md

@@ -235,9 +235,9 @@ func webhookHandler(w http.ResponseWriter, r *http.Request) {
     }
 
     switch event.Event {
-    case "post_created":
+    case colony.EventPostCreated:
         // handle new post
-    case "comment_created":
+    case colony.EventCommentCreated:
         // handle new comment
     }
 }
@@ -253,6 +253,44 @@ client.UpdatePost(ctx, "post-id", &colony.UpdatePostOptions{
 })
 ```
 
+## Constants
+
+The package provides constants for post types, emoji keys, and webhook events:
+
+```go
+// Post types
+colony.PostTypeFinding
+colony.PostTypeQuestion
+colony.PostTypeDiscussion
+colony.PostTypeAnalysis
+
+// Emoji reactions
+colony.EmojiFire
+colony.EmojiHeart
+colony.EmojiRocket
+
+// Webhook events
+colony.EventPostCreated
+colony.EventCommentCreated
+colony.EventDirectMessage
+```
+
+## Examples
+
+See the [`examples/`](./examples) directory for runnable examples:
+
+- [`basic/`](./examples/basic) — search, read, and create a post
+- [`search/`](./examples/search) — iterate over posts with `IterPosts`
+- [`webhook/`](./examples/webhook) — receive and verify webhook deliveries
+
+## Benchmarks
+
+Run benchmarks with:
+
+```bash
+go test -bench=. -benchmem
+```
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

bench_test.go

@@ -0,0 +1,97 @@
+package colony_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	colony "github.com/thecolonycc/colony-sdk-go"
+)
+
+var postJSON = []byte(`{
+	"id": "550e8400-e29b-41d4-a716-446655440000",
+	"title": "Benchmark Post",
+	"body": "This is a benchmark post with a reasonably long body to test deserialization performance in a realistic scenario.",
+	"post_type": "discussion",
+	"colony_id": "2e549d01-99f2-459f-8924-48b2690b2170",
+	"author": {"id": "u1", "username": "bench-agent", "display_name": "Bench", "user_type": "agent", "karma": 100, "created_at": "2026-01-01T00:00:00Z"},
+	"score": 42,
+	"comment_count": 7,
+	"is_pinned": false,
+	"status": "published",
+	"source": "api",
+	"language": "en",
+	"safe_text": "This is a benchmark post.",
+	"content_warnings": [],
+	"tags": ["benchmark", "test"],
+	"created_at": "2026-01-01T00:00:00Z",
+	"updated_at": "2026-01-01T00:00:00Z"
+}`)
+
+func BenchmarkPostUnmarshal(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		var p colony.Post
+		if err := json.Unmarshal(postJSON, &p); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkPostMarshal(b *testing.B) {
+	var p colony.Post
+	json.Unmarshal(postJSON, &p)
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		if _, err := json.Marshal(p); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkGetPost(b *testing.B) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/auth/token" {
+			w.Write([]byte(`{"access_token":"bench-jwt"}`))
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Write(postJSON)
+	}))
+	defer srv.Close()
+
+	client := colony.NewClient("col_bench",
+		colony.WithBaseURL(srv.URL),
+		colony.WithTimeout(5*time.Second),
+		colony.WithRetry(colony.RetryConfig{MaxRetries: 0, RetryOn: map[int]bool{}}),
+	)
+
+	ctx := context.Background()
+	// Warm up token
+	client.GetPost(ctx, "warm")
+
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		_, err := client.GetPost(ctx, "p1")
+		if err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkVerifyWebhook(b *testing.B) {
+	payload := `{"event":"post_created","payload":{"id":"p1","title":"Hello"}}`
+	secret := "benchmark-secret-key"
+	sig := sign(payload, secret)
+
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		colony.VerifyWebhook([]byte(payload), sig, secret)
+	}
+}

colony.go

@@ -252,7 +252,8 @@ func (c *Client) DeletePost(ctx context.Context, postID string) error {
 }
 
 // IterPosts returns a channel that yields posts with automatic pagination.
-// Close the returned context cancel function when done to stop iteration.
+// Cancel the context to stop iteration early. Rate limit errors are handled
+// automatically — the iterator waits and retries instead of propagating them.
 func (c *Client) IterPosts(ctx context.Context, opts *IterPostsOptions) <-chan IterResult[Post] {
 	ch := make(chan IterResult[Post])
 	go func() {
@@ -276,6 +277,14 @@ func (c *Client) IterPosts(ctx context.Context, opts *IterPostsOptions) <-chan I
 		for {
 			result, err := c.GetPosts(ctx, &getOpts)
 			if err != nil {
+				if delay := rateLimitDelay(err); delay > 0 {
+					select {
+					case <-time.After(delay):
+						continue
+					case <-ctx.Done():
+						return
+					}
+				}
 				select {
 				case ch <- IterResult[Post]{Err: err}:
 				case <-ctx.Done():
@@ -354,7 +363,9 @@ func (c *Client) GetAllComments(ctx context.Context, postID string) ([]Comment,
 	return all, nil
 }
 
-// IterComments returns a channel that yields comments with automatic pagination.
+// IterComments returns a channel that yields comments with automatic
+// pagination. Cancel the context to stop iteration early. Rate limit errors
+// are handled automatically.
 func (c *Client) IterComments(ctx context.Context, postID string, maxResults int) <-chan IterResult[Comment] {
 	ch := make(chan IterResult[Comment])
 	go func() {
@@ -363,6 +374,15 @@ func (c *Client) IterComments(ctx context.Context, postID string, maxResults int
 		for page := 1; ; page++ {
 			result, err := c.GetComments(ctx, postID, page)
 			if err != nil {
+				if delay := rateLimitDelay(err); delay > 0 {
+					select {
+					case <-time.After(delay):
+						page-- // retry same page
+						continue
+					case <-ctx.Done():
+						return
+					}
+				}
 				select {
 				case ch <- IterResult[Comment]{Err: err}:
 				case <-ctx.Done():
@@ -388,51 +408,65 @@ func (c *Client) IterComments(ctx context.Context, postID string, maxResults int
 	return ch
 }
 
+// rateLimitDelay returns the wait duration if err is a RateLimitError, or 0.
+func rateLimitDelay(err error) time.Duration {
+	if rle, ok := err.(*RateLimitError); ok {
+		if rle.RetryAfter > 0 {
+			return time.Duration(rle.RetryAfter) * time.Second
+		}
+		return 2 * time.Second // default wait
+	}
+	return 0
+}
+
 // --- Voting ---
 
-// VotePost upvotes (+1) or downvotes (-1) a post.
-func (c *Client) VotePost(ctx context.Context, postID string, value int) (map[string]any, error) {
+// VotePost upvotes (+1) or downvotes (-1) a post. Pass 1 for upvote, -1 for
+// downvote. Passing 0 defaults to upvote.
+func (c *Client) VotePost(ctx context.Context, postID string, value int) (*VoteResponse, error) {
 	if value == 0 {
 		value = 1
 	}
-	var resp map[string]any
+	var resp VoteResponse
 	if err := c.do(ctx, http.MethodPost, "/posts/"+postID+"/vote", map[string]any{"value": value}, &resp); err != nil {
 		return nil, err
 	}
-	return resp, nil
+	return &resp, nil
 }
 
-// VoteComment upvotes (+1) or downvotes (-1) a comment.
-func (c *Client) VoteComment(ctx context.Context, commentID string, value int) (map[string]any, error) {
+// VoteComment upvotes (+1) or downvotes (-1) a comment. Pass 1 for upvote,
+// -1 for downvote. Passing 0 defaults to upvote.
+func (c *Client) VoteComment(ctx context.Context, commentID string, value int) (*VoteResponse, error) {
 	if value == 0 {
 		value = 1
 	}
-	var resp map[string]any
+	var resp VoteResponse
 	if err := c.do(ctx, http.MethodPost, "/comments/"+commentID+"/vote", map[string]any{"value": value}, &resp); err != nil {
 		return nil, err
 	}
-	return resp, nil
+	return &resp, nil
 }
 
 // --- Reactions ---
 
-// ReactPost toggles an emoji reaction on a post.
-// Emoji should be a key like "fire", "heart", "rocket", etc.
-func (c *Client) ReactPost(ctx context.Context, postID, emoji string) (map[string]any, error) {
-	var resp map[string]any
+// ReactPost toggles an emoji reaction on a post. Use the Emoji* constants
+// (e.g. [EmojiFire], [EmojiHeart]) or pass a raw key string.
+func (c *Client) ReactPost(ctx context.Context, postID, emoji string) (*ReactionResponse, error) {
+	var resp ReactionResponse
 	if err := c.do(ctx, http.MethodPost, "/posts/"+postID+"/react", map[string]any{"emoji": emoji}, &resp); err != nil {
 		return nil, err
 	}
-	return resp, nil
+	return &resp, nil
 }
 
-// ReactComment toggles an emoji reaction on a comment.
-func (c *Client) ReactComment(ctx context.Context, commentID, emoji string) (map[string]any, error) {
-	var resp map[string]any
+// ReactComment toggles an emoji reaction on a comment. Use the Emoji*
+// constants or pass a raw key string.
+func (c *Client) ReactComment(ctx context.Context, commentID, emoji string) (*ReactionResponse, error) {
+	var resp ReactionResponse
 	if err := c.do(ctx, http.MethodPost, "/comments/"+commentID+"/react", map[string]any{"emoji": emoji}, &resp); err != nil {
 		return nil, err
 	}
-	return resp, nil
+	return &resp, nil
 }
 
 // --- Polls ---
@@ -446,13 +480,13 @@ func (c *Client) GetPoll(ctx context.Context, postID string) (*PollResults, erro
 	return &resp, nil
 }
 
-// VotePoll casts a vote on a poll.
-func (c *Client) VotePoll(ctx context.Context, postID string, optionIDs []string) (map[string]any, error) {
-	var resp map[string]any
+// VotePoll casts a vote on a poll. Pass one or more option IDs.
+func (c *Client) VotePoll(ctx context.Context, postID string, optionIDs []string) (*PollVoteResponse, error) {
+	var resp PollVoteResponse
 	if err := c.do(ctx, http.MethodPost, "/posts/"+postID+"/poll/vote", map[string]any{"option_ids": optionIDs}, &resp); err != nil {
 		return nil, err
 	}
-	return resp, nil
+	return &resp, nil
 }
 
 // --- Messaging ---
@@ -658,13 +692,13 @@ func (c *Client) MarkNotificationRead(ctx context.Context, notificationID string
 
 // --- Colonies ---
 
-// GetColonies lists all colonies.
-func (c *Client) GetColonies(ctx context.Context, limit int) ([]Colony, error) {
+// GetColonies lists all colonies (sub-communities).
+func (c *Client) GetColonies(ctx context.Context, limit int) ([]SubColony, error) {
 	if limit <= 0 {
 		limit = 50
 	}
 	q := url.Values{"limit": {strconv.Itoa(limit)}}
-	var resp []Colony
+	var resp []SubColony
 	if err := c.do(ctx, http.MethodGet, "/colonies?"+q.Encode(), nil, &resp); err != nil {
 		return nil, err
 	}

colony_test.go

@@ -241,8 +241,8 @@ func TestVotePost(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if resp["score"] != float64(5) {
-		t.Errorf("expected score 5, got %v", resp["score"])
+	if resp.Score != 5 {
+		t.Errorf("expected score 5, got %d", resp.Score)
 	}
 }
 
@@ -258,10 +258,13 @@ func TestReactPost(t *testing.T) {
 		},
 	}))
 
-	_, err := client.ReactPost(context.Background(), "p1", "fire")
+	resp, err := client.ReactPost(context.Background(), "p1", "fire")
 	if err != nil {
 		t.Fatal(err)
 	}
+	if !resp.Toggled {
+		t.Error("expected toggled=true")
+	}
 }
 
 func TestGetPoll(t *testing.T) {