[google_sign_in] Redesign API for current identity SDKs - Platform Interface

packages/google_sign_in/google_sign_in_platform_interface/CHANGELOG.md

@@ -1,5 +1,9 @@
-## NEXT
+## 3.0.0
 
+* **BREAKING CHANGE**: Overhauls the entire API surface to better abstract the
+  current set of underlying platform SDKs, and to use structured errors. See
+  API doc comments for details on the behaviors that platform implementations
+  must implement.
 * Updates minimum supported SDK version to Flutter 3.27/Dart 3.6.
 
 ## 2.5.0

packages/google_sign_in/google_sign_in_platform_interface/lib/google_sign_in_platform_interface.dart

@@ -4,13 +4,10 @@
 
 import 'dart:async';
 
-import 'package:flutter/foundation.dart' show visibleForTesting;
 import 'package:plugin_platform_interface/plugin_platform_interface.dart';
 
-import 'src/method_channel_google_sign_in.dart';
 import 'src/types.dart';
 
-export 'src/method_channel_google_sign_in.dart';
 export 'src/types.dart';
 
 /// The interface that implementations of google_sign_in must implement.
@@ -27,134 +24,151 @@ abstract class GoogleSignInPlatform extends PlatformInterface {
 
   static final Object _token = Object();
 
-  /// Only mock implementations should set this to `true`.
+  /// The instance of [GoogleSignInPlatform] to use.
   ///
-  /// Mockito mocks implement this class with `implements` which is forbidden
-  /// (see class docs). This property provides a backdoor for mocks to skip the
-  /// verification that the class isn't implemented with `implements`.
-  @visibleForTesting
-  @Deprecated('Use MockPlatformInterfaceMixin instead')
-  bool get isMock => false;
-
-  /// The default instance of [GoogleSignInPlatform] to use.
-  ///
-  /// Platform-specific plugins should override this with their own
+  /// Platform-implementations should override this with their own
   /// platform-specific class that extends [GoogleSignInPlatform] when they
   /// register themselves.
   ///
   /// Defaults to [MethodChannelGoogleSignIn].
   static GoogleSignInPlatform get instance => _instance;
 
-  static GoogleSignInPlatform _instance = MethodChannelGoogleSignIn();
+  static GoogleSignInPlatform _instance = _PlaceholderImplementation();
 
-  // TODO(amirh): Extract common platform interface logic.
-  // https://github.com/flutter/flutter/issues/43368
   static set instance(GoogleSignInPlatform instance) {
-    if (!instance.isMock) {
-      PlatformInterface.verify(instance, _token);
-    }
+    PlatformInterface.verify(instance, _token);
     _instance = instance;
   }
 
-  /// Initializes the plugin. Deprecated: call [initWithParams] instead.
+  /// Initializes the plugin with specified [params]. You must call this method
+  /// before calling other methods.
   ///
-  /// The [hostedDomain] argument specifies a hosted domain restriction. By
-  /// setting this, sign in will be restricted to accounts of the user in the
-  /// specified domain. By default, the list of accounts will not be restricted.
+  /// See:
   ///
-  /// The list of [scopes] are OAuth scope codes to request when signing in.
-  /// These scope codes will determine the level of data access that is granted
-  /// to your application by the user. The full list of available scopes can be
-  /// found here: <https://developers.google.com/identity/protocols/googlescopes>
+  /// * [InitParameters]
+  Future<void> init(InitParameters params);
+
+  /// Attempts to sign in without an explicit user intent.
   ///
-  /// The [signInOption] determines the user experience. [SigninOption.games] is
-  /// only supported on Android.
+  /// This is intended to support the use case where the user might be expected
+  /// to be signed in, but hasn't explicitly requested sign in, such as when
+  /// launching an application that is intended to be used while signed in.
   ///
-  /// See:
-  /// https://developers.google.com/identity/sign-in/web/reference#gapiauth2initparams
-  Future<void> init({
-    List<String> scopes = const <String>[],
-    SignInOption signInOption = SignInOption.standard,
-    String? hostedDomain,
-    String? clientId,
-  }) async {
-    throw UnimplementedError('init() has not been implemented.');
-  }
+  /// This may be silent, or may show minimal UI, depending on the platform and
+  /// the context.
+  Future<AuthenticationResults?>? attemptLightweightAuthentication(
+      AttemptLightweightAuthenticationParameters params);
 
-  /// Initializes the plugin with specified [params]. You must call this method
-  /// before calling other methods.
+  /// Returns true if the platform implementation supports the [authenticate]
+  /// method.
   ///
-  /// See:
+  /// The default is true, but platforms that cannot support [authenticate] can
+  /// override this to return false, throw [UnsupportedError] from
+  /// [authenticate], and provide a different, platform-specific authentication
+  /// flow.
+  bool supportsAuthenticate();
+
+  /// Signs in with explicit user intent.
   ///
-  /// * [SignInInitParameters]
-  Future<void> initWithParams(SignInInitParameters params) async {
-    await init(
-      scopes: params.scopes,
-      signInOption: params.signInOption,
-      hostedDomain: params.hostedDomain,
-      clientId: params.clientId,
-    );
-  }
+  /// This is intended to support the use case where the user has expressed
+  /// an explicit intent to sign in.
+  Future<AuthenticationResults> authenticate(AuthenticateParameters params);
 
-  /// Attempts to reuse pre-existing credentials to sign in again, without user interaction.
-  Future<GoogleSignInUserData?> signInSilently() async {
-    throw UnimplementedError('signInSilently() has not been implemented.');
-  }
+  /// Whether or not authorization calls that could show UI must be called from
+  /// a user interaction, such as a button press, on the current platform.
+  ///
+  /// Platforms that can fail to show UI without an active user interaction,
+  /// such as a web implementations that uses popups, should return false.
+  bool authorizationRequiresUserInteraction();
 
-  /// Signs in the user with the options specified to [init].
-  Future<GoogleSignInUserData?> signIn() async {
-    throw UnimplementedError('signIn() has not been implemented.');
+  /// Returns the tokens used to authenticate other API calls from a client.
+  ///
+  /// This should only return null if prompting would be necessary but [params]
+  /// do not allow it, otherwise any failure should return an error.
+  Future<ClientAuthorizationTokenData?> clientAuthorizationTokensForScopes(
+      ClientAuthorizationTokensForScopesParameters params);
+
+  /// Returns the tokens used to authenticate other API calls from a server.
+  ///
+  /// This should only return null if prompting would be necessary but [params]
+  /// do not allow it, otherwise any failure should return an error.
+  Future<ServerAuthorizationTokenData?> serverAuthorizationTokensForScopes(
+      ServerAuthorizationTokensForScopesParameters params);
+
+  /// Signs out previously signed in accounts.
+  Future<void> signOut(SignOutParams params);
+
+  /// Revokes all of the scopes that all signed in users granted, and then signs
+  /// them out.
+  Future<void> disconnect(DisconnectParams params);
+
+  /// Returns a stream of authentication events.
+  ///
+  /// If this is not overridden, the app-facing package will assume that the
+  /// futures returned by [attemptLightweightAuthentication], [authenticate],
+  /// and [signOut] are the only sources of authentication-related events.
+  /// Implementations that have other sources should override this and provide
+  /// a stream with all authentication and sign-out events.
+  /// These will normally come from asynchronous flows, like the authenticate
+  /// and signOut methods, as well as potentially from platform-specific methods
+  /// (such as the Google Sign-In Button Widget from the Web implementation).
+  ///
+  /// Implementations should never intentionally call `addError` for this
+  /// stream, and should instead use AuthenticationEventException. This is to
+  /// ensure via the type system that implementations are always sending
+  /// [GoogleSignInException] for know failure cases.
+  Stream<AuthenticationEvent>? get authenticationEvents => null;
+}
+
+/// An implementation of GoogleSignInPlatform that throws unimplemented errors,
+/// to use as a default instance if no platform implementation has been
+/// registered.
+class _PlaceholderImplementation extends GoogleSignInPlatform {
+  @override
+  Future<void> init(InitParameters params) {
+    throw UnimplementedError();
   }
 
-  /// Returns the Tokens used to authenticate other API calls.
-  Future<GoogleSignInTokenData> getTokens(
-      {required String email, bool? shouldRecoverAuth}) async {
-    throw UnimplementedError('getTokens() has not been implemented.');
+  @override
+  Future<AuthenticationResults?> attemptLightweightAuthentication(
+      AttemptLightweightAuthenticationParameters params) {
+    throw UnimplementedError();
   }
 
-  /// Signs out the current account from the application.
-  Future<void> signOut() async {
-    throw UnimplementedError('signOut() has not been implemented.');
+  @override
+  bool supportsAuthenticate() {
+    throw UnimplementedError();
   }
 
-  /// Revokes all of the scopes that the user granted.
-  Future<void> disconnect() async {
-    throw UnimplementedError('disconnect() has not been implemented.');
+  @override
+  Future<AuthenticationResults> authenticate(AuthenticateParameters params) {
+    throw UnimplementedError();
   }
 
-  /// Returns whether the current user is currently signed in.
-  Future<bool> isSignedIn() async {
-    throw UnimplementedError('isSignedIn() has not been implemented.');
+  @override
+  bool authorizationRequiresUserInteraction() {
+    throw UnimplementedError();
   }
 
-  /// Clears any cached information that the plugin may be holding on to.
-  Future<void> clearAuthCache({required String token}) async {
-    throw UnimplementedError('clearAuthCache() has not been implemented.');
+  @override
+  Future<ClientAuthorizationTokenData?> clientAuthorizationTokensForScopes(
+      ClientAuthorizationTokensForScopesParameters params) {
+    throw UnimplementedError();
   }
 
-  /// Requests the user grants additional Oauth [scopes].
-  ///
-  /// Scopes should come from the full  list
-  /// [here](https://developers.google.com/identity/protocols/googlescopes).
-  Future<bool> requestScopes(List<String> scopes) async {
-    throw UnimplementedError('requestScopes() has not been implemented.');
+  @override
+  Future<ServerAuthorizationTokenData?> serverAuthorizationTokensForScopes(
+      ServerAuthorizationTokensForScopesParameters params) {
+    throw UnimplementedError();
   }
 
-  /// Checks if the current user has granted access to all the specified [scopes].
-  ///
-  /// Optionally, an [accessToken] can be passed for applications where a
-  /// long-lived token may be cached (like the web).
-  Future<bool> canAccessScopes(
-    List<String> scopes, {
-    String? accessToken,
-  }) async {
-    throw UnimplementedError('canAccessScopes() has not been implemented.');
+  @override
+  Future<void> signOut(SignOutParams params) {
+    throw UnimplementedError();
   }
 
-  /// Returns a stream of [GoogleSignInUserData] authentication events.
-  ///
-  /// These will normally come from asynchronous flows, like the Google Sign-In
-  /// Button Widget from the Web implementation, and will be funneled directly
-  /// to the `onCurrentUserChanged` Stream of the plugin.
-  Stream<GoogleSignInUserData?>? get userDataEvents => null;
+  @override
+  Future<void> disconnect(DisconnectParams params) {
+    throw UnimplementedError();
+  }
 }