refactor: combine the storage interface for storage and pkce in gotrue_client

[Vinzent03]

What kind of change does this PR introduce?

refactor with breaking changes and fixes

What is the current behavior?

The session gets stored by the supabase_flutter package by listening to auth events. The session is stored by a different class/interface than the pkce token. This adds unnecessary complexity and is a difference to the supabase-js sdk.

What is the new behavior?

The gotrue package manages the session storage itself (like in supabase-js) and uses the same interface as the pkce token.

Reasons for this pr:

• Have a more similar approach to saving the session like in supabase-js
• Make it less confusing for the user to have to provide two different storage interfaces to customize the storage of the session and the pkce token
• Provide a built-in interface to persist the session if not using supabase_flutter, e.g. when building a cli with sessions or I suppose a jaspr website.
• The auth client has now the persistSession field, which is now used to explicitly turn on the session broadcasting. fixes Version 2.7.0 prevents reading data on web under certain conditions #1085

I deprecated both localStorage (used for session storage by supabase_flutter) and pkceAsyncStorage (used by supabase to store the pkce token) and replace them with a unified storage interface asyncStorage, which uses the GotrueAsyncStorage class, which was previously used for pkce only. Though I refactored the arguments of the methods to use positional arguments instead of named arguments. This is much more idiomatic to other storage packages and common for methods with just one or two arguments. To support existing configuration as best as possible I created a new class, which combines both deprecated config options (localStorage and pkceAsyncStorage) into one and decides by the suffix of the storage key to use the session storage or pkce storage. Note that an implementation of the GotrueAsyncStorage class still needs to be refactored, but that only affects the method signature and not the implementation itself.

Additionally, I noticed that many document comments were outdated, because of the 'new' options classes for each package, so I updated them.

Breaking Changes

• Only the change of the method signatures of the GotrueAsyncStorage class

-Future<void> setItem({required String key, required String value});
+Future<void> setItem(String key, String value);

Additional context

I think this is a great refactoring that does not affect many people, because I don't think many flutter user customize the storage. But it makes it easier and more streamlined for the ones that do so and opens new easier usage ways outside of flutter with auth session storage now built-in.

[dshukertjr]

Thanks for this PR, but honestly, I am not a huge fan of these refactorings. I feel like the library is deviating more and more from supabase-js, which makes it hard to maintain. Unless there is something broken, I'd say we keep it the way it is, and maybe we can revisit it when a major version release comes.

[Vinzent03]

I'm quite confused, because the whole goal of this pr is to align with supabase-js .

• This now uses a single storage interface like supabase-js -> session and pkce are no longer handled separately like it's done in supabase-js
• This now uses the same storage interface like supabase-js
• The session is stored by the auth client itself like in auth-js instead of having to listen to the onAuthStateChange stream in supabase_flutter.
• The session is only broadcasted if the session is persisted, just like in auth-js

So this pr makes it easier to maintain the similarity to the js sdk.
Example:
Beforehand it was not possible to disable the session broadcasting like in auth-js, which I already mentioned in that pr, because the sdk were deviated. But with these changes it's implemented like in supabase-js

[dshukertjr]

It's a refactoring that doesn't really solve any issues that users are asking for. We can probably wait for a major version bump for changes like this.

[github-actions]

This pull request has been inactive for 90 days.
It will be automatically closed in 14 days if there is no further activity.

If you plan to continue working on this PR, please leave a comment to keep it open.

[github-actions]

This pull request was automatically closed due to inactivity.

If you'd like to continue this work, please reopen the PR or create a new one.

[Vinzent03]

This code was actually not functional before as one cannot really cancel a future. Canceling this future would just call the onCancel function, but that is not specified here. So it would have just been fine to call recoverSession() directly.

[spydon]

@Vinzent03 just fyi, I changed the base of this from the v3 branch to main so that I can remove the v3 branch.

[spydon]

@Vinzent03 this was superseded by #1804 and #1805, I'd love your review on those ones!