From 43f5b1b3f0c04528d943e8138c17e533b3efd0dc 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
---
 src/Sockudo.php          | 66 ++++++++++++++++++++++++++++++++++++++++
 src/SockudoInterface.php | 15 +++++++++
 2 files changed, 81 insertions(+)

diff --git a/src/Sockudo.php b/src/Sockudo.php
index 18c9a59..e8f9fef 100755
--- a/src/Sockudo.php
+++ b/src/Sockudo.php
@@ -840,6 +840,33 @@ public function appendMessage(string $channel, string $messageSerial, array $par
         return $this->post('/channels/' . $channel . '/messages/' . $messageSerial . '/append', $params);
     }
 
+    /**
+     * Publish an annotation for a versioned message.
+     */
+    public function publishAnnotation(string $channel, string $messageSerial, array $params): object
+    {
+        $this->validate_channel($channel);
+        return $this->post('/channels/' . $channel . '/messages/' . $messageSerial . '/annotations', json_encode($params, JSON_THROW_ON_ERROR));
+    }
+
+    /**
+     * Delete an annotation from a versioned message.
+     */
+    public function deleteAnnotation(string $channel, string $messageSerial, string $annotationSerial, array $params = []): object
+    {
+        $this->validate_channel($channel);
+        return $this->delete('/channels/' . $channel . '/messages/' . $messageSerial . '/annotations/' . $annotationSerial, $params);
+    }
+
+    /**
+     * List raw annotation events for a versioned message.
+     */
+    public function listAnnotations(string $channel, string $messageSerial, array $params = []): object
+    {
+        $this->validate_channel($channel);
+        return $this->get('/channels/' . $channel . '/messages/' . $messageSerial . '/annotations', $params);
+    }
+
     /**
      * @deprecated in favour of getPresenceUsers
      */
@@ -897,6 +924,45 @@ public function get(string $path, array $params = [], $associative = false)
         return $body;
     }
 
+    /**
+     * DELETE arbitrary REST API resource using a synchronous http client.
+     * All request signing is handled automatically.
+     */
+    public function delete(string $path, array $params = [], $associative = false)
+    {
+        $path = $this->settings['base_path'] . $path;
+
+        $signature = $this->sign($path, 'DELETE', $params);
+
+        $headers = [
+            'Content-Type' => 'application/json',
+            'X-Pusher-Library' => 'sockudo-http-php ' . self::$VERSION,
+        ];
+
+        $response = $this->client->delete(ltrim($path, '/'), [
+            'query' => $signature,
+            'http_errors' => false,
+            'headers' => $headers,
+            'base_uri' => $this->channels_url_prefix(),
+            'timeout' => $this->settings['timeout'],
+        ]);
+
+        $status = $response->getStatusCode();
+
+        if ($status !== 200) {
+            $body = (string) $response->getBody();
+            throw new ApiErrorException($body, $status);
+        }
+
+        try {
+            $body = json_decode($response->getBody(), $associative, 512, JSON_THROW_ON_ERROR);
+        } catch (\JsonException $e) {
+            throw new SockudoException('Data decoding error.');
+        }
+
+        return $body;
+    }
+
     /**
      * POST arbitrary REST API resource using a synchronous http client.
      * All request signing is handled automatically.
diff --git a/src/SockudoInterface.php b/src/SockudoInterface.php
index 4d8ccb7..d3de949 100644
--- a/src/SockudoInterface.php
+++ b/src/SockudoInterface.php
@@ -169,6 +169,21 @@ public function deleteMessage(string $channel, string $messageSerial, array $par
      */
     public function appendMessage(string $channel, string $messageSerial, array $params = []): object;
 
+    /**
+     * Publish an annotation for a versioned message.
+     */
+    public function publishAnnotation(string $channel, string $messageSerial, array $params): object;
+
+    /**
+     * Delete an annotation from a versioned message.
+     */
+    public function deleteAnnotation(string $channel, string $messageSerial, string $annotationSerial, array $params = []): object;
+
+    /**
+     * List raw annotation events for a versioned message.
+     */
+    public function listAnnotations(string $channel, string $messageSerial, array $params = []): object;
+
     /**
      * GET arbitrary REST API resource using a synchronous http client.
      * All request signing is handled automatically.