From 8fb2218be603c5c3d034a9dd3af33674df574559 Mon Sep 17 00:00:00 2001
From: Diaconu Radu-Mihai <52667211+countradooku@users.noreply.github.com>
Date: Wed, 29 Apr 2026 09:10:09 +0200
Subject: [PATCH] Expose message annotations in the server SDK

Add Sockudo 4.4 message annotation request and response surfaces for publishing, deleting, and listing raw annotation events through trusted backend SDKs.

Constraint: Annotation REST calls use the existing signed app HTTP API

Confidence: medium

Scope-risk: moderate

Tested: git diff --check

Not-tested: SDK-specific test suite
---
 lib/sockudo/channel.rb  | 15 +++++++++++++++
 lib/sockudo/client.rb   | 21 +++++++++++++++++++++
 lib/sockudo/request.rb  |  4 ++++
 lib/sockudo/resource.rb |  4 ++++
 4 files changed, 44 insertions(+)

diff --git a/lib/sockudo/channel.rb b/lib/sockudo/channel.rb
index 50c50d6..08d4aa8 100644
--- a/lib/sockudo/channel.rb
+++ b/lib/sockudo/channel.rb
@@ -157,6 +157,21 @@ def append_message(message_serial, params = {})
       @client.append_message(name, message_serial, params)
     end
 
+    # Publish an annotation for a versioned message.
+    def publish_annotation(message_serial, params = {})
+      @client.publish_annotation(name, message_serial, params)
+    end
+
+    # Delete an annotation from a versioned message.
+    def delete_annotation(message_serial, annotation_serial, params = {})
+      @client.delete_annotation(name, message_serial, annotation_serial, params)
+    end
+
+    # List raw annotation events for a versioned message.
+    def list_annotations(message_serial, params = {})
+      @client.list_annotations(name, message_serial, params)
+    end
+
     # Request users for a presence channel
     # Only works on presence channels (see: http://sockudo.com/docs/client_api_guide/client_presence_channels and https://sockudo.com/docs/rest_api)
     #
diff --git a/lib/sockudo/client.rb b/lib/sockudo/client.rb
index e6b5ada..1a4eace 100644
--- a/lib/sockudo/client.rb
+++ b/lib/sockudo/client.rb
@@ -201,6 +201,12 @@ def post(path, params = {}, headers = {})
       resource(path).post(params, headers)
     end
 
+    # DELETE arbitrary REST API resource using a synchronous http client.
+    # All request signing is handled automatically.
+    def delete(path, params = {})
+      resource(path).delete(params)
+    end
+
     # POST arbitrary REST API resource using an asynchronous http client.
     # Works identially to get_async method, but posts params as JSON in post
     # body.
@@ -336,6 +342,21 @@ def append_message(channel_name, message_serial, params = {})
       post("/channels/#{channel_name}/messages/#{message_serial}/append", params)
     end
 
+    # Publish an annotation for a versioned message
+    def publish_annotation(channel_name, message_serial, params = {})
+      post("/channels/#{channel_name}/messages/#{message_serial}/annotations", params)
+    end
+
+    # Delete an annotation from a versioned message
+    def delete_annotation(channel_name, message_serial, annotation_serial, params = {})
+      delete("/channels/#{channel_name}/messages/#{message_serial}/annotations/#{annotation_serial}", params)
+    end
+
+    # List raw annotation events for a versioned message
+    def list_annotations(channel_name, message_serial, params = {})
+      get("/channels/#{channel_name}/messages/#{message_serial}/annotations", params)
+    end
+
     # Request info for users of a presence channel
     #
     # GET /apps/[id]/channels/[channel_name]/users
diff --git a/lib/sockudo/request.rb b/lib/sockudo/request.rb
index 26144e6..0c66b8f 100644
--- a/lib/sockudo/request.rb
+++ b/lib/sockudo/request.rb
@@ -59,6 +59,10 @@ def send_async
                  http_client.get({
                                    query: @params, head: @head
                                  })
+               when :delete
+                 http_client.delete({
+                                      query: @params, head: @head
+                                    })
                else
                  raise 'Unsupported verb'
                end
diff --git a/lib/sockudo/resource.rb b/lib/sockudo/resource.rb
index b87b14c..78fe886 100644
--- a/lib/sockudo/resource.rb
+++ b/lib/sockudo/resource.rb
@@ -25,6 +25,10 @@ def post_async(params, headers = {})
       create_request(:post, {}, body, headers).send_async
     end
 
+    def delete(params)
+      create_request(:delete, params).send_sync
+    end
+
     private
 
     def create_request(verb, params, body = nil, extra_headers = {})