feat(core): Error Handling Revamp (#3102)

* Initial exports and external api changes

* Connect response to error info

* feat: Revamp error handling to include `httpResponse` and `cause` in `FirebaseAuthError` and `FirebaseAppError`, added sample tests.

* more refactoring

* refactor: Update all services to use ErrorInfo format

* refactor: Update unit tests to verify error cause and httpResponse population.

* chore: fix lint

* chore: remove debug tests

* fix: Ran api documentor and fix some export errors

* fix: Removed outdated `__proto__` workaround and updated api doc strings

* chore: Fix lint

* fix: Used a helper function to map `RequestResponse` to `HttpResponse`

* fix: Removed last of the stringified response bodies in response messages

* chore: Fix lint

* chore: Generate apidocs

* fix: Apply revamp changes to pnv

* chore: Added review suggestions

Author: jonathanedey

etc/firebase-admin.api.md

@@ -220,6 +220,14 @@ export namespace database {
     const ServerValue: rtdb.ServerValue;
 }
 
+// @public
+export interface ErrorInfo {
+    cause?: Error;
+    code: string;
+    httpResponse?: HttpResponse;
+    message: string;
+}
+
 // @public
 export interface FirebaseArrayIndexError {
     error: FirebaseError;
@@ -228,12 +236,19 @@ export interface FirebaseArrayIndexError {
 
 // @public
 export interface FirebaseError {
+    cause?: Error;
     code: string;
+    httpResponse?: HttpResponse;
     message: string;
     stack?: string;
     toJSON(): object;
 }
 
+// @public
+export class FirebaseError extends Error implements FirebaseError {
+    constructor(errorInfo: ErrorInfo);
+}
+
 // @public (undocumented)
 export function firestore(app?: App): _firestore.Firestore;
 
@@ -299,6 +314,15 @@ export interface GoogleOAuthAccessToken {
     expires_in: number;
 }
 
+// @public
+export interface HttpResponse {
+    data?: string | object;
+    headers: {
+        [key: string]: any;
+    };
+    status: number;
+}
+
 // @public (undocumented)
 export function initializeApp(options?: AppOptions, name?: string): app.App;
 

etc/firebase-admin.app-check.api.md

@@ -16,6 +16,9 @@ export class AppCheck {
     verifyToken(appCheckToken: string, options?: VerifyAppCheckTokenOptions): Promise<VerifyAppCheckTokenResponse>;
 }
 
+// @public
+export type AppCheckErrorCode = 'aborted' | 'invalid-argument' | 'invalid-credential' | 'internal-error' | 'permission-denied' | 'unauthenticated' | 'not-found' | 'app-check-token-expired' | 'unknown-error';
+
 // @public
 export interface AppCheckToken {
     token: string;
@@ -39,6 +42,14 @@ export interface DecodedAppCheckToken {
     sub: string;
 }
 
+// Warning: (ae-forgotten-export) The symbol "PrefixedFirebaseError" needs to be exported by the entry point index.d.ts
+//
+// @public
+export class FirebaseAppCheckError extends PrefixedFirebaseError {
+    // Warning: (ae-forgotten-export) The symbol "ErrorInfo" needs to be exported by the entry point index.d.ts
+    constructor(info: ErrorInfo, message?: string);
+}
+
 // @public
 export function getAppCheck(app?: App): AppCheck;
 

etc/firebase-admin.app.api.md

@@ -63,10 +63,19 @@ export interface Credential {
 // @public
 export function deleteApp(app: App): Promise<void>;
 
+// @public
+export interface ErrorInfo {
+    cause?: Error;
+    code: string;
+    httpResponse?: HttpResponse;
+    message: string;
+}
+
 // Warning: (ae-forgotten-export) The symbol "PrefixedFirebaseError" needs to be exported by the entry point index.d.ts
 //
 // @public
 export class FirebaseAppError extends PrefixedFirebaseError {
+    constructor(info: ErrorInfo, message?: string);
 }
 
 // @public
@@ -77,12 +86,19 @@ export interface FirebaseArrayIndexError {
 
 // @public
 export interface FirebaseError {
+    cause?: Error;
     code: string;
+    httpResponse?: HttpResponse;
     message: string;
     stack?: string;
     toJSON(): object;
 }
 
+// @public
+export class FirebaseError extends Error implements FirebaseError {
+    constructor(errorInfo: ErrorInfo);
+}
+
 // @public
 export function getApp(appName?: string): App;
 
@@ -97,6 +113,15 @@ export interface GoogleOAuthAccessToken {
     expires_in: number;
 }
 
+// @public
+export interface HttpResponse {
+    data?: string | object;
+    headers: {
+        [key: string]: any;
+    };
+    status: number;
+}
+
 // @public
 export function initializeApp(options?: AppOptions, appName?: string): App;