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

[grdsdev]

Summary

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

Changes

• SupabaseStorageClient: Added setHeader(String key, String value) method that sets a header and returns this for method chaining
• StorageFileApi: Added setHeader(String key, String value) method with shallow copy of headers to isolate changes between instances
• Tests: Added 8 unit tests covering happy path and edge cases

Reference Implementation

This matches the supabase-js implementation from:

• Commit: b1beee6
• PR: #2079

Key Behaviors

• Creates shallow copy of headers to avoid mutating shared state
• Returns this for method chaining
• StorageFileApi instances maintain isolated headers (setting on one doesn't affect others)

Testing

Unit Tests Added

• Sets custom header on storage client
• Returns this for method chaining
• Supports chaining multiple setHeader calls
• Headers set on client are included in file operations
• setHeader on StorageFileApi sets header for that instance
• setHeader on StorageFileApi does not affect other instances
• setHeader on StorageFileApi returns this for chaining
• setHeader can override existing headers

Test Commands

cd packages/storage_client
dart test test/basic_test.dart  # All 29 tests pass
dart test test/client_test.dart --name 'setHeader'  # All 8 tests pass

Acceptance Criteria

• setHeader(name, value) method implemented on storage base client
• Headers are copied (not mutated) when setting
• Method chaining supported
• Unit tests cover happy path and edge cases
• Documentation/docstrings updated

Linear Issue

Closes: SDK-691

---

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added setHeader() method for configuring custom HTTP headers with method chaining support.
  • Headers can be set at the client and instance levels with proper isolation between instances.
  • Existing headers can be overridden as needed.

• Tests

  • Comprehensive test coverage for header management functionality, including chaining, isolation, and header override scenarios.

Walkthrough

This PR implements the setHeader() method on storage client classes (SupabaseStorageClient and StorageFileApi) to enable per-request HTTP header configuration with method chaining support. The implementation creates shallow copies of headers to avoid mutating shared state. The StorageFileApi constructor was changed from const to non-const to support the private _headers field, with a public getter providing access. Comprehensive unit tests validate header functionality including chaining, isolation across instances, and integration with storage operations.

Assessment against linked issues

Objective	Addressed	Explanation
setHeader(name, value) method implemented on storage base client [SDK-691]	✅
Headers are copied (not mutated) when setting [SDK-691]	✅
Method chaining supported [SDK-691]	✅
Unit tests cover happy path and edge cases [SDK-691]	✅
Documentation/docstrings updated [SDK-691]	✅

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}