From fb21211ae83050be73ef9029e8197d2aec0c7f0c Mon Sep 17 00:00:00 2001
From: Jake Barnby <jakeb994@gmail.com>
Date: Fri, 20 Mar 2026 13:08:19 +1300
Subject: [PATCH] fix: return \$sequence as string and add V21 backward-compat
 filters

---
 .../SDK/Specification/Format/OpenAPI3.php     |  3 +-
 .../SDK/Specification/Format/Swagger2.php     |  3 +-
 src/Appwrite/Utopia/Response/Filters/V21.php  | 32 +++++++++++++++++++
 .../Utopia/Response/Model/Document.php        |  4 +--
 src/Appwrite/Utopia/Response/Model/Row.php    |  4 +--
 5 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php
index 7c7fc96b2f..9edf923092 100644
--- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php
+++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php
@@ -843,8 +843,7 @@ class OpenAPI3 extends Format
                         break;
 
                     case 'id':
-                        $type = 'integer';
-                        $format = $rule['format'] ?? 'int32';
+                        $type = 'string';
                         break;
 
                     case 'enum':
diff --git a/src/Appwrite/SDK/Specification/Format/Swagger2.php b/src/Appwrite/SDK/Specification/Format/Swagger2.php
index 558e911c33..0d79320033 100644
--- a/src/Appwrite/SDK/Specification/Format/Swagger2.php
+++ b/src/Appwrite/SDK/Specification/Format/Swagger2.php
@@ -823,8 +823,7 @@ class Swagger2 extends Format
                         break;
 
                     case 'id':
-                        $type = 'integer';
-                        $format = $rule['format'] ?? 'int32';
+                        $type = 'string';
                         break;
 
                     case 'enum':
diff --git a/src/Appwrite/Utopia/Response/Filters/V21.php b/src/Appwrite/Utopia/Response/Filters/V21.php
index 37f9e01b86..f184471317 100644
--- a/src/Appwrite/Utopia/Response/Filters/V21.php
+++ b/src/Appwrite/Utopia/Response/Filters/V21.php
@@ -23,6 +23,18 @@ class V21 extends Filter
                 "functions",
                 fn ($item) => $this->parseFunction($item),
             ),
+            Response::MODEL_DOCUMENT => $this->parseDocument($content),
+            Response::MODEL_DOCUMENT_LIST => $this->handleList(
+                $content,
+                "documents",
+                fn ($item) => $this->parseDocument($item),
+            ),
+            Response::MODEL_ROW => $this->parseRow($content),
+            Response::MODEL_ROW_LIST => $this->handleList(
+                $content,
+                "rows",
+                fn ($item) => $this->parseRow($item),
+            ),
             default => $content,
         };
     }
@@ -46,4 +58,24 @@ class V21 extends Filter
         unset($content['runtimeSpecification']);
         return $content;
     }
+
+    protected function parseDocument(array $content): array
+    {
+        if (isset($content['$sequence'])) {
+            $content['$sequence'] = \is_numeric($content['$sequence'])
+                ? (int)$content['$sequence']
+                : 0;
+        }
+        return $content;
+    }
+
+    protected function parseRow(array $content): array
+    {
+        if (isset($content['$sequence'])) {
+            $content['$sequence'] = \is_numeric($content['$sequence'])
+                ? (int)$content['$sequence']
+                : 0;
+        }
+        return $content;
+    }
 }
diff --git a/src/Appwrite/Utopia/Response/Model/Document.php b/src/Appwrite/Utopia/Response/Model/Document.php
index e0aca32b3b..3be003418d 100644
--- a/src/Appwrite/Utopia/Response/Model/Document.php
+++ b/src/Appwrite/Utopia/Response/Model/Document.php
@@ -83,8 +83,8 @@ class Document extends Any
         $document->removeAttribute('$collection');
         $document->removeAttribute('$tenant');
 
-        if (!$document->isEmpty() && \is_numeric($document->getAttribute('$sequence', 0))) {
-            $document->setAttribute('$sequence', (int)$document->getAttribute('$sequence', 0));
+        if (!$document->isEmpty()) {
+            $document->setAttribute('$sequence', (string)$document->getAttribute('$sequence', ''));
         }
 
         foreach ($document->getAttributes() as $attribute) {
diff --git a/src/Appwrite/Utopia/Response/Model/Row.php b/src/Appwrite/Utopia/Response/Model/Row.php
index a96df44bc3..4c7426c4bc 100644
--- a/src/Appwrite/Utopia/Response/Model/Row.php
+++ b/src/Appwrite/Utopia/Response/Model/Row.php
@@ -83,8 +83,8 @@ class Row extends Any
         $document->removeAttribute('$collection');
         $document->removeAttribute('$tenant');
 
-        if (!$document->isEmpty() && \is_numeric($document->getAttribute('$sequence', 0))) {
-            $document->setAttribute('$sequence', (int)$document->getAttribute('$sequence', 0));
+        if (!$document->isEmpty()) {
+            $document->setAttribute('$sequence', (string)$document->getAttribute('$sequence', ''));
         }
 
         foreach ($document->getAttributes() as $column) {