fix(auth): replace trait with runtime configuration flag (#844)

* fix(auth): replace trait with runtime configuration flag

Replaces the EmitLocalSessionAsInitialSession trait with a runtime configuration flag to resolve compatibility issues with Xcode projects and align with Apple's trait guidelines.

## Changes

- Added `emitLocalSessionAsInitialSession: Bool` property to `AuthClient.Configuration`
  - Defaults to `false` for backward compatibility
  - Will change to `true` in next major release
- Replaced conditional compilation (`#if EmitLocalSessionAsInitialSession`) with runtime checks
- Updated deprecation warning to reference the new configuration option
- Added tests for both behaviors (old and new)
- Removed `EmitLocalSessionAsInitialSession` trait from [email protected]

## Benefits

- Works in all project types (Xcode, SPM, CocoaPods)
- No recompilation required to change behavior
- Better discoverability through autocomplete and docs
- Complies with Apple's trait guidelines (traits must be strictly additive)

## Migration

Users who want the new behavior can now set:
```swift
AuthClient(
  // ... other config
  emitLocalSessionAsInitialSession: true
)
```

Resolves compatibility issues where Xcode projects cannot enable package traits.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix(auth): add emitLocalSessionAsInitialSession to SupabaseClientOptions

Adds support for the emitLocalSessionAsInitialSession flag in SupabaseClientOptions.AuthOptions so users can configure this behavior when creating a SupabaseClient.

- Added emitLocalSessionAsInitialSession property to SupabaseClientOptions.AuthOptions
- Updated both initializers to include the new parameter
- Pass the flag through to AuthClient initialization in SupabaseClient

This ensures users can configure the flag whether they create an AuthClient directly or use SupabaseClient.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: Guilherme Souza

[email protected]

@@ -1393,7 +1393,7 @@ public actor AuthClient {
   }
 
   private func emitInitialSession(forToken token: ObservationToken) async {
-    #if EmitLocalSessionAsInitialSession
+    if configuration.emitLocalSessionAsInitialSession {
       guard let currentSession else {
         eventEmitter.emit(.initialSession, session: nil, token: token)
         return
@@ -1407,7 +1407,7 @@ public actor AuthClient {
           // No need to emit `tokenRefreshed` nor `signOut` event since the `refreshSession` does it already.
         }
       }
-    #else
+    } else {
       let session = try? await session
       eventEmitter.emit(.initialSession, session: session, token: token)
 
@@ -1417,16 +1417,16 @@ public actor AuthClient {
         reportIssue(
           """
           Initial session emitted after attempting to refresh the local stored session.
-          This is incorrect behavior and will be fixed in the next major release since it’s a breaking change.
-          For now, if you want to opt-in to the new behavior, add the trait `EmitLocalSessionAsInitialSession` to your Package.swift file when importing the Supabase dependency.
+          This is incorrect behavior and will be fixed in the next major release since it's a breaking change.
+          To opt-in to the new behavior now, set `emitLocalSessionAsInitialSession: true` in your AuthClient configuration.
           The new behavior ensures that the locally stored session is always emitted, regardless of its validity or expiration.
           If you rely on the initial session to opt users in, you need to add an additional check for `session.isExpired` in the session.
 
           Check https://github.com/supabase/supabase-swift/pull/822 for more information.
           """
         )
       }
-    #endif
+    }
   }
 
   nonisolated private func prepareForPKCE() -> (

Sources/Auth/AuthClient.swift

@@ -46,6 +46,16 @@ extension AuthClient {
     /// Set to `true` if you want to automatically refresh the token before expiring.
     public let autoRefreshToken: Bool
 
+    /// When `true`, emits the locally stored session immediately as the initial session,
+    /// regardless of its validity or expiration. When `false`, emits the initial session
+    /// after attempting to refresh the local stored session (legacy behavior).
+    ///
+    /// Default is `false` for backward compatibility. This will change to `true` in the next major release.
+    ///
+    /// - Note: If you rely on the initial session to opt users in, you need to add an additional
+    ///   check for `session.isExpired` when this is set to `true`.
+    public let emitLocalSessionAsInitialSession: Bool
+
     /// Initializes a AuthClient Configuration with optional parameters.
     ///
     /// - Parameters:
@@ -60,6 +70,7 @@ extension AuthClient {
     ///   - decoder: The JSON decoder to use for decoding responses.
     ///   - fetch: The asynchronous fetch handler for network requests.
     ///   - autoRefreshToken: Set to `true` if you want to automatically refresh the token before expiring.
+    ///   - emitLocalSessionAsInitialSession: When `true`, emits the locally stored session immediately as the initial session.
     public init(
       url: URL? = nil,
       headers: [String: String] = [:],
@@ -71,7 +82,8 @@ extension AuthClient {
       encoder: JSONEncoder = AuthClient.Configuration.jsonEncoder,
       decoder: JSONDecoder = AuthClient.Configuration.jsonDecoder,
       fetch: @escaping FetchHandler = { try await URLSession.shared.data(for: $0) },
-      autoRefreshToken: Bool = AuthClient.Configuration.defaultAutoRefreshToken
+      autoRefreshToken: Bool = AuthClient.Configuration.defaultAutoRefreshToken,
+      emitLocalSessionAsInitialSession: Bool = false
     ) {
       let headers = headers.merging(Configuration.defaultHeaders) { l, _ in l }
 
@@ -86,6 +98,7 @@ extension AuthClient {
       self.decoder = decoder
       self.fetch = fetch
       self.autoRefreshToken = autoRefreshToken
+      self.emitLocalSessionAsInitialSession = emitLocalSessionAsInitialSession
     }
   }
 
@@ -103,6 +116,7 @@ extension AuthClient {
   ///   - decoder: The JSON decoder to use for decoding responses.
   ///   - fetch: The asynchronous fetch handler for network requests.
   ///   - autoRefreshToken: Set to `true` if you want to automatically refresh the token before expiring.
+  ///   - emitLocalSessionAsInitialSession: When `true`, emits the locally stored session immediately as the initial session.
   public init(
     url: URL? = nil,
     headers: [String: String] = [:],
@@ -114,7 +128,8 @@ extension AuthClient {
     encoder: JSONEncoder = AuthClient.Configuration.jsonEncoder,
     decoder: JSONDecoder = AuthClient.Configuration.jsonDecoder,
     fetch: @escaping FetchHandler = { try await URLSession.shared.data(for: $0) },
-    autoRefreshToken: Bool = AuthClient.Configuration.defaultAutoRefreshToken
+    autoRefreshToken: Bool = AuthClient.Configuration.defaultAutoRefreshToken,
+    emitLocalSessionAsInitialSession: Bool = false
   ) {
     self.init(
       configuration: Configuration(
@@ -128,7 +143,8 @@ extension AuthClient {
         encoder: encoder,
         decoder: decoder,
         fetch: fetch,
-        autoRefreshToken: autoRefreshToken
+        autoRefreshToken: autoRefreshToken,
+        emitLocalSessionAsInitialSession: emitLocalSessionAsInitialSession
       )
     )
   }

Sources/Auth/AuthClientConfiguration.swift

@@ -181,7 +181,8 @@ public final class SupabaseClient: Sendable {
         // DON'T use `fetchWithAuth` method within the AuthClient as it may cause a deadlock.
         try await options.global.session.data(for: $0)
       },
-      autoRefreshToken: options.auth.autoRefreshToken
+      autoRefreshToken: options.auth.autoRefreshToken,
+      emitLocalSessionAsInitialSession: options.auth.emitLocalSessionAsInitialSession
     )
 
     _realtime = UncheckedSendable(

Sources/Supabase/SupabaseClient.swift

@@ -57,6 +57,13 @@ public struct SupabaseClientOptions: Sendable {
     /// Set to `true` if you want to automatically refresh the token before expiring.
     public let autoRefreshToken: Bool
 
+    /// When `true`, emits the locally stored session immediately as the initial session,
+    /// regardless of its validity or expiration. When `false`, emits the initial session
+    /// after attempting to refresh the local stored session (legacy behavior).
+    ///
+    /// Default is `false` for backward compatibility. This will change to `true` in the next major release.
+    public let emitLocalSessionAsInitialSession: Bool
+
     /// Optional function for using a third-party authentication system with Supabase. The function should return an access token or ID token (JWT) by obtaining it from the third-party auth client library.
     /// Note that this function may be called concurrently and many times. Use memoization and locking techniques if this is not supported by the client libraries.
     /// When set, the `auth` namespace of the Supabase client cannot be used.
@@ -71,6 +78,7 @@ public struct SupabaseClientOptions: Sendable {
       encoder: JSONEncoder = AuthClient.Configuration.jsonEncoder,
       decoder: JSONDecoder = AuthClient.Configuration.jsonDecoder,
       autoRefreshToken: Bool = AuthClient.Configuration.defaultAutoRefreshToken,
+      emitLocalSessionAsInitialSession: Bool = false,
       accessToken: (@Sendable () async throws -> String?)? = nil
     ) {
       self.storage = storage
@@ -80,6 +88,7 @@ public struct SupabaseClientOptions: Sendable {
       self.encoder = encoder
       self.decoder = decoder
       self.autoRefreshToken = autoRefreshToken
+      self.emitLocalSessionAsInitialSession = emitLocalSessionAsInitialSession
       self.accessToken = accessToken
     }
   }
@@ -173,6 +182,7 @@ extension SupabaseClientOptions.AuthOptions {
       encoder: JSONEncoder = AuthClient.Configuration.jsonEncoder,
       decoder: JSONDecoder = AuthClient.Configuration.jsonDecoder,
       autoRefreshToken: Bool = AuthClient.Configuration.defaultAutoRefreshToken,
+      emitLocalSessionAsInitialSession: Bool = false,
       accessToken: (@Sendable () async throws -> String?)? = nil
     ) {
       self.init(
@@ -183,6 +193,7 @@ extension SupabaseClientOptions.AuthOptions {
         encoder: encoder,
         decoder: decoder,
         autoRefreshToken: autoRefreshToken,
+        emitLocalSessionAsInitialSession: emitLocalSessionAsInitialSession,
         accessToken: accessToken
       )
     }