fix: correctness fixes across gotrue, postgrest, storage, supabase and supabase_flutter (#1445)

## Summary

A batch of correctness fixes found during a code review sweep. Each fix
is in its own per-package commit and ships with a regression test that
was verified to fail on the current `main` and pass with the fix.

### gotrue
- `verifyOTP` sent the captcha token under `captchaToken` inside
`gotrue_meta_security`, but the server reads `captcha_token`, so the
token was silently dropped. Now uses `captcha_token` like every other
call.
- `resend` checked `containsKey(['message_id'])` with a list argument
(always false), so `ResendResponse.messageId` was never populated. Now
uses the string key.

### postgrest
- `.maybeSingle().count()` with zero matching rows and no converter
returned `null as T` where `T` is the non-nullable `PostgrestResponse`,
throwing a `TypeError`. Now returns a response with null data and
`count: 0`.

### storage_client
- A single `MultipartFile` instance was reused across retry attempts, so
a retry re-finalized an already finalized file and threw a `StateError`
instead of retrying. The request factory now builds a fresh
`MultipartFile` per attempt.
- Binary signed url uploads derived the content type from the full url
including the `?token=` query string, defeating mime lookup and falling
back to `application/octet-stream`. Now uses the url path.
- `_removeEmptyFolders` used JavaScript regex literals (`/.../g`) that
never matched, making it a no-op. Now uses valid Dart patterns so signed
url paths are normalized.

### supabase
- The `headers` setter rebuilt the realtime client headers from the
client headers only, dropping the `apikey` entry present at
construction. Now includes the `apikey`. Also removes a redundant
self-spread when merging rest headers before an `rpc`.

### supabase_flutter
- When initialized with a custom `accessToken`,
`_restoreSessionCancellableOperation` was never assigned, so `dispose()`
threw a `LateInitializationError`. The field is now nullable and
cancelled with a null-aware call.

## Test plan
- New and updated tests in each package, all mock based and runnable
without a backend.
- Each test was confirmed to fail on the unpatched `main` and pass with
the fix.
- `dart analyze` and `dart format` are clean across all changed files.

Author: spydon

packages/gotrue/lib/src/gotrue_client.dart

@@ -595,7 +595,7 @@ class GoTrueClient {
       if (token != null) 'token': token,
       'type': type.snakeCase,
       'redirect_to': redirectTo,
-      'gotrue_meta_security': {'captchaToken': captchaToken},
+      'gotrue_meta_security': {'captcha_token': captchaToken},
       if (tokenHash != null) 'token_hash': tokenHash,
     };
     final fetchOptions = GotrueRequestOptions(headers: _headers, body: body);
@@ -765,7 +765,7 @@ class GoTrueClient {
       options: options,
     );
 
-    if ((response as Map).containsKey(['message_id'])) {
+    if ((response as Map).containsKey('message_id')) {
       return ResendResponse(messageId: response['message_id']);
     }
     return ResendResponse();

packages/gotrue/test/otp_mock_test.dart

@@ -244,6 +244,15 @@ void main() {
       expect(response, isA<ResendResponse>());
     });
 
+    test('resend() parses the message id from the response', () async {
+      final response = await client.resend(
+        phone: testPhone,
+        type: OtpType.sms,
+      );
+
+      expect(response.messageId, 'mock-message-id-resend');
+    });
+
     test('resend() with email type', () async {
       final response = await client.resend(
         email: testEmail,
@@ -610,5 +619,19 @@ void main() {
       );
       expect(mockClient.lastRequestBody?['type'], 'email_change');
     });
+
+    test('verifyOTP() sends the captcha token under the captcha_token key',
+        () async {
+      await client.verifyOTP(
+        phone: testPhone,
+        token: '123456',
+        type: OtpType.sms,
+        captchaToken: 'captcha-token-123',
+      );
+
+      final security = mockClient.lastRequestBody?['gotrue_meta_security']
+          as Map<String, dynamic>?;
+      expect(security?['captcha_token'], 'captcha-token-123');
+    });
   });
 }

packages/postgrest/lib/src/postgrest_builder.dart

@@ -366,7 +366,7 @@ class PostgrestBuilder<T, S, R> implements Future<T> {
           return PostgrestResponse<S>(data: _converter(null as R), count: 0)
               as T;
         }
-        return null as T;
+        return PostgrestResponse<S>(data: null as S, count: 0) as T;
       }
       if (_converter != null) {
         return _converter(null as R) as T;

packages/postgrest/test/maybe_single_test.dart

@@ -0,0 +1,43 @@
+import 'dart:convert';
+
+import 'package:http/http.dart';
+import 'package:postgrest/postgrest.dart';
+import 'package:test/test.dart';
+
+/// Mimics PostgREST returning the "0 rows" error that `maybeSingle()` treats as
+/// an empty result rather than a failure.
+class ZeroRowsHttpClient extends BaseClient {
+  @override
+  Future<StreamedResponse> send(BaseRequest request) async {
+    return StreamedResponse(
+      Stream.value(utf8.encode(jsonEncode({
+        'code': 'PGRST116',
+        'details': 'Results contain 0 rows',
+        'hint': null,
+        'message': 'JSON object requested, multiple (or no) rows returned',
+      }))),
+      406,
+      request: request,
+    );
+  }
+}
+
+void main() {
+  test('maybeSingle().count() returns null data and count 0 when no rows match',
+      () async {
+    final postgrest = PostgrestClient(
+      'https://example.com',
+      httpClient: ZeroRowsHttpClient(),
+    );
+
+    final response = await postgrest
+        .from('users')
+        .update({'name': 'x'})
+        .select()
+        .maybeSingle()
+        .count();
+
+    expect(response.data, isNull);
+    expect(response.count, 0);
+  });
+}

packages/storage_client/lib/src/fetch.dart

@@ -107,16 +107,16 @@ class Fetch {
     final contentType = fileOptions.contentType != null
         ? MediaType.parse(fileOptions.contentType!)
         : _parseMediaType(file.path);
-    final multipartFile = http.MultipartFile.fromBytes(
-      '',
-      file.readAsBytesSync(),
-      filename: file.path,
-      contentType: contentType,
-    );
+    final bytes = file.readAsBytesSync();
     return _handleMultipartRequest(
       method,
       url,
-      multipartFile,
+      () => http.MultipartFile.fromBytes(
+        '',
+        bytes,
+        filename: file.path,
+        contentType: contentType,
+      ),
       fileOptions,
       options,
       retryAttempts,
@@ -135,18 +135,17 @@ class Fetch {
   ) {
     final contentType = fileOptions.contentType != null
         ? MediaType.parse(fileOptions.contentType!)
-        : _parseMediaType(url);
-    final multipartFile = http.MultipartFile.fromBytes(
-      '',
-      data,
-      // request fails with null filename so set it empty instead.
-      filename: '',
-      contentType: contentType,
-    );
+        : _parseMediaType(Uri.parse(url).path);
     return _handleMultipartRequest(
       method,
       url,
-      multipartFile,
+      () => http.MultipartFile.fromBytes(
+        '',
+        data,
+        // request fails with null filename so set it empty instead.
+        filename: '',
+        contentType: contentType,
+      ),
       fileOptions,
       options,
       retryAttempts,
@@ -157,7 +156,7 @@ class Fetch {
   Future<dynamic> _handleMultipartRequest(
     String method,
     String url,
-    MultipartFile multipartFile,
+    MultipartFile Function() createMultipartFile,
     FileOptions fileOptions,
     FetchOptions? options,
     int retryAttempts,
@@ -169,7 +168,7 @@ class Fetch {
     http.MultipartRequest createRequest() {
       final request = http.MultipartRequest(method, Uri.parse(url))
         ..headers.addAll(headers)
-        ..files.add(multipartFile)
+        ..files.add(createMultipartFile())
         ..fields['cacheControl'] = fileOptions.cacheControl
         ..headers['x-upsert'] = fileOptions.upsert.toString();
       if (fileOptions.metadata != null) {

packages/storage_client/lib/src/storage_file_api.dart

@@ -41,9 +41,7 @@ class StorageFileApi {
   }
 
   String _removeEmptyFolders(String path) {
-    return path
-        .replaceAll(RegExp(r'/^\/|\/$/g'), '')
-        .replaceAll(RegExp(r'/\/+/g'), '/');
+    return path.replaceAll(RegExp(r'^/|/$'), '').replaceAll(RegExp(r'/+'), '/');
   }
 
   /// Uploads a file to an existing bucket.

packages/storage_client/test/fetch_test.dart

@@ -0,0 +1,104 @@
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:http/http.dart';
+import 'package:storage_client/storage_client.dart';
+import 'package:test/test.dart';
+
+import 'custom_http_client.dart';
+
+const storageUrl = 'http://localhost/storage/v1';
+const headers = {'Authorization': 'Bearer token'};
+
+/// Client that finalizes (reads) the request body before failing, mimicking a
+/// real HTTP client. This exercises [MultipartFile] finalization on every retry
+/// attempt, which previously crashed because the same file instance was reused.
+class FinalizingRetryHttpClient extends BaseClient {
+  FinalizingRetryHttpClient({this.failuresBeforeSuccess = 1});
+
+  final int failuresBeforeSuccess;
+  int attempts = 0;
+
+  @override
+  Future<StreamedResponse> send(BaseRequest request) async {
+    attempts++;
+    await request.finalize().drain<void>();
+    if (attempts <= failuresBeforeSuccess) {
+      throw ClientException('Offline');
+    }
+    return StreamedResponse(
+      Stream.value(utf8.encode(jsonEncode({'Key': 'public/a.txt'}))),
+      201,
+      request: request,
+    );
+  }
+}
+
+void main() {
+  group('multipart uploads', () {
+    test('retries a binary upload after a failure that finalized the request',
+        () async {
+      final retryClient = FinalizingRetryHttpClient(failuresBeforeSuccess: 1);
+      final client = SupabaseStorageClient(
+        storageUrl,
+        headers,
+        httpClient: retryClient,
+        retryAttempts: 3,
+      );
+
+      final result = await client
+          .from('bucket')
+          .uploadBinary('folder/file.png', Uint8List.fromList([1, 2, 3]));
+
+      expect(result, 'public/a.txt');
+      expect(retryClient.attempts, 2);
+    });
+
+    test('detects content type from the path of a binary signed url upload',
+        () async {
+      final mockClient = CustomHttpClient();
+      mockClient.response = <String, dynamic>{};
+      mockClient.statusCode = 200;
+      final client = SupabaseStorageClient(
+        storageUrl,
+        headers,
+        httpClient: mockClient,
+      );
+
+      await client.from('bucket').uploadBinaryToSignedUrl(
+            'folder/image.png',
+            'signed-token',
+            Uint8List.fromList([1, 2, 3]),
+          );
+
+      final request = mockClient.receivedRequests.single as MultipartRequest;
+      expect(request.files.single.contentType.mimeType, 'image/png');
+    });
+  });
+
+  group('path normalization', () {
+    test('removes leading, trailing and duplicate slashes from the path',
+        () async {
+      final mockClient = CustomHttpClient();
+      mockClient.response = <String, dynamic>{};
+      mockClient.statusCode = 200;
+      final client = SupabaseStorageClient(
+        storageUrl,
+        headers,
+        httpClient: mockClient,
+      );
+
+      final cleanPath = await client.from('bucket').uploadBinaryToSignedUrl(
+            '/folder//image.png/',
+            'signed-token',
+            Uint8List.fromList([1]),
+          );
+
+      expect(cleanPath, 'folder/image.png');
+
+      final requestPath = mockClient.receivedRequests.single.url.path;
+      expect(requestPath, endsWith('/bucket/folder/image.png'));
+      expect(requestPath.contains('//'), isFalse);
+    });
+  });
+}

packages/supabase/lib/src/supabase_client.dart

@@ -113,7 +113,10 @@ class SupabaseClient {
     // manually unsubscribe and resubscribe to all channels.
     realtime.headers
       ..clear()
-      ..addAll(_headers);
+      ..addAll({
+        'apikey': _supabaseKey,
+        ..._headers,
+      });
   }
 
   /// {@macro supabase_client}
@@ -213,7 +216,7 @@ class SupabaseClient {
     Map<String, dynamic>? params,
     get = false,
   }) {
-    rest.headers.addAll({...rest.headers, ...headers});
+    rest.headers.addAll(headers);
     return rest.rpc(fn, params: params, get: get);
   }
 

packages/supabase/lib/src/supabase_query_schema.dart

@@ -54,7 +54,7 @@ class SupabaseQuerySchema {
     Map<String, dynamic>? params,
     bool get = false,
   }) {
-    _rest.headers.addAll({..._rest.headers, ..._headers});
+    _rest.headers.addAll(_headers);
     return _rest.rpc(
       fn,
       params: params,

packages/supabase/test/client_test.dart

@@ -305,6 +305,13 @@ void main() {
         expect(supabase.headers['X-Client-Info'], startsWith('supabase-dart/'));
       });
 
+      test('should preserve apikey on realtime headers when setting headers',
+          () {
+        supabase.headers = {'Custom-Header': 'custom-value'};
+
+        expect(supabase.realtime.headers['apikey'], supabaseKey);
+      });
+
       test('should not update auth headers when using custom access token', () {
         final customTokenClient = SupabaseClient(
           supabaseUrl,