feat(gotrue): surface the sign-out reason on the signedOut event

[spydon]

What

Adds AuthState.signOutReason, a typed SignOutReason populated on the signedOut event so listeners can tell why the user was signed out:

• userInitiated for an explicit signOut().
• sessionExpired when the refresh token was rejected (invalid or expired) and the session was removed.
• sessionMissing when a stored session could not be recovered because it was missing required data.

It is null for every event other than signedOut, and also null for signedOut events received from another tab via web.BroadcastChannel.

Why

Follow-up to #1450, which stops recoverSession from double-reporting an expected sign-out as an uncaught stream error. The remaining concern was that a pure onAuthStateChange listener then sees signedOut without knowing why the user was signed out, removing the ability to handle it differently or notify the user.

This restores that capability through the event itself, rather than through an error that only reaches listeners with an onError handler:

supabase.auth.onAuthStateChange.listen((state) {
  if (state.event == AuthChangeEvent.signedOut &&
      state.signOutReason != null &&
      state.signOutReason != SignOutReason.userInitiated) {
    // involuntary sign out (e.g. expired session) -> show a message
  }
});

How

• New SignOutReason enum (userInitiated, sessionExpired, sessionMissing), exported from gotrue.dart.
• AuthState gains a nullable signOutReason field, threaded through notifyAllSubscribers.
• signOut() now delegates to a private _signOut({scope, reason}) so the public API is unchanged while internal callers can pass a reason.
• recoverSession and setInitialSession sign out with the appropriate reason and now throw AuthExceptions tagged with ErrorCode.sessionMissing / ErrorCode.sessionExpired (new error codes).
• The non-retryable refresh failure path signs the user out with sessionExpired.

The reason is intentionally not propagated across tabs via the broadcast channel, so it is always null when fromBroadcast is true.

Tests

• signedOut event carries SignOutReason.sessionExpired on an invalid refresh token.
• signedOut event reports SignOutReason.userInitiated on an explicit signOut.

[Vinzent03]

Adding an exception field to the class feels a bit strange, if we simultaneously use errors on the stream itself. But I cannot come up with a better solution right now. I thought about an enum at first as well like you did here: #1450 (comment), but that is probably hard to properly maintain and this solution is more general.
However, I think you've missed the sign out reasons in the recover method, right? They only have a human message and no special code to handle. Might be interesting to create a code that we use across similar issues in the recover method?

[spydon]

@Vinzent03 I went with an enum anyways, I think it should be enough and it's much cleaner. What do you think?

[Vinzent03]

I like it! Should be much easier to handle for the user and is not too specific to properly maintain for us.