Merge branch 'main' of github.com:DutchCodingCompany/oauth_chopper into feature/add_custom_client

# Conflicts:
#	lib/src/oauth_chopper.dart
#	lib/src/oauth_grant.dart
#	pubspec.yaml

Author: Guldem

analysis_options.yaml

@@ -1,30 +1,14 @@
-# This file configures the static analysis results for your project (errors,
-# warnings, and lints).
-#
-# This enables the 'recommended' set of lints from `package:lints`.
-# This set helps identify many issues that may lead to problems when running
-# or consuming Dart code, and enforces writing Dart using a single, idiomatic
-# style and format.
-#
-# If you want a smaller set of lints you can change this to specify
-# 'package:lints/core.yaml'. These are just the most critical lints
-# (the recommended set includes the core lints).
-# The core lints are also what is used by pub.dev for scoring packages.
-
-include: package:lints/recommended.yaml
-
-# Uncomment the following section to specify additional rules.
-
-# linter:
-#   rules:
-#     - camel_case_types
-
-# analyzer:
-#   exclude:
-#     - path/to/excluded/files/**
-
-# For more information about the core and recommended set of lints, see
-# https://dart.dev/go/core-lints
-
-# For additional information about configuring this file, see
-# https://dart.dev/guides/language/analysis-options
+include: package:very_good_analysis/analysis_options.yaml
+
+analyzer:
+  errors:
+    unawaited_futures: warning
+    avoid_void_async: warning
+    missing_return: error
+    missing_required_param: error
+    invalid_annotation_target: info
+
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true

example/oauth_chopper_example.dart

@@ -1,4 +1,6 @@
-// ignore_for_file: unused_local_variable
+// ignore because its a example.
+// ignore_for_file: unused_local_variable, prefer_const_declarations,
+// ignore_for_file: prefer_const_constructors
 
 import 'package:chopper/chopper.dart';
 import 'package:oauth_chopper/oauth_chopper.dart';

lib/oauth_chopper.dart

@@ -1,4 +1,4 @@
-/// OAuthChopper for configuring OAuth authentication with [Chopper].
+/// OAuthChopper for configuring OAuth authentication with Chopper.
 ///
 /// More dartdocs go here.
 library oauth_chopper;

lib/src/extensions/request.dart

@@ -1,9 +1,11 @@
 import 'package:chopper/chopper.dart';
 
+/// Helper extension to easily apply a authorization header to a request.
 extension ChopperRequest on Request {
-  Request addAuthorizationHeader(String token) {
-    final newHeaders = Map<String, String>.from(headers);
-    newHeaders['Authorization'] = 'Bearer $token';
-    return copyWith(headers: newHeaders);
-  }
+  /// Adds a authorization header with a bearer [token] to the request.
+  Request addAuthorizationHeader(String token) => applyHeader(
+        this,
+        'Authorization',
+        'Bearer $token',
+      );
 }

lib/src/oauth_authenticator.dart

@@ -4,20 +4,33 @@ import 'package:chopper/chopper.dart';
 import 'package:oauth_chopper/oauth_chopper.dart';
 import 'package:oauth_chopper/src/extensions/request.dart';
 
+/// Callback for error handling.
 typedef OnErrorCallback = void Function(Object, StackTrace);
 
-/// OAuthAuthenticator provides a authenticator that handles OAuth authorizations.
+/// {@template authenticator}
+/// OAuthAuthenticator provides a authenticator that handles
+/// OAuth authorizations.
 /// When the provided credentials are invalid it tries to refresh them.
-/// Can throw a exceptions if no [onError] is passed. When [onError] is passed exception will be passed to [onError]
+/// Can throw a exceptions if no [onError] is passed. When [onError] is passed
+/// exception will be passed to [onError]
+/// {@endtemplate}
 class OAuthAuthenticator extends Authenticator {
+  /// {@macro authenticator}
   OAuthAuthenticator(this.oauthChopper, this.onError);
 
+  /// Callback for error handling.
   final OnErrorCallback? onError;
+
+  /// The [OAuthChopper] instance to get the token from and
+  /// to refresh the token.
   final OAuthChopper oauthChopper;
 
   @override
-  FutureOr<Request?> authenticate(Request request, Response<dynamic> response,
-      [Request? originalRequest]) async {
+  FutureOr<Request?> authenticate(
+    Request request,
+    Response<dynamic> response, [
+    Request? originalRequest,
+  ]) async {
     final token = await oauthChopper.token;
     if (response.statusCode == 401 && token != null) {
       try {

lib/src/oauth_chopper.dart

@@ -9,7 +9,8 @@ import 'package:oauth_chopper/src/oauth_token.dart';
 import 'package:oauth_chopper/src/storage/memory_storage.dart';
 import 'package:oauth_chopper/src/storage/oauth_storage.dart';
 
-/// OAuthChopper client for configuring OAuth authentication with [Chopper].
+/// {@template oauth_chopper}
+/// OAuthChopper client for configuring OAuth authentication with Chopper.
 ///
 /// For example:
 /// ```dart
@@ -19,7 +20,23 @@ import 'package:oauth_chopper/src/storage/oauth_storage.dart';
 ///     secret: secret,
 ///   );
 /// ```
+/// {@endtemplate}
 class OAuthChopper {
+  /// {@macro oauth_chopper}
+  OAuthChopper({
+    required this.authorizationEndpoint,
+    required this.identifier,
+    required this.secret,
+    this.endSessionEndpoint,
+    this.httpClient,
+
+    /// OAuth storage for storing credentials.
+    /// By default it will use a in memory storage [MemoryStorage].
+    /// For persisting the credentials implement a custom [OAuthStorage].
+    /// See [OAuthStorage] for more information.
+    OAuthStorage? storage,
+  }) : _storage = storage ?? MemoryStorage();
+
   /// OAuth authorization endpoint.
   final Uri authorizationEndpoint;
 
@@ -33,36 +50,24 @@ class OAuthChopper {
   final String secret;
 
   /// OAuth storage for storing credentials.
-  /// By default it will use a in memory storage. For persisting the credentials implement a custom [OAuthStorage].
+  /// By default it will use a in memory storage. For persisting the credentials
+  /// implement a custom [OAuthStorage].
   /// See [OAuthStorage] for more information.
   final OAuthStorage _storage;
 
   /// Provide a custom [http.Client] which will be passed to [oauth2] and used for making new requests.
   final http.Client? httpClient;
 
-  OAuthChopper({
-    required this.authorizationEndpoint,
-    required this.identifier,
-    required this.secret,
-    this.endSessionEndpoint,
-    this.httpClient,
-
-    /// OAuth storage for storing credentials.
-    /// By default it will use a in memory storage [MemoryStorage]. For persisting the credentials implement a custom [OAuthStorage].
-    /// See [OAuthStorage] for more information.
-    OAuthStorage? storage,
-  }) : _storage = storage ?? MemoryStorage();
-
   /// Get stored [OAuthToken].
   Future<OAuthToken?> get token async {
     final credentialsJson = await _storage.fetchCredentials();
-    return credentialsJson != null
-        ? OAuthToken.fromJson(credentialsJson)
-        : null;
+    return credentialsJson != null ? OAuthToken.fromJson(credentialsJson) : null;
   }
 
   /// Provides an [OAuthAuthenticator] instance.
-  /// The authenticator can throw exceptions when OAuth authentication fails. If [onError] is provided exceptions will be passed to [onError] and not be thrown.
+  /// The authenticator can throw exceptions when OAuth authentication fails.
+  /// If [onError] is provided exceptions will be passed to [onError] and not be
+  /// thrown.
   OAuthAuthenticator authenticator({
     /// When provided [onError] handles exceptions if thrown.
     OnErrorCallback? onError,
@@ -72,10 +77,12 @@ class OAuthChopper {
   /// Provides an [OAuthInterceptor] instance.
   OAuthInterceptor get interceptor => OAuthInterceptor(this);
 
-  /// Tries to refresh the available credentials and returns a new [OAuthToken] instance.
-  /// Throws an exception when refreshing fails. If the exception is a [AuthorizationException] it clears the storage.
+  /// Tries to refresh the available credentials and returns a new [OAuthToken]
+  /// instance.
+  /// Throws an exception when refreshing fails. If the exception is a
+  /// [AuthorizationException] it clears the storage.
   /// See [Credentials.refresh]
-  Future<OAuthToken?> refresh() async {
+  Future<OAuthToken?> refresh() async  {
     final credentialsJson = await _storage.fetchCredentials();
     if (credentialsJson == null) return null;
     final credentials = oauth2.Credentials.fromJson(credentialsJson);
@@ -93,15 +100,17 @@ class OAuthChopper {
     }
   }
 
-  /// Request an [OAuthGrant] and stores the credentials in the [storage].
+  /// Request an [OAuthGrant] and stores the credentials in the
+  /// [_storage].
+  ///
   /// Currently supported grants:
   ///  - [ResourceOwnerPasswordGrant]
   ///  - [ClientCredentialsGrant]
   ///  - [AuthorizationCodeGrant]
   /// Throws an exception if the grant fails.
   Future<OAuthToken> requestGrant(OAuthGrant grant) async {
     final credentials = await grant.handle(
-        authorizationEndpoint, identifier, secret, httpClient);
+        authorizationEndpoint, identifier, secret, httpClient,);
 
     await _storage.saveCredentials(credentials);
 

lib/src/oauth_grant.dart

@@ -1,9 +1,15 @@
 import 'package:http/http.dart' as http;
 import 'package:oauth2/oauth2.dart' as oauth;
 
-abstract class OAuthGrant {
+/// {@template oauth_grant}
+/// Interface for a OAuth grant.
+/// Grants are used to obtain credentials from an authorization server.
+/// {@endtemplate}
+abstract interface class OAuthGrant {
+  /// {@macro oauth_grant}
   const OAuthGrant();
 
+  /// Obtains credentials from an authorization server.
   Future<String> handle(
     Uri authorizationEndpoint,
     String identifier,
@@ -12,13 +18,24 @@ abstract class OAuthGrant {
   );
 }
 
+/// {@template resource_owner_password_grant}
 /// Obtains credentials using a [resource owner password grant](https://tools.ietf.org/html/rfc6749#section-1.3.3).
-class ResourceOwnerPasswordGrant extends OAuthGrant {
+///
+/// This grant uses the resource owner's [username] and [password] to obtain
+/// credentials.
+/// {@endtemplate}
+class ResourceOwnerPasswordGrant implements OAuthGrant {
+  /// {@macro resource_owner_password_grant}
+  const ResourceOwnerPasswordGrant({
+    required this.username,
+    required this.password,
+  });
+
+  /// Username used for obtaining credentials.
   final String username;
-  final String password;
 
-  const ResourceOwnerPasswordGrant(
-      {required this.username, required this.password});
+  /// Password used for obtaining credentials.
+  final String password;
 
   @override
   Future<String> handle(
@@ -39,8 +56,11 @@ class ResourceOwnerPasswordGrant extends OAuthGrant {
   }
 }
 
+/// {@template client_credentials_grant}
 /// Obtains credentials using a [client credentials grant](https://tools.ietf.org/html/rfc6749#section-1.3.4).
-class ClientCredentialsGrant extends OAuthGrant {
+/// {@endtemplate}
+class ClientCredentialsGrant implements OAuthGrant {
+  /// {@macro client_credentials_grant}
   const ClientCredentialsGrant();
 
   @override
@@ -60,8 +80,11 @@ class ClientCredentialsGrant extends OAuthGrant {
   }
 }
 
+/// {@template authorization_code_grant}
 /// Obtains credentials using a [authorization code grant](https://tools.ietf.org/html/rfc6749#section-1.3.1).
-class AuthorizationCodeGrant extends OAuthGrant {
+/// {@endtemplate}
+class AuthorizationCodeGrant implements OAuthGrant {
+  /// {@macro authorization_code_grant}
   const AuthorizationCodeGrant({
     required this.tokenEndpoint,
     required this.scopes,
@@ -70,10 +93,25 @@ class AuthorizationCodeGrant extends OAuthGrant {
     required this.listen,
   });
 
+  /// A URL provided by the authorization server that this library uses to
+  /// obtain long-lasting credentials.
+  ///
+  /// This will usually be listed in the authorization server's OAuth2 API
+  /// documentation.
   final Uri tokenEndpoint;
+
+  /// The redirect URL where the resource owner will redirect to.
   final Uri redirectUrl;
+
+  /// The specific permissions being requested from the authorization server may
+  /// be specified via [scopes].
   final List<String> scopes;
+
+  /// Callback used for redirect the authorizationUrl given by the authorization
+  /// server.
   final Future<void> Function(Uri authorizationUri) redirect;
+
+  /// Callback used for listening for the redirectUrl.
   final Future<Uri> Function(Uri redirectUri) listen;
 
   @override
@@ -89,12 +127,18 @@ class AuthorizationCodeGrant extends OAuthGrant {
       tokenEndpoint,
       httpClient: httpClient,
     );
-    var authorizationUrl =
-        grant.getAuthorizationUrl(redirectUrl, scopes: scopes);
+
+    final authorizationUrl = grant.getAuthorizationUrl(
+      redirectUrl,
+      scopes: scopes,
+    );
+
     await redirect(authorizationUrl);
-    var responseUrl = await listen(redirectUrl);
-    oauth.Client client =
-        await grant.handleAuthorizationResponse(responseUrl.queryParameters);
+    final responseUrl = await listen(redirectUrl);
+
+    final client = await grant.handleAuthorizationResponse(
+      responseUrl.queryParameters,
+    );
 
     return client.credentials.toJson();
   }

lib/src/oauth_interceptor.dart

@@ -4,12 +4,18 @@ import 'package:chopper/chopper.dart';
 import 'package:oauth_chopper/oauth_chopper.dart';
 import 'package:oauth_chopper/src/extensions/request.dart';
 
-/// OAuthInterceptor is responsible for adding 'Authorization' header to requests.
-/// The header is only added if there is a token available. When no token is available no header is added.
+/// {@template oauth_interceptor}
+/// OAuthInterceptor is responsible for adding 'Authorization' header to
+/// requests.
+/// The header is only added if there is a token available. When no token is
+/// available no header is added.
 /// Its added as a Bearer token.
+/// {@endtemplate}
 class OAuthInterceptor implements RequestInterceptor {
+  /// {@macro oauth_interceptor}
   OAuthInterceptor(this.oauthChopper);
 
+  /// The [OAuthChopper] instance to get the token from.
   final OAuthChopper oauthChopper;
 
   @override