fix: align time series return types with actual float aggregation output

PHPStan level max flagged getTimeSeries() annotations as int while the
ClickHouse adapter emits floats via agg_value cast. Updates the abstract,
both adapters, the Usage facade, and zeroFillTimeSeries to float.

Also throws on json_encode failure in Usage::collect so the md5() input is
guaranteed string instead of string|false.

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

Author: lohanidamodar

src/Usage/Adapter.php

@@ -47,7 +47,7 @@ abstract public function addBatch(array $metrics, string $type, int $batchSize =
      * @param  array<\Utopia\Query\Query>  $queries  Additional query filters
      * @param  bool  $zeroFill  Whether to fill gaps with zero values
      * @param  string|null  $type  Metric type: 'event', 'gauge', or null (query both)
-     * @return array<string, array{total: int, data: array<array{value: int, date: string}>}>
+     * @return array<string, array{total: float, data: array<array{value: float, date: string}>}>
      */
     abstract public function getTimeSeries(array $metrics, string $interval, string $startDate, string $endDate, array $queries = [], bool $zeroFill = true, ?string $type = null): array;
 

src/Usage/Adapter/ClickHouse.php

@@ -1896,7 +1896,7 @@ public function sumDailyBatch(array $metrics, array $queries = []): array
      * @param  array<Query>  $queries
      * @param  bool  $zeroFill
      * @param  string|null  $type  'event', 'gauge', or null (both)
-     * @return array<string, array{total: int, data: array<array{value: int, date: string}>}>
+     * @return array<string, array{total: float, data: array<array{value: float, date: string}>}>
      * @throws Exception
      */
     public function getTimeSeries(array $metrics, string $interval, string $startDate, string $endDate, array $queries = [], bool $zeroFill = true, ?string $type = null): array
@@ -1967,7 +1967,7 @@ public function getTimeSeries(array $metrics, string $interval, string $startDat
      * @param  string  $endDate
      * @param  array<Query>  $queries
      * @param  string  $type
-     * @return array<string, array{total: int, data: array<array{value: int, date: string}>}>
+     * @return array<string, array{total: float, data: array<array{value: float, date: string}>}>
      * @throws Exception
      */
     private function getTimeSeriesFromTable(array $metrics, string $interval, string $startDate, string $endDate, array $queries, string $type): array
@@ -2040,7 +2040,7 @@ private function getTimeSeriesFromTable(array $metrics, string $interval, string
         if (is_array($json) && isset($json['data']) && is_array($json['data'])) {
             foreach ($json['data'] as $row) {
                 $metricName = $row['metric'] ?? '';
-                $bucketTime = $row['bucket'] ?? '';
+                $bucketTime = (string) ($row['bucket'] ?? '');
                 $value = (float) ($row['agg_value'] ?? 0);
 
                 if (!isset($output[$metricName])) {
@@ -2049,7 +2049,7 @@ private function getTimeSeriesFromTable(array $metrics, string $interval, string
 
                 // Format bucket time
                 $formattedDate = $bucketTime;
-                if (is_string($bucketTime) && strpos($bucketTime, 'T') === false) {
+                if (strpos($bucketTime, 'T') === false) {
                     $formattedDate = str_replace(' ', 'T', $bucketTime) . '+00:00';
                 }
 
@@ -2067,11 +2067,11 @@ private function getTimeSeriesFromTable(array $metrics, string $interval, string
     /**
      * Fill gaps in time series data with zero-value entries.
      *
-     * @param array<array{value: int, date: string}> $data Existing data points
+     * @param array<array{value: float, date: string}> $data Existing data points
      * @param string $interval '1h' or '1d'
      * @param string $startDate Start datetime
      * @param string $endDate End datetime
-     * @return array<array{value: int, date: string}>
+     * @return array<array{value: float, date: string}>
      */
     private function zeroFillTimeSeries(array $data, string $interval, string $startDate, string $endDate): array
     {

src/Usage/Adapter/Database.php

@@ -161,7 +161,7 @@ public function addBatch(array $metrics, string $type = Usage::TYPE_EVENT, int $
      * @param array<Query> $queries
      * @param bool $zeroFill
      * @param string|null $type
-     * @return array<string, array{total: int, data: array<array{value: int, date: string}>}>
+     * @return array<string, array{total: float, data: array<array{value: float, date: string}>}>
      */
     public function getTimeSeries(array $metrics, string $interval, string $startDate, string $endDate, array $queries = [], bool $zeroFill = true, ?string $type = null): array
     {

src/Usage/Usage.php

@@ -105,7 +105,7 @@ public function addBatch(array $metrics, string $type = self::TYPE_EVENT, int $b
      * @param array<\Utopia\Query\Query> $queries Additional filters
      * @param bool $zeroFill Whether to fill gaps with zero values
      * @param string|null $type Metric type: 'event', 'gauge', or null (query both)
-     * @return array<string, array{total: int, data: array<array{value: int, date: string}>}>
+     * @return array<string, array{total: float, data: array<array{value: float, date: string}>}>
      * @throws \Exception
      */
     public function getTimeSeries(array $metrics, string $interval, string $startDate, string $endDate, array $queries = [], bool $zeroFill = true, ?string $type = null): array
@@ -299,7 +299,7 @@ public function collect(string $metric, int $value, string $type, array $tags =
             throw new \InvalidArgumentException("Invalid metric type '{$type}'. Allowed: " . self::TYPE_EVENT . ', ' . self::TYPE_GAUGE);
         }
 
-        $tagsHash = !empty($tags) ? md5(json_encode($tags)) : '';
+        $tagsHash = !empty($tags) ? md5(json_encode($tags, JSON_THROW_ON_ERROR)) : '';
         $key = $metric . ':' . $type . ':' . $tagsHash;
 
         if ($type === 'event') {