feat(exception): enhance FirebaseAppException with JSON serialization and update error codes

Author: demolaf

packages/dart_firebase_admin/lib/src/app/app_exception.dart

@@ -1,23 +1,13 @@
 part of '../app.dart';
 
 /// Exception thrown for Firebase app initialization and lifecycle errors.
-class FirebaseAppException implements Exception {
+class FirebaseAppException extends FirebaseAdminException {
   FirebaseAppException(this.errorCode, [String? message])
-    : code = errorCode.code,
-      _message = message;
+    : super('app', errorCode.code, message ?? errorCode.message);
 
   /// The error code object containing code and default message.
   final AppErrorCode errorCode;
 
-  /// The error code string.
-  final String code;
-
-  /// Custom error message, if provided.
-  final String? _message;
-
-  /// The error message. Returns custom message if provided, otherwise default.
-  String get message => _message ?? errorCode.message;
-
   @override
   String toString() => 'FirebaseAppException($code): $message';
 }

packages/dart_firebase_admin/lib/src/app/exception.dart

@@ -11,6 +11,16 @@ class FirebaseArrayIndexError {
 
   /// The error object.
   final FirebaseAdminException error;
+
+  /// Converts this error to a JSON-serializable map.
+  ///
+  /// This is useful for structured logging and error reporting.
+  /// The returned map contains:
+  /// - `index`: The index of the errored item
+  /// - `error`: The serialized error object (with code and message)
+  Map<String, dynamic> toJson() {
+    return {'index': index, 'error': error.toJson()};
+  }
 }
 
 /// A set of platform level error codes.
@@ -78,6 +88,27 @@ abstract class FirebaseAdminException implements Exception {
   /// this message should not be displayed in your application.
   String get message => _message ?? _platformErrorCodeMessage(_code);
 
+  /// Converts this exception to a JSON-serializable map.
+  ///
+  /// This is useful for structured logging and error reporting in GCP Cloud Logging.
+  /// The returned map contains:
+  /// - `code`: The error code string (e.g., "auth/invalid-uid")
+  /// - `message`: The error message
+  ///
+  /// Example:
+  /// ```dart
+  /// try {
+  ///   // ...
+  /// } catch (e) {
+  ///   if (e is FirebaseAdminException) {
+  ///     print(jsonEncode(e.toJson())); // Logs structured JSON
+  ///   }
+  /// }
+  /// ```
+  Map<String, dynamic> toJson() {
+    return {'code': code, 'message': message};
+  }
+
   @override
   String toString() {
     return '$runtimeType($code, $message)';

packages/dart_firebase_admin/test/app/app_registry_test.dart

@@ -165,7 +165,7 @@ void main() {
                 () => registry.fetchOptionsFromEnvironment(),
                 throwsA(
                   isA<FirebaseAppException>()
-                      .having((e) => e.code, 'code', 'invalid-argument')
+                      .having((e) => e.code, 'code', 'app/invalid-argument')
                       .having(
                         (e) => e.message,
                         'message',
@@ -188,7 +188,7 @@ void main() {
               () => registry.fetchOptionsFromEnvironment(),
               throwsA(
                 isA<FirebaseAppException>()
-                    .having((e) => e.code, 'code', 'invalid-argument')
+                    .having((e) => e.code, 'code', 'app/invalid-argument')
                     .having(
                       (e) => e.message,
                       'message',
@@ -238,7 +238,7 @@ void main() {
                 isA<FirebaseAppException>().having(
                   (e) => e.code,
                   'code',
-                  'invalid-app-options',
+                  'app/invalid-app-options',
                 ),
               ),
             );
@@ -263,7 +263,7 @@ void main() {
                 isA<FirebaseAppException>().having(
                   (e) => e.code,
                   'code',
-                  'invalid-app-options',
+                  'app/invalid-app-options',
                 ),
               ),
             );
@@ -306,7 +306,7 @@ void main() {
             isA<FirebaseAppException>().having(
               (e) => e.code,
               'code',
-              'duplicate-app',
+              'app/duplicate-app',
             ),
           ),
         );
@@ -365,7 +365,7 @@ void main() {
           ),
           throwsA(
             isA<FirebaseAppException>()
-                .having((e) => e.code, 'code', 'invalid-app-name')
+                .having((e) => e.code, 'code', 'app/invalid-app-name')
                 .having(
                   (e) => e.message,
                   'message',
@@ -380,7 +380,7 @@ void main() {
           () => registry.getApp(''),
           throwsA(
             isA<FirebaseAppException>()
-                .having((e) => e.code, 'code', 'invalid-app-name')
+                .having((e) => e.code, 'code', 'app/invalid-app-name')
                 .having(
                   (e) => e.message,
                   'message',
@@ -417,7 +417,7 @@ void main() {
           () => registry.getApp(),
           throwsA(
             isA<FirebaseAppException>()
-                .having((e) => e.code, 'code', 'no-app')
+                .having((e) => e.code, 'code', 'app/no-app')
                 .having(
                   (e) => e.message,
                   'message',
@@ -435,7 +435,7 @@ void main() {
           () => registry.getApp('my-app'),
           throwsA(
             isA<FirebaseAppException>()
-                .having((e) => e.code, 'code', 'no-app')
+                .having((e) => e.code, 'code', 'app/no-app')
                 .having(
                   (e) => e.message,
                   'message',