test(crashlytics): ensure modular API are exported properly (#7929)

packages/crashlytics/__tests__/crashlytics.test.ts

@@ -1,6 +1,21 @@
 import { describe, expect, it } from '@jest/globals';
 
-import { firebase } from '../lib';
+import {
+  firebase,
+  getCrashlytics,
+  isCrashlyticsCollectionEnabled,
+  checkForUnsentReports,
+  deleteUnsentReports,
+  didCrashOnPreviousExecution,
+  crash,
+  log,
+  recordError,
+  sendUnsentReports,
+  setUserId,
+  setAttribute,
+  setAttributes,
+  setCrashlyticsCollectionEnabled,
+} from '../lib';
 
 describe('Crashlytics', function () {
   describe('namespace', function () {
@@ -10,4 +25,58 @@ describe('Crashlytics', function () {
       expect(app.crashlytics().app).toEqual(app);
     });
   });
+
+  describe('modular', function () {
+    it('`getCrashlytics` function is properly exposed to end user', function () {
+      expect(getCrashlytics).toBeDefined();
+    });
+
+    it('`isCrashlyticsCollectionEnabled` function is properly exposed to end user', function () {
+      expect(isCrashlyticsCollectionEnabled).toBeDefined();
+    });
+
+    it('`checkForUnsentReports` function is properly exposed to end user', function () {
+      expect(checkForUnsentReports).toBeDefined();
+    });
+
+    it('`deleteUnsentReports` function is properly exposed to end user', function () {
+      expect(deleteUnsentReports).toBeDefined();
+    });
+
+    it('`didCrashOnPreviousExecution` function is properly exposed to end user', function () {
+      expect(didCrashOnPreviousExecution).toBeDefined();
+    });
+
+    it('`crash` function is properly exposed to end user', function () {
+      expect(crash).toBeDefined();
+    });
+
+    it('`log` function is properly exposed to end user', function () {
+      expect(log).toBeDefined();
+    });
+
+    it('`recordError` function is properly exposed to end user', function () {
+      expect(recordError).toBeDefined();
+    });
+
+    it('`sendUnsentReports` function is properly exposed to end user', function () {
+      expect(sendUnsentReports).toBeDefined();
+    });
+
+    it('`setUserId` function is properly exposed to end user', function () {
+      expect(setUserId).toBeDefined();
+    });
+
+    it('`setAttribute` function is properly exposed to end user', function () {
+      expect(setAttribute).toBeDefined();
+    });
+
+    it('`setAttributes` function is properly exposed to end user', function () {
+      expect(setAttributes).toBeDefined();
+    });
+
+    it('`setCrashlyticsCollectionEnabled` function is properly exposed to end user', function () {
+      expect(setCrashlyticsCollectionEnabled).toBeDefined();
+    });
+  });
 });

packages/crashlytics/lib/index.d.ts

@@ -266,6 +266,8 @@ export const firebase: ReactNativeFirebase.Module & {
 
 export default defaultExport;
 
+export * from './modular';
+
 /**
  * Attach namespace to `firebase.` and `FirebaseApp.`.
  */

packages/crashlytics/lib/modular/index.js

@@ -1,11 +1,16 @@
 import { firebase } from '..';
 
 /**
- * @typedef {import("..").FirebaseApp} FirebaseApp
- * @typedef {import("..").FirebaseCrashlyticsTypes.Module} FirebaseCrashlytics
+ * @typedef {import('@firebase/app').FirebaseApp} FirebaseApp
+ * @typedef {import('..').FirebaseCrashlyticsTypes.Module} FirebaseCrashlytics
  */
 
 /**
+ * Returns Crashlytics instance.
+ * #### Example
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * ```
  * @param {FirebaseApp} app
  * @returns {FirebaseCrashlytics}
  */
@@ -14,6 +19,14 @@ export function getCrashlytics() {
 }
 
 /**
+ * Whether Crashlytics reporting is enabled.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * const isEnabled = isCrashlyticsCollectionEnabled(crashlytics);
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @returns {boolean}
  */
@@ -22,6 +35,20 @@ export function isCrashlyticsCollectionEnabled(crashlytics) {
 }
 
 /**
+ * Determines whether there are any unsent crash reports cached on the device. The callback only executes
+ * if automatic data collection is disabled.
+ *
+ * #### Example
+ *
+ * ```js
+ * async checkReports() {
+ * // returns boolean value
+ *  const crashlytics = getCrashlytics();
+ *  const unsentReports = await checkForUnsentReports(crashlytics);
+ * }
+ *
+ * checkReports();
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @returns {Promise<boolean>}
  */
@@ -30,6 +57,15 @@ export function checkForUnsentReports(crashlytics) {
 }
 
 /**
+ * Deletes any unsent reports on the device. This method only applies if automatic data collection is
+ * disabled.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * deleteUnsentReports(crashlytics);
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @returns {Promise<void>}
  */
@@ -38,6 +74,19 @@ export function deleteUnsentReports(crashlytics) {
 }
 
 /**
+ * Returns a boolean value indicating whether the app crashed during the previous execution.
+ *
+ * #### Example
+ *
+ * ```js
+ * async didCrashPreviously() {
+ * // returns boolean value
+ * const crashlytics = getCrashlytics();
+ * const didCrash = await didCrashOnPreviousExecution(crashlytics);
+ * }
+ *
+ * didCrashPreviously();
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @returns {Promise<boolean>}
  */
@@ -46,6 +95,16 @@ export function didCrashOnPreviousExecution(crashlytics) {
 }
 
 /**
+ * Cause your app to crash for testing purposes. This is a native crash and will not contain a javascript stack trace.
+ * Note that crashes are intercepted by debuggers on iOS so no report will be seen under those conditions. Additionally
+ * if it is a debug build you will need to ensure your firebase.json is configured to enable crashlytics even in debug mode.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * crash(crashlytics);
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @returns {void}
  */
@@ -54,6 +113,15 @@ export function crash(crashlytics) {
 }
 
 /**
+ * Log a message that will appear in any subsequent Crash or Non-fatal error reports.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * log(crashlytics, 'Testing a crash');
+ * crash(crashlytics);
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @param {string} message
  * @returns {void}
@@ -63,6 +131,21 @@ export function log(crashlytics, message) {
 }
 
 /**
+ * Record a JavaScript Error.
+ *
+ * The JavaScript stack trace is converted into a mock native iOS or Android exception before submission.
+ * The line numbers in the stack trace (if available) will be relative to the javascript bundle built by your packager,
+ * after whatever transpilation or minimization steps happen. You will need to maintain sourcemaps to decode them if desired.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * recordError(
+ *  crashlytics,
+ *  new Error('An error was caught')
+ * );
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @param {Error} error
  * @param {string | undefined} jsErrorName
@@ -73,6 +156,15 @@ export function recordError(crashlytics, error, jsErrorName) {
 }
 
 /**
+ * Enqueues any unsent reports on the device to upload to Crashlytics. This method only applies if
+ * automatic data collection is disabled.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * sendUnsentReports(crashlytics);
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @returns {void}
  */
@@ -81,6 +173,24 @@ export function sendUnsentReports(crashlytics) {
 }
 
 /**
+ * Specify a user identifier which will be visible in the Firebase Crashlytics console.
+ *
+ * It is recommended for privacy purposes that this value be a value that's meaningless to a third-party
+ * observer; such as an arbitrary string that ties an end-user to a record in your system e.g. a database record id.
+ *
+ * #### Example
+ *
+ * ```js
+ * const auth = getAuth();
+ * const crashlytics = getCrashlytics();
+ * // Custom user id
+ * await setUserId(crashlytics, '123456789');
+ * // Firebase auth uid
+ * await setUserId(
+ *  crashlytics,
+ *  auth.currentUser.uid
+ * );
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @param {string} userId
  * @returns {Promise<null>}
@@ -90,6 +200,14 @@ export function setUserId(crashlytics, userId) {
 }
 
 /**
+ * Sets a string value to be associated with the given attribute name which will be visible in the Firebase Crashlytics console.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * await setAttribute(crashlytics, 'role', 'admin');
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @param {string} name
  * @param {string} value
@@ -100,6 +218,17 @@ export function setAttribute(crashlytics, name, value) {
 }
 
 /**
+ * Like `setAttribute` but for multiple attributes.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * await setAttributes(crashlytics, {
+ *   role: 'admin',
+ *   followers: '13',
+ * });
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @param {{ [key: string]: string }} attributes
  * @returns {Promise<null>}
@@ -109,6 +238,17 @@ export function setAttributes(crashlytics, attributes) {
 }
 
 /**
+ * Enable/disable Crashlytics reporting.
+ *
+ * Use this for opt-in first user data collection flows combined with `firebase.json` settings to disable auto collection.
+ *
+ * #### Example
+ *
+ * ```js
+ * const crashlytics = getCrashlytics();
+ * // Disable crash reporting
+ * await setCrashlyticsCollectionEnabled(crashlytics, false);
+ * ```
  * @param {FirebaseCrashlytics} crashlytics
  * @param {boolean} enabled
  * @returns {Promise<null>}