Documented accounts_client.js.

docs/accounts-base/README.md

@@ -36,8 +36,48 @@ Connections have observers based on the Mongo implementation.
 
 ## Classes
 
-### `AccountsClient`
-
+### `AccountsClient extends AccountsCommon` (`accounts_client.js`)
+
+* `constructor(options)`
+    * `options``:
+        * `connection`: optional DDP connection to reuse
+        * `ddpUrl`: optional DDP URL to create a new connection
+    * calls parent constructor
+    * initializes properties:
+        * `_loggingIn`: "private", use `loggingIn()`/`setLoggingIn()` for reactivity
+        * `_loggingInDeps`: Tracker dependency
+        * `_loginServicesHandle`: subscription to `meteor.loginServiceConfiguration`
+        * `_pageLoadLoginCallbacks`: an array of page loading callbacks
+        * `_pageLoadLoginAttemptInfo`: holds the information passed to login callbacks during a page-load login attempt
+    * invokes `_initUrlMatching()` (from `url_client.js`)
+    * invokes `_initLocalStorage()` (from `localstorage_token.js`)
+* `callLoginMethod(options)`: call login method on the server
+    * A login method is a method which on success calls `this.setUserId(id)` and `Accounts._setLoginToken` on the server and returns an object with fields 'id' (actually `userId` (containing the user id), 'token' (containing a resume token), and optionally `tokenExpires`.
+    * This function takes care of:
+        * Updating the `Meteor.loggingIn()` reactive data source
+        * Calling the method in `wait` mode
+        * On success, saving the resume token to localStorage
+        * On success, calling `Accounts.connection.setUserId()`
+        * Setting up an `onReconnect` handler which logs in with the resume token
+        * Running `onLoginHook` or `onLoginFailureHook` then the `userCallback` option
+    * Options:
+        * `methodName`: The method to call (default `login`)
+        * `methodArguments`: The arguments for the method
+        * `validateResult`: If provided, will be called with the result of the method. If it throws, the client will not be logged in (and its error will be passed to the callback).
+        * `userCallback`: Will be called with no arguments once the user is fully logged in, or with a single-element array containing the error on error.
+* `loggingIn()`: reactive getter for `_loggingIn`
+* `loginServicesConfigured()`: A reactive function returning whether the `loginServiceConfiguration` subscription is ready. Used by `accounts-ui` to hide the login button until we have all the configuration loaded
+* `logout(callback)`: logs the user out:
+    * call `connection.logout()`
+    * clear token
+    * invoke callback
+* `logoutOtherClients(callback)`: Log out other clients logged in as the current user, but does not log out the client that calls this function. **Interesting logic**  to execute two method calls without having the event loop run between them.
+* `makeClientLoggedIn()`: helper for `callLoginMethod()`
+* `makeClientLoggedOut()`: helper for `logout()` and reconnect errors
+* `onPageLoadLogin(f)`: Register a callback to be called if we have information about a login attempt at page load time.  Call the callback immediately if we already have the page load login attempt info, otherwise stash the callback to be called if and when we do get the attempt info.
+* `userId()` overrides pseudo-abstract parent method to use the per-connection user id.
+* `_pageLoadLogin(attemptInfo)`:
+* `_setLoggingIn()`: setter for `_loggingIn` (triggers reactive update)
 * `url_client.js` additions:
     * `_attemptToMatchHash()` :  Try to match the saved value of window.location.hash to one of the reserved hashes, to trigger an Accounts operation. On success, invokes passed handler which, when called from `_initUrlMatching()`, will always be `defaultSuccessHandler()`.
     * `_initUrlMatching()`: called by constructor. Inits extra data on instance and invokes `_attemptToMatchHash()`
@@ -275,13 +315,19 @@ Base class for `AccountsClient` / `AccountsServer`.
 
 * `OAuthEncryption`: if package `oauth-encryption` is present, contains its `encryption` export. Used by OAuth-related functions in this package.
 
-## Exported Objects (`globals_(client|server).js`)
+## Exported Objects (`(accounts|globals)_(client|server).js`)
 
 * `Accounts`
    * on client: `new AccountsClient()` (extends `AccountsCommon`)
    * on server: `new AccountsServer(Meteor.server)` (extends `AccountsCommon`)
 * `Meteor`
    * new field `users` for the `users` collection. Name is expected to become configurable in future versions.
+   * on client: `Meteor.loggingIn()` is an alias for `Accounts.loggingIn()`.
+   * on client: `Meteor.logout()` is an alias for `AccountsClient.logout()`.
+   * on client: `Meteor.logoutOtherClients()` is an alias for `AccountsClient.logoutOtherClients()`.
+* Template helpers (with Blaze / Spacebars only):
+  * `currentUser` -> `Meteor.user()`.
+  * `loggingIn` -> `Meteor.loggingIn()`.
 
 ## Side-effects