feat(storage): add setHeader method for custom HTTP headers (#1313)

Add setHeader(key, value) method to both SupabaseStorageClient and
StorageFileApi to allow setting per-request HTTP headers on storage
operations, matching the supabase-js API.

Key behaviors:
- Creates shallow copy of headers to avoid mutating shared state
- Returns this for method chaining
- StorageFileApi instances maintain isolated headers

Linear: SDK-691

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: grdsdev

packages/storage_client/lib/src/storage_client.dart

@@ -100,4 +100,17 @@ class SupabaseStorageClient extends StorageBucketApi {
   void setAuth(String jwt) {
     headers['Authorization'] = 'Bearer $jwt';
   }
+
+  /// Sets an HTTP header for subsequent requests.
+  ///
+  /// Creates a shallow copy of headers to avoid mutating shared state.
+  /// Returns this for method chaining.
+  ///
+  /// ```dart
+  /// storage.setHeader('x-custom-header', 'value').from('bucket').upload(...);
+  /// ```
+  SupabaseStorageClient setHeader(String key, String value) {
+    headers[key] = value;
+    return this;
+  }
 }

packages/storage_client/lib/src/storage_file_api.dart

@@ -7,18 +7,34 @@ import 'file_io.dart' if (dart.library.js) './file_stub.dart';
 
 class StorageFileApi {
   final String url;
-  final Map<String, String> headers;
+  Map<String, String> _headers;
   final String? bucketId;
   final int _retryAttempts;
   final Fetch _storageFetch;
 
-  const StorageFileApi(
+  StorageFileApi(
     this.url,
-    this.headers,
+    Map<String, String> headers,
     this.bucketId,
     this._retryAttempts,
     this._storageFetch,
-  );
+  ) : _headers = {...headers};
+
+  /// The headers used for requests.
+  Map<String, String> get headers => _headers;
+
+  /// Sets an HTTP header for subsequent requests.
+  ///
+  /// Creates a shallow copy of headers to avoid mutating shared state.
+  /// Returns this for method chaining.
+  ///
+  /// ```dart
+  /// storage.from('bucket').setHeader('x-custom-header', 'value').upload(...);
+  /// ```
+  StorageFileApi setHeader(String key, String value) {
+    _headers = {..._headers, key: value};
+    return this;
+  }
 
   String _getFinalPath(String path) {
     return '$bucketId/$path';

packages/storage_client/test/client_test.dart

@@ -5,6 +5,8 @@ import "package:path/path.dart" show join;
 import 'package:storage_client/storage_client.dart';
 import 'package:test/test.dart';
 
+import 'custom_http_client.dart';
+
 const storageUrl = 'http://localhost:8000/storage/v1';
 const storageKey =
     'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzdXBhYmFzZSIsImlhdCI6MTYwMzk2ODgzNCwiZXhwIjoyNTUwNjUzNjM0LCJhdWQiOiIiLCJzdWIiOiIzMTdlYWRjZS02MzFhLTQ0MjktYTBiYi1mMTlhN2E1MTdiNGEiLCJSb2xlIjoicG9zdGdyZXMifQ.pZobPtp6gDcX0UbzMmG3FHSlg4m4Q-22tKtGWalOrNo';
@@ -479,4 +481,131 @@ void main() {
     final res2 = await storage.from(newBucketName).exists('not-exist');
     expect(res2, false);
   });
+
+  group('setHeader', () {
+    late CustomHttpClient customHttpClient;
+    late SupabaseStorageClient client;
+
+    setUp(() {
+      customHttpClient = CustomHttpClient();
+      client = SupabaseStorageClient(
+        storageUrl,
+        {'Authorization': 'Bearer $storageKey'},
+        httpClient: customHttpClient,
+      );
+    });
+
+    test('sets custom header on storage client', () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      client.setHeader('x-custom-header', 'custom-value');
+      await client.listBuckets();
+
+      expect(customHttpClient.receivedRequests.length, 1);
+      expect(
+        customHttpClient.receivedRequests.first.headers['x-custom-header'],
+        'custom-value',
+      );
+    });
+
+    test('returns this for method chaining', () {
+      final result = client.setHeader('x-header-a', 'value-a');
+      expect(identical(result, client), isTrue);
+    });
+
+    test('supports chaining multiple setHeader calls', () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      client
+          .setHeader('x-header-a', 'value-a')
+          .setHeader('x-header-b', 'value-b');
+      await client.listBuckets();
+
+      expect(customHttpClient.receivedRequests.length, 1);
+      final headers = customHttpClient.receivedRequests.first.headers;
+      expect(headers['x-header-a'], 'value-a');
+      expect(headers['x-header-b'], 'value-b');
+    });
+
+    test('headers set on client are included in file operations', () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      client.setHeader('x-custom-header', 'custom-value');
+      await client.from('test-bucket').list();
+
+      expect(customHttpClient.receivedRequests.length, 1);
+      expect(
+        customHttpClient.receivedRequests.first.headers['x-custom-header'],
+        'custom-value',
+      );
+    });
+
+    test('setHeader on StorageFileApi sets header for that instance', () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      final fileApi = client.from('test-bucket');
+      fileApi.setHeader('x-file-header', 'file-value');
+      await fileApi.list();
+
+      expect(customHttpClient.receivedRequests.length, 1);
+      expect(
+        customHttpClient.receivedRequests.first.headers['x-file-header'],
+        'file-value',
+      );
+    });
+
+    test(
+        'setHeader on StorageFileApi does not affect other StorageFileApi instances',
+        () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      final fileApi1 = client.from('bucket1');
+      final fileApi2 = client.from('bucket2');
+
+      fileApi1.setHeader('x-header', 'value1');
+
+      await fileApi1.list();
+      await fileApi2.list();
+
+      expect(customHttpClient.receivedRequests.length, 2);
+      expect(
+        customHttpClient.receivedRequests[0].headers['x-header'],
+        'value1',
+      );
+      // fileApi2 should not have the header set on fileApi1
+      expect(
+        customHttpClient.receivedRequests[1].headers['x-header'],
+        isNull,
+      );
+    });
+
+    test('setHeader on StorageFileApi returns this for chaining', () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      final fileApi = client.from('test-bucket');
+      final result = fileApi.setHeader('x-header', 'value');
+
+      expect(identical(result, fileApi), isTrue);
+    });
+
+    test('setHeader can override existing headers', () async {
+      customHttpClient.response = [];
+      customHttpClient.statusCode = 200;
+
+      client.setHeader('Authorization', 'Bearer new-token');
+      await client.listBuckets();
+
+      expect(customHttpClient.receivedRequests.length, 1);
+      expect(
+        customHttpClient.receivedRequests.first.headers['Authorization'],
+        'Bearer new-token',
+      );
+    });
+  });
 }