feat: Add customHeaders closure for injecting request headers

Introduces a public customHeaders closure property on Flagsmith that
allows consumers to inject arbitrary HTTP headers into every SDK request.
The closure is invoked fresh on every request, so dynamic values (OAuth
Bearer tokens, request correlation IDs, custom telemetry, etc.) are
always up to date.

Use cases this unblocks:
- Authenticating through a gateway/proxy that requires custom auth
  headers (e.g. OAuth Bearer) that aren't the X-Environment-Key
- Adding tracing/correlation IDs to requests for observability
- Injecting A/B testing or user-agent headers for downstream systems

Backward compatible — when customHeaders is nil (the default),
behavior is unchanged.

Changes:
- Flagsmith.swift: add public customHeaders closure property
- APIManager.swift: invoke closure and apply headers to every request
- SSEManager.swift: same for SSE connection requests
- CustomHeadersTests.swift: add tests covering invocation, nil, and
  per-request freshness

Author: chocke

FlagsmithClient/Classes/Flagsmith.swift

@@ -58,6 +58,20 @@ public final class Flagsmith: @unchecked Sendable {
         }
     }
 
+    /// Custom HTTP headers to inject into every Flagsmith request.
+    ///
+    /// The closure is invoked **fresh** on every request, so dynamic values
+    /// (like OAuth Bearer tokens that get refreshed) are always up to date.
+    ///
+    /// Example — inject an Authorization header:
+    /// ```swift
+    /// Flagsmith.shared.customHeaders = { [weak tokenStore] in
+    ///     guard let token = tokenStore?.tokens?.accessToken else { return [:] }
+    ///     return ["Authorization": "Bearer \(token)"]
+    /// }
+    /// ```
+    public var customHeaders: (@Sendable () -> [String: String])?
+
     /// Is flag analytics enabled?
     public var enableAnalytics: Bool {
         get { analytics.enableAnalytics }

FlagsmithClient/Classes/Internal/APIManager.swift

@@ -142,6 +142,13 @@ final class APIManager: NSObject, URLSessionDataDelegate, @unchecked Sendable {
             return
         }
 
+        // Inject custom headers (called fresh per request to support dynamic values like OAuth tokens)
+        if let headers = Flagsmith.shared.customHeaders?() {
+            for (key, value) in headers {
+                request.setValue(value, forHTTPHeaderField: key)
+            }
+        }
+
         // set the cache policy based on Flagsmith settings
         request.cachePolicy = .reloadIgnoringLocalAndRemoteCacheData
         if Flagsmith.shared.cacheConfig.useCache {

FlagsmithClient/Classes/Internal/SSEManager.swift

@@ -158,6 +158,13 @@ final class SSEManager: NSObject, URLSessionDataDelegate, @unchecked Sendable {
         request.setValue("no-cache", forHTTPHeaderField: "Cache-Control")
         request.setValue("keep-alive", forHTTPHeaderField: "Connection")
 
+        // Inject custom headers (called fresh per request to support dynamic values like OAuth tokens)
+        if let headers = Flagsmith.shared.customHeaders?() {
+            for (key, value) in headers {
+                request.setValue(value, forHTTPHeaderField: key)
+            }
+        }
+
         completionHandler = completion
         dataTask = session.dataTask(with: request)
         dataTask?.resume()

FlagsmithClient/Tests/CustomHeadersTests.swift

@@ -0,0 +1,66 @@
+//
+//  CustomHeadersTests.swift
+//  FlagsmithClientTests
+//
+
+@testable import FlagsmithClient
+import XCTest
+
+final class CustomHeadersTests: FlagsmithClientTestCase {
+    override func tearDown() {
+        super.tearDown()
+        Flagsmith.shared.customHeaders = nil
+    }
+
+    /// Verify the `customHeaders` closure is invoked when a request is made.
+    func testCustomHeadersClosureIsInvoked() throws {
+        let closureInvoked = expectation(description: "customHeaders closure invoked")
+
+        Flagsmith.shared.customHeaders = {
+            closureInvoked.fulfill()
+            return ["X-Test-Header": "value"]
+        }
+        Flagsmith.shared.apiKey = "mock-test-api-key"
+        // Force a quick failure so the request doesn't hang
+        Flagsmith.shared.baseURL = URL(fileURLWithPath: "/dev/null")
+
+        Flagsmith.shared.getFeatureFlags { _ in }
+
+        wait(for: [closureInvoked], timeout: 1.0)
+    }
+
+    /// Verify that when `customHeaders` is nil, requests still work normally.
+    func testNilCustomHeadersDoesNotCrash() throws {
+        Flagsmith.shared.customHeaders = nil
+        Flagsmith.shared.apiKey = "mock-test-api-key"
+        Flagsmith.shared.baseURL = URL(fileURLWithPath: "/dev/null")
+
+        let requestFinished = expectation(description: "Request finished without crash")
+
+        Flagsmith.shared.getFeatureFlags { _ in
+            requestFinished.fulfill()
+        }
+
+        wait(for: [requestFinished], timeout: 1.0)
+    }
+
+    /// Verify the closure is invoked on every request (not cached).
+    func testCustomHeadersClosureInvokedEveryRequest() throws {
+        var invocationCount = 0
+        Flagsmith.shared.customHeaders = {
+            invocationCount += 1
+            return [:]
+        }
+        Flagsmith.shared.apiKey = "mock-test-api-key"
+        Flagsmith.shared.baseURL = URL(fileURLWithPath: "/dev/null")
+
+        let firstRequest = expectation(description: "First request")
+        let secondRequest = expectation(description: "Second request")
+
+        Flagsmith.shared.getFeatureFlags { _ in firstRequest.fulfill() }
+        Flagsmith.shared.getFeatureFlags { _ in secondRequest.fulfill() }
+
+        wait(for: [firstRequest, secondRequest], timeout: 2.0)
+        XCTAssertEqual(invocationCount, 2, "customHeaders should be invoked for every request")
+    }
+}