fix: improve multilingual support [#128] (#132)

* fix: improve multilingual support [#128]

* fix: reformat generated file to meet flutter standards [#128]

* fix: reformat en localizations too [#128]

* fix: delete clerk_translator class [#128]

* feat: add localization of internal error messages [#128]

* feat: add accept-language header to http requests [#128]

* fix: slight refactor to stop empty error being throw [#128]

* fix: minor rewording [#128]

* fix: make autherror argument string only [#128]

* fix: formatting in generated files [#128]

* fix: pr changes

---------

Co-authored-by: Simon Lightfoot <[email protected]>

Author: shinyford

.run/Flutter Run -_ 'clerk_flutter_example'.run.xml .run/Clerk Flutter Example.run.xml

@@ -1,6 +1,6 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Flutter Run -&gt; 'clerk_flutter_example'" type="FlutterRunConfigurationType" factoryName="Flutter">
-    <option name="additionalArgs" value="--dart-define-from-file=example.env" />
+  <configuration default="false" name="Clerk Flutter Example" type="FlutterRunConfigurationType" factoryName="Flutter">
+    <option name="additionalArgs" value="--dart-define-from-file=example.json" />
     <option name="filePath" value="$PROJECT_DIR$/packages/clerk_flutter/example/lib/main.dart" />
     <method v="2" />
   </configuration>

.run/Flutter Run -_ 'clerk_widgetbook'.run.xml

@@ -39,4 +39,16 @@ scripts:
 
   # Run build and format code
   brunner_format:
-    run: melos brunner && melos format
+    run: melos run brunner && melos run format
+
+  # Run localizations
+  localization:
+    run: melos run sort_localizations && melos exec -- fvm flutter gen-l10n && melos run format
+    packageFilters:
+      scope: "clerk_flutter"
+
+  # Sort localizations `dart pub global activate arb_utils`
+  sort_localizations:
+    run: melos exec -- arb_utils sort l10n/en.arb
+    packageFilters:
+      scope: "clerk_flutter"

melos.yaml

@@ -8,8 +8,6 @@ Future<void> main() async {
     persistor: await DefaultPersistor.create(
       storageDirectory: Directory.current,
     ),
-    httpService: const DefaultHttpService(),
-    pollMode: SessionTokenPollMode.lazy,
   );
 
   Client client;

packages/clerk_auth/example/main.dart

@@ -2,6 +2,7 @@
 library clerk_auth;
 
 export 'src/clerk_api/telemetry.dart';
+export 'src/clerk_api/api.dart' show ClerkLocalesLookup;
 export 'src/clerk_auth/auth.dart';
 export 'src/clerk_constants.dart';
 export 'src/models/models.dart';

packages/clerk_auth/lib/clerk_auth.dart

@@ -15,10 +15,19 @@ import 'package:http/http.dart' as http;
 
 export 'package:clerk_auth/src/models/enums.dart' show SessionTokenPollMode;
 
+/// Used by [Api] to locate the current user locale preference.
+typedef ClerkLocalesLookup = List<String> Function();
+
 /// [Api] manages communication with the Clerk frontend API
 ///
 class Api with Logging {
-  Api._(this._tokenCache, this._domain, this._httpService, this._pollMode);
+  Api._(
+    this._tokenCache,
+    this._domain,
+    this._httpService,
+    this._localesLookup,
+    this._pollMode,
+  );
 
   /// Create an [Api] object for a given Publishable Key, or return the existing one
   /// if such already exists for that key. Requires a [publishableKey]
@@ -37,6 +46,7 @@ class Api with Logging {
     required String publishableKey,
     required Persistor persistor,
     required HttpService httpService,
+    required ClerkLocalesLookup localesLookup,
     SessionTokenPollMode pollMode = SessionTokenPollMode.lazy,
   }) =>
       Api._(
@@ -46,12 +56,14 @@ class Api with Logging {
         ),
         _deriveDomainFrom(publishableKey),
         httpService,
+        localesLookup,
         pollMode,
       );
 
   final TokenCache _tokenCache;
   final String _domain;
   final HttpService _httpService;
+  final ClerkLocalesLookup _localesLookup;
   final SessionTokenPollMode _pollMode;
   late final String _nativeDeviceId;
   Timer? _pollTimer;
@@ -878,6 +890,7 @@ class Api with Logging {
   }) {
     return {
       HttpHeaders.acceptHeader: 'application/json',
+      HttpHeaders.acceptLanguageHeader: _localesLookup().join(', '),
       HttpHeaders.contentTypeHeader: method.isGet
           ? 'application/json'
           : 'application/x-www-form-urlencoded',

packages/clerk_auth/lib/src/clerk_api/api.dart

@@ -46,6 +46,7 @@ class Auth {
     required Persistor persistor,
     bool sendTelemetryData = true,
     HttpService httpService = const DefaultHttpService(),
+    ClerkLocalesLookup localesLookup = defaultLocalesList,
     SessionTokenPollMode pollMode = SessionTokenPollMode.lazy,
   })  : telemetry = Telemetry(
           publishableKey: publishableKey,
@@ -57,9 +58,13 @@ class Auth {
           publishableKey: publishableKey,
           persistor: persistor,
           httpService: httpService,
+          localesLookup: localesLookup,
           pollMode: pollMode,
         );
 
+  /// Use 'English' as the default locale
+  static List<String> defaultLocalesList() => <String>['en'];
+
   /// The service to send telemetry to the back end
   final Telemetry telemetry;
 
@@ -151,10 +156,14 @@ class Auth {
   }
 
   ApiResponse _housekeeping(ApiResponse resp) {
-    if (resp.client case Client client when resp.isOkay) {
+    if (resp.isError) {
+      throw AuthError(
+        code: AuthErrorCode.serverErrorResponse,
+        message: '{arg}: ${resp.errorMessage}',
+        argument: resp.status.toString(),
+      );
+    } else if (resp.client case Client client) {
       this.client = client;
-    } else {
-      throw AuthError(code: resp.status, message: resp.errorMessage);
     }
     return resp;
   }
@@ -185,7 +194,10 @@ class Auth {
         : null;
     final token = await _api.sessionToken(org, templateName);
     if (token is! SessionToken) {
-      throw AuthError(message: 'No session token retrieved');
+      throw const AuthError(
+        message: 'No session token retrieved',
+        code: AuthErrorCode.noSessionTokenRetrieved,
+      );
     }
     return token;
   }
@@ -339,7 +351,10 @@ class Auth {
     String? signature,
   }) async {
     if (password != passwordConfirmation) {
-      throw AuthError(message: "Password and password confirmation must match");
+      throw const AuthError(
+        message: "Password and password confirmation must match",
+        code: AuthErrorCode.passwordMatchError,
+      );
     }
 
     switch (client.signUp) {
@@ -534,8 +549,9 @@ class Auth {
 
       final expiry = client.signIn?.firstFactorVerification?.expireAt;
       if (expiry?.isAfter(DateTime.timestamp()) != true) {
-        throw AuthError(
+        throw const AuthError(
           message: 'Awaited user action not completed in required timeframe',
+          code: AuthErrorCode.actionNotTimely,
         );
       }
 

packages/clerk_auth/lib/src/clerk_auth/auth.dart

@@ -1,27 +1,69 @@
 /// Container for errors encountered during Clerk auth(entication|orization)
 ///
-class AuthError extends Error {
+class AuthError implements Exception {
   /// Construct an [AuthError]
-  AuthError({this.code, required this.message, this.substitutions});
+  const AuthError({
+    required this.code,
+    required this.message,
+    this.argument,
+  });
 
-  /// An error [code], likely to be an http status code
-  final int? code;
+  /// Error code
+  final AuthErrorCode? code;
 
   /// The associated [message]
   final String message;
 
-  /// A possible [substitution] within the message
-  final List<dynamic>? substitutions;
+  /// Any arguments
+  final String? argument;
 
   @override
   String toString() {
-    if (substitutions case List<dynamic> subs when subs.isNotEmpty) {
-      String msg = message.replaceFirst('###', subs.first);
-      for (int i = 1; i < subs.length; ++i) {
-        msg = msg.replaceFirst('#${i + 1}#', subs[i].toString());
-      }
-      return msg;
+    if (argument case String argument) {
+      return message.replaceFirst('{arg}', argument);
     }
     return message;
   }
 }
+
+/// Code to enable consuming apps to identify the error
+enum AuthErrorCode {
+  /// Server error response
+  serverErrorResponse,
+
+  /// Error during sign-up flow
+  signUpFlowError,
+
+  /// Invalid Password
+  invalidPassword,
+
+  /// Type Invalid
+  typeInvalid,
+
+  /// No stage for status
+  noStageForStatus,
+
+  /// No session token retrieved
+  noSessionTokenRetrieved,
+
+  /// No strategy associated with type,
+  noAssociatedStrategy,
+
+  /// Password and password confirmation must match
+  passwordMatchError,
+
+  /// JWT poorly formatted
+  jwtPoorlyFormatted,
+
+  /// Awaited user action not completed in required timeframe
+  actionNotTimely,
+
+  /// No session found for user
+  noSessionFoundForUser,
+
+  /// Unsupported strategy for first factor
+  noSuchFirstFactorStrategy,
+
+  /// Unsupported strategy for second factor
+  noSuchSecondFactorStrategy,
+}

packages/clerk_auth/lib/src/clerk_auth/auth_error.dart

@@ -80,7 +80,11 @@ class Client {
         return session;
       }
     }
-    throw AuthError(message: 'No session found for ${user.name}');
+    throw AuthError(
+      message: 'No session found for {arg}',
+      argument: user.name,
+      code: AuthErrorCode.noSessionFoundForUser,
+    );
   }
 
   /// Get the latest version of this [User]

packages/clerk_auth/lib/src/models/client/client.dart

@@ -23,9 +23,13 @@ class Field {
   /// email address
   static const emailAddress = Field._(name: 'email_address');
 
+  /// username
+  static const username = Field._(name: 'username');
+
   static final _values = <String, Field>{
     phoneNumber.name: phoneNumber,
     emailAddress.name: emailAddress,
+    username.name: username,
   };
 
   /// The [values] of the Fields

packages/clerk_auth/lib/src/models/client/field.dart

@@ -25,7 +25,11 @@ class SessionToken {
 
   late final _parts = switch (jwt.split('.')) {
     List<String> parts when parts.length == 3 => parts,
-    _ => throw AuthError(message: "JWT poorly formatted: $jwt"),
+    _ => throw AuthError(
+        message: "JWT poorly formatted: {arg}",
+        argument: jwt,
+        code: AuthErrorCode.jwtPoorlyFormatted,
+      ),
   };
 
   /// The [header] of the token

packages/clerk_auth/lib/src/models/client/session_token.dart

@@ -94,7 +94,19 @@ class SignIn {
     for (final factor in factors) {
       if (factor.strategy == strategy) return factor;
     }
-    throw AuthError(
-        message: 'Strategy $strategy unsupported for $stage factor');
+    switch (stage) {
+      case Stage.first:
+        throw AuthError(
+          message: 'Strategy {arg} unsupported for first factor',
+          argument: strategy.toString(),
+          code: AuthErrorCode.noSuchFirstFactorStrategy,
+        );
+      case Stage.second:
+        throw AuthError(
+          message: 'Strategy {arg} unsupported for second factor',
+          argument: strategy.toString(),
+          code: AuthErrorCode.noSuchSecondFactorStrategy,
+        );
+    }
   }
 }

packages/clerk_auth/lib/src/models/client/sign_in.dart

@@ -199,8 +199,9 @@ class Strategy {
       'phone_number' => Strategy.phoneCode,
       'email_address' => Strategy.emailCode,
       String name => throw AuthError(
-          message: 'No strategy associated with ### \'#2#\'',
-          substitutions: [T.runtimeType, name],
+          message: 'No strategy associated with {arg}',
+          argument: '${T.runtimeType} \'$name\'',
+          code: AuthErrorCode.noAssociatedStrategy,
         ),
     };
   }

packages/clerk_auth/lib/src/models/client/strategy.dart

@@ -168,8 +168,9 @@ enum Stage {
       Status.needsFirstFactor => first,
       Status.needsSecondFactor => second,
       _ => throw AuthError(
-          message: 'No Stage for ###',
-          substitutions: [status],
+          message: 'No Stage for {arg}',
+          argument: status.toString(),
+          code: AuthErrorCode.noStageForStatus,
         ),
     };
   }

packages/clerk_auth/lib/src/models/enums.dart

@@ -17,6 +17,7 @@ void main() {
       publishableKey: env.publishableKey,
       persistor: Persistor.none,
       httpService: httpService,
+      localesLookup: testLocalesLookup,
       pollMode: SessionTokenPollMode.lazy,
     );
     await api.initialize();

packages/clerk_auth/test/integration/clerk_api/environment_test.dart

@@ -24,6 +24,7 @@ void main() {
       publishableKey: env.publishableKey,
       persistor: Persistor.none,
       httpService: httpService,
+      localesLookup: testLocalesLookup,
       pollMode: SessionTokenPollMode.lazy,
     );
     await api.initialize();

packages/clerk_auth/test/integration/clerk_api/sign_in_test.dart

@@ -40,6 +40,7 @@ void main() {
       publishableKey: env.publishableKey,
       persistor: Persistor.none,
       httpService: httpService,
+      localesLookup: testLocalesLookup,
       pollMode: SessionTokenPollMode.lazy,
     );
     await api.initialize();

packages/clerk_auth/test/integration/clerk_api/sign_up_test.dart

@@ -32,6 +32,7 @@ void main() {
       publishableKey: env.publishableKey,
       persistor: Persistor.none,
       httpService: httpService,
+      localesLookup: testLocalesLookup,
       pollMode: SessionTokenPollMode.lazy,
     );
     await api.initialize();

packages/clerk_auth/test/integration/clerk_api/user_details_test.dart

@@ -67,6 +67,7 @@ class TestHttpService implements HttpService {
   ) {
     final hdrs = {...?headers}
       ..remove(HttpHeaders.acceptHeader)
+      ..remove(HttpHeaders.acceptLanguageHeader)
       ..remove(HttpHeaders.contentTypeHeader)
       ..remove(HttpHeaders.authorizationHeader)
       ..remove('clerk-api-version')
@@ -122,3 +123,5 @@ class TestHttpServiceError extends Error {
   @override
   String toString() => '$runtimeType: $message';
 }
+
+List<String> testLocalesLookup() => <String>['en'];