fix(auth): replace trait with runtime configuration flag

Sources/Auth/AuthClient.swift

@@ -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/AuthClientConfiguration.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/Supabase/SupabaseClient.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/Types.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
       )
     }