Add sdk and sdkVersion columns to audit logs

Author: lohanidamodar

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to `utopia-php/audit` are documented in this file.
 
+## 2.7.0
+
+### ClickHouse adapter — SDK columns
+
+The ClickHouse adapter now stores two additional optional columns capturing the
+SDK that produced an audit event:
+
+#### Added
+
+- `Log::getSdk()` and `Log::getSdkVersion()` getters for ClickHouse-backed log reads.
+
+#### ClickHouse schema changes
+
+- Column `sdk` `LowCardinality(Nullable(String))` — SDK name (e.g. `web`, `flutter`,
+  `console`, `cli`); low-cardinality, optional.
+- Column `sdkVersion` `Nullable(String)` — SDK version (e.g. `14.0.0`); high-cardinality,
+  optional.
+- Index `_key_sdk` — bloom-filter index on the `sdk` column.
+
+Both columns are optional (`required = false`) so `createBatch()` never throws when a
+caller omits them. Existing ClickHouse audit tables gain the columns via `setup()` or an
+`ALTER TABLE ... ADD COLUMN IF NOT EXISTS` migration.
+
 ## 2.4.0
 
 ### ClickHouse adapter — actor terminology

src/Audit/Adapter/ClickHouse.php

@@ -31,6 +31,7 @@ class ClickHouse extends SQL
         'actorType',
         'resourceType',
         'country',
+        'sdk',
     ];
 
     /**
@@ -536,6 +537,26 @@ public function getAttributes(): array
                 'array' => false,
                 'filters' => [],
             ],
+            [
+                '$id' => 'sdk',
+                'type' => Database::VAR_STRING,
+                'size' => 256,
+                'required' => false,
+                'default' => null,
+                'signed' => true,
+                'array' => false,
+                'filters' => [],
+            ],
+            [
+                '$id' => 'sdkVersion',
+                'type' => Database::VAR_STRING,
+                'size' => 255,
+                'required' => false,
+                'default' => null,
+                'signed' => true,
+                'array' => false,
+                'filters' => [],
+            ],
         ];
     }
 
@@ -609,6 +630,13 @@ public function getIndexes(): array
                 'lengths' => [],
                 'orders' => [],
             ],
+            [
+                '$id' => '_key_sdk',
+                'type' => Database::INDEX_KEY,
+                'attributes' => ['sdk'],
+                'lengths' => [],
+                'orders' => [],
+            ],
         ];
     }
 

src/Audit/Log.php

@@ -101,6 +101,28 @@ public function getResource(): string
         return is_string($resource) ? $resource : '';
     }
 
+    /**
+     * Get the SDK name associated with this log entry.
+     *
+     * @return string
+     */
+    public function getSdk(): string
+    {
+        $sdk = $this->getAttribute('sdk', '');
+        return is_string($sdk) ? $sdk : '';
+    }
+
+    /**
+     * Get the SDK version associated with this log entry.
+     *
+     * @return string
+     */
+    public function getSdkVersion(): string
+    {
+        $sdkVersion = $this->getAttribute('sdkVersion', '');
+        return is_string($sdkVersion) ? $sdkVersion : '';
+    }
+
     /**
      * Get the user agent string.
      *

tests/Audit/Adapter/ClickHouseTest.php

@@ -535,7 +535,9 @@ public function testClickHouseAdapterAttributes(): void
             'projectInternalId',
             'teamId',
             'teamInternalId',
-            'hostname'
+            'hostname',
+            'sdk',
+            'sdkVersion'
         ];
 
         foreach ($expectedAttributes as $expected) {
@@ -565,7 +567,8 @@ public function testClickHouseAdapterIndexes(): void
             '_key_actor_internal_id',
             '_key_actor_type',
             '_key_country',
-            '_key_hostname'
+            '_key_hostname',
+            '_key_sdk'
         ];
 
         foreach ($expectedClickHouseIndexes as $expected) {