Improved error message for $firebaseAuth initialization and updated migration guide (#750)

Author: abeisgoat

docs/migration/1XX-to-2XX.md

@@ -24,21 +24,36 @@ for details on how to upgrade to the Firebase `3.x.x` SDK.
 
 ## `$firebaseAuth` Method Renames / Signature Changes
 
+The `$firebaseAuth` service now accepts an optional Firebase `auth` instance instead of a Firebase
+Database reference.
+
+```js
+// Old
+$firebaseAuth(ref);
+
+// New
+$firebaseAuth();
+// Or if you need to explicitly provide an auth instance
+$firebaseAuth(firebase.auth());
+```
+
 Several authentication methods have been renamed and / or have different method signatures:
 
 | Old Method | New Method | Notes |
 |------------|------------|------------------|
 | `$authAnonymously(options)` | `$signInAnonymously()` | No longer takes any arguments |
+| `$authWithPassword(credentials)` | `$signInWithEmailAndPassword(email, password)` | |
 | `$authWithCustomToken(token)` | `$signInWithCustomToken(token)` | |
 | `$authWithOAuthPopup(provider[, options])` | `$signInWithPopup(provider)` | `options` can be provided by passing a configured `firebase.database.AuthProvider` instead of a `provider` string |
 | `$authWithOAuthRedirect(provider[, options])` | `$signInWithRedirect(provider)` | `options` can be provided by passing a configured `firebase.database.AuthProvider` instead of a `provider` string |
+| `$authWithOAuthToken(provider, token)` | `$signInWithCredential(credential)` | Tokens must now be transformed into provider specific credentials. This is discussed more in the [Firebase Authentication guide](https://firebase.google.com/docs/auth/#key_functions). |
 | `$createUser(credentials)` | `$createUserWithEmailAndPassword(email, password)` | |
 | `$removeUser(credentials)` | `$deleteUser()` | Deletes the currently signed in user |
 | `$changeEmail(credentials)` | `$updateEmail(newEmail)` | Changes the email of the currently signed in user |
 | `$changePassword(credentials)` | `$updatePassword(newPassword)` | Changes the password of the currently signed in user |
 | `$resetPassword(credentials)` | `$sendPasswordResetEmail(email)` | |
 | `$unauth()` | `$signOut()` | |
-| `$onAuth(callback)` | `$onAuthStateChanged(callback)` |   |
+| `$onAuth(callback)` | `$onAuthStateChanged(callback)` | |
 
 
 ## Auth Payload Format Changes

src/FirebaseAuth.js

@@ -8,7 +8,7 @@
       /**
        * This factory returns an object allowing you to manage the client's authentication state.
        *
-       * @param {Firebase} ref A Firebase reference to authenticate.
+       * @param {Firebase.auth.Auth} auth A Firebase auth instance to authenticate.
        * @return {object} An object containing methods for authenticating clients, retrieving
        * authentication state, and managing users.
        */
@@ -24,9 +24,13 @@
   FirebaseAuth = function($q, $firebaseUtils, auth) {
     this._q = $q;
     this._utils = $firebaseUtils;
-    if (typeof ref === 'string') {
-      throw new Error('Please provide a Firebase reference instead of a URL when creating a `$firebaseAuth` object.');
+
+    if (typeof auth === 'string') {
+      throw new Error('The $firebaseAuth service accepts a Firebase auth instance (or nothing) instead of a URL.');
+    } else if (typeof auth.ref !== 'undefined') {
+      throw new Error('The $firebaseAuth service accepts a Firebase auth instance (or nothing) instead of a Database reference.');
     }
+
     this._auth = auth;
     this._initialAuthResolver = this._initAuthResolver();
   };

tests/unit/FirebaseAuth.spec.js

@@ -98,6 +98,16 @@ describe('FirebaseAuth',function(){
     });
   });
 
+  it('will throw an error if a database reference is used in place of a Firebase auth instance',function(){
+    expect(function(){
+      $firebaseAuth(firebase.database().ref());
+    }).toThrow();
+  });
+
+  it('will not throw an error if an auth instance is provided',function(){
+      $firebaseAuth(firebase.auth());
+  });
+
   describe('$signInWithCustomToken',function(){
     it('should return a promise', function() {
       expect(authService.$signInWithCustomToken('myToken')).toBeAPromise();