@qikdev/sdk 1.0.12 → 1.0.13

package/src/api/qik.api.js

@@ -5,13 +5,26 @@ import { version } from "../version.js";
 
 
 /**
- * Creates a new instance of Axios, with automatic authentication and token refreshing functionality.
- * This module provides all the underlying functions for making http requests and interacting with the REST API.
- * It is a wrapper around the axios library, a popular promise based javascript request package. The api module is used by most other modules in the SDK and will handle authentication, token refreshing and other headers automatically.
+ * The HTTP client for the Qik REST API: an axios instance whose base URL is the API, so paths are relative
+ * ('/content/profile/list'). Every request automatically carries the current access token (refreshed
+ * first when it's about to expire), the caller's timezone and the SDK version. Responses are axios
+ * responses, so the body is in `.data`; errors are axios errors (the server's message is in
+ * err.response.data.message, or use sdk.utils.errorMessage(err)).
+ * Use the standard axios methods: get(url, config), delete(url, config), post(url, body, config),
+ * put(url, body, config), patch(url, body, config). Query string values go in config.params (arrays are
+ * sent as repeated keys: ?select=a&select=b). A request body for DELETE goes in config.data.
+ * Rate-limited requests (429) are retried up to 3 times honouring Retry-After, and 502/504 responses are retried.
+ * Identical requests made at the same time share one network call.
+ * Extra config options the SDK understands: `bypassInterceptor: true` skips the automatic token refresh
+ * (the current token is still sent); add `withoutToken: true` as well to send no access token or Qik headers at all.
  * @alias api
  * @constructor
  * @hideconstructor
- * @param {QikAPI} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
+ * @param {QikCore} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
+ * @example
+ * const { data } = await sdk.api.get('/user');
+ * const { data: result } = await sdk.api.post('/content/profile/list', { select: ['firstName'], page: { size: 10 } });
+ * const { data: partial } = await sdk.api.get('/content/61eca4746971e75c1fc670cd', { params: { select: ['title', 'meta.created'] } });
  */
 
 const CancelToken = axios.CancelToken;
@@ -121,25 +134,19 @@ var QikAPI = function (qik) {
   //////////////////////////////////////////////////////////////////////////////
 
   /**
-   *
-   * Generate an Endpoint URL, complete with authentication.
-   * this function is helpful for generating authenticated links for the user to open in another window
+   * Builds a full URL for an API endpoint, with the current access token added as ?access_token=, for
+   * links the browser opens by itself (a download link, an <img> src, a new window) where no
+   * Authorization header can be sent. The token in the URL grants the user's access, so don't share or log these URLs.
    * @alias api.generateEndpointURL
-   * @param  {String} endpoint The endpoint to generate a url for
-   * @param  {Object} params Extra parameters for the url
-   * @param  {Object} options Additional request configuration
-   * @param  {Object} options.withoutToken Don't append the current user's access token to the url
-   * @param  {Object} options.file Whether the response for this request is expected to be a binary file type
+   * @param {String} endpoint The path, starting with a slash, e.g. '/image/61eca4746971e75c1fc670cf'.
+   * @param {Object} [params] Query string values. Values that are undefined, null, false, 0 or '' are left out; arrays become repeated keys.
+   * @param {Object} [options] Options.
+   * @param {Boolean} [options.withoutToken] Don't add the access token.
+   * @param {Boolean} [options.file] Build the URL on the file host (sdk.fileAPI) when one is configured, instead of the API URL.
+   * @returns {String} The URL, e.g. 'https://api.qik.dev/image/61eca...?access_token=XXXX&w=100&h=50'.
    * @example
-   *
-   *
-   * const result = sdk.api.generateEndpointURL('/image/61eca4746971e75c1fc670cf', {
-   *     w:100,
-   *     h:50,
-   *     }, {file:true})
-   *
-   * // Would return something similar to:
-   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?w=100&h=50&access_token=XXXX...
+   * const url = sdk.api.generateEndpointURL('/image/61eca4746971e75c1fc670cf', { w: 100, h: 50 }, { file: true });
+   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?access_token=XXXX&w=100&h=50
    */
   service.generateEndpointURL = function (endpoint, params, options) {
     options = options || {};
@@ -172,6 +179,19 @@ var QikAPI = function (qik) {
 
   //////////////////////////////////////////////////////////////////////////////
 
+  /**
+   * Tells whether a request error came from cancelling the request (for example a cancellable content.list),
+   * so you can ignore it instead of showing an error.
+   * @alias api.wasCancelled
+   * @param {Error} err The error a request rejected with.
+   * @returns {Boolean} True when the request was cancelled.
+   * @example
+   * try {
+   *     await request.promise;
+   * } catch (err) {
+   *     if (!sdk.api.wasCancelled(err)) throw err;
+   * }
+   */
   service.wasCancelled = function (err) {
     return axios.isCancel(err);
   };
@@ -343,16 +363,23 @@ var QikAPI = function (qik) {
   ///////////////////////////////////////
 
   /**
-   *
-   * Reference to the underlying axios package (https://www.npmjs.com/package/axios)
-   * Useful for creating new instances of axios if you want to create http requests to
-   * external APIs and not send tokens etc..
-   * @name api.axios
+   * The axios CancelToken class, for cancelling an in-flight request: create a source, pass
+   * source.token as the request's cancelToken, and call source.cancel() to abort it.
+   * @alias api.CancelToken
    * @example
-   * const newRequest = await sdk.api.axios.get('https://otherapi.com/content/61eca4746971e75c1fc670cf');
+   * const source = sdk.api.CancelToken.source();
+   * const request = sdk.api.get('/user', { cancelToken: source.token });
+   * source.cancel('No longer needed');
    */
-
   service.CancelToken = CancelToken;
+
+  /**
+   * The plain axios library (https://www.npmjs.com/package/axios), for requests to other services:
+   * requests made with it carry no Qik token or headers and don't use the API base URL.
+   * @alias api.axios
+   * @example
+   * const { data } = await sdk.api.axios.get('https://example.com/feed.json');
+   */
   service.axios = axios;
 
   ///////////////////////////////////////

package/src/api/qik.auth.js

@@ -4,12 +4,23 @@ import { createStorageAdapter } from './qik.storage.js';
 ///////////////////////////////////////////////////
 
 /**
- * Creates a new instance of QikAuth a module of the SDK
- * that contains all helper functions to do with authentication and user session management
+ * Signing in and out and the current session. The SDK keeps the session in memory (or, with
+ * useHttpOnlyCookies, lets the browser hold the tokens in httpOnly cookies) and attaches its access token to
+ * every sdk.api request, refreshing it shortly before it expires. A 401 response signs the user out.
+ * The session object returned by getCurrentUser() is { session, token }: `session` describes the signed-in
+ * user in the current organisation (_id, firstName, lastName, email, userType, organisation, persona,
+ * profiles, permissions, cacheKey...) and is what the sdk.access helpers expect; `token` is
+ * { accessToken, refreshToken, expires } (absent in cookie mode).
+ * Listen for 'change' with sdk.auth.addEventListener('change', handler): the handler gets the new stored
+ * value (or null after sign-out) and, as a second argument, any parameters passed to sdk.auth.set().
  * @alias auth
  * @constructor
  * @hideconstructor
- * @param {QikAPI} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
+ * @param {QikCore} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
+ * @example
+ * sdk.auth.addEventListener('change', (user) => {
+ *     console.log(user ? `Signed in as ${user.session.firstName}` : 'Signed out');
+ * });
  */
 
 var QikAuth = function(qik) {
@@ -59,10 +70,11 @@ var QikAuth = function(qik) {
 
         //Dispatch the change to the listeners
         if (service.onChange) {
-            service.onChange(user);
+            service.onChange(user, parameters);
         }
 
-        //Dispatch the change event
+        //Dispatch the change event: listeners get the user first and any
+        //parameters passed to set() second
         dispatcher.dispatch('change', user, parameters);
     }
 
@@ -70,15 +82,17 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Stores a session as the current one (replacing any other) and fires 'change', unless it's identical
+     * to the session already stored. Use it with a session returned by a call made with
+     * { disableAutoAuthentication: true }.
      * @alias auth.set
-     * @description Manually set current user session
-     * @param  {Object} user The user session object to set as the current user session
-     * @param  {Object} parameters Additional parameters to dispatch
-     * @param  {Boolean} stopDispatch Whether to supress dispatching a 'change' event.
+     * @param {Object|null} user The { session, token } object to store, as returned by login, changeOrganisation or impersonate. null clears it.
+     * @param {Object} [parameters] Extra details for 'change' listeners, passed to them as their second argument (the user is the first).
+     * @param {Boolean} [stopDispatch] Store the session without firing 'change'.
+     * @returns {undefined}
      * @example
-     * 
-     * const userSession = {_id:'61eca4746971e75c1fc670cf', firstName:'Daffy', lastName:'Duck' ...};
-     * sdk.auth.set(userSession);
+     * const { data } = await sdk.auth.login(credentials, { disableAutoAuthentication: true });
+     * sdk.auth.set(data);
      */
 
     service.set = function(user, parameters, stopDispatch) {
@@ -97,8 +111,10 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Signs out locally: forgets the current session, clears every SDK cache (sdk.cache.reset()) and fires
+     * 'change' with null. No request is sent to the server.
      * @alias auth.logout
-     * @description Clear the current user session from memory and erase all caches
+     * @returns {undefined}
      * @example
      * sdk.auth.logout();
      */
@@ -112,21 +128,19 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Switches the signed-in user into another organisation they belong to (POST /user/switch/:organisationID).
+     * By default the new session replaces the current one, SDK caches are cleared and 'change' fires; an open
+     * socket reconnects under the new organisation.
      * @alias auth.changeOrganisation
-     * @description Manually set current user session
-     * @param  {(String|Object)} organisation The id of the organisation to switch into
-     * @param  {Object} options Additional options
-     * @param  {Boolean} options.disableAutoAuthentication By default when switching organisation, the current user session
-     * will be updated to reflect a session in the new organisation, you can use this option to disable that behavior and instead return the 
-     * user session without dispatching any events
+     * @param {String|Object} organisationID The organisation's id, or an object with an _id.
+     * @param {Object} [options] Options.
+     * @param {Boolean} [options.disableAutoAuthentication] Only return the new session; don't store it, clear caches or fire 'change'.
+     * @returns {Promise<Object>} The new { session, token } for that organisation.
      * @example
+     * await sdk.auth.changeOrganisation('61eca4746971e75c1fc670cf');
      *
-     * sdk.auth.changeOrganisation('61eca4746971e75c1fc670cf');
-     * // Current user session will be automatically updated
-     *
-     * const newSession = await sdk.auth.changeOrganisation('61eca4746971e75c1fc670cf', {disableAutoAuthentication:true});
-     * // Current user session will not be updated
-     * sdk.auth.set(newSession);
+     * // Get the session without switching to it
+     * const newSession = await sdk.auth.changeOrganisation('61eca4746971e75c1fc670cf', { disableAutoAuthentication: true });
      */
     service.changeOrganisation = function(organisationID, options) {
 
@@ -171,21 +185,18 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Starts a session as another person (persona) in the organisation, for administrators checking what
+     * someone else sees (POST /user/impersonate with { persona, application } in the body).
+     * On success the new session replaces the current one and caches are cleared.
      * @alias auth.impersonate
-     * @description Impersonate another user within your organisation
-     * @param  {(String|Object)} persona The id of the user persona you want to impersonate
-     * @param  {Object} options Additional options
-     * @param  {Boolean} options.disableAutoAuthentication By default when impersonating a user, the current user session
-     * will be updated automatically to reflect the new session, you can use this option to disable that behavior and instead return the 
-     * new impersonation user session without dispatching any events
+     * @param {String|Object} personaID The persona's id, or an object with an _id.
+     * @param {Object} [options] Options.
+     * @param {String|Object} [options.application] An application id (or object with an _id), to impersonate the persona as an app user of that application.
+     * @param {Boolean} [options.disableAutoAuthentication] Only return the response; don't store the new session or clear caches.
+     * @returns {Promise<Object>} The axios response; its `data` is the impersonation { session, token }.
      * @example
-     *
-     * sdk.auth.impersonate('61eca4746971e75c1fc670cf');
-     * // Current user session will be automatically updated
-     *
-     * const newSession = await sdk.auth.impersonate('61eca4746971e75c1fc670cf', {disableAutoAuthentication:true});
-     * // Current user session will not be updated
-     * sdk.auth.set(newSession);
+     * await sdk.auth.impersonate('61eca4746971e75c1fc670cf');
+     * console.log(sdk.auth.getCurrentUser().session.firstName);
      */
     service.impersonate = function(personaID, options) {
 
@@ -209,7 +220,13 @@ var QikAuth = function(qik) {
 
         //////////////////////////
 
-        var promise = qik.api.post(`/user/impersonate/${personaID}`)
+        // The server reads the persona (and optional application) from the body
+        var body = { persona: personaID };
+        if (options.application) {
+            body.application = qik.utils.id(options.application);
+        }
+
+        var promise = qik.api.post(`/user/impersonate`, body)
 
         promise.then(function(res) {
 
@@ -227,30 +244,34 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Signs in with an email and password (POST /user/login). When a one-time code is required (always for
+     * dashboard users; for app users when the application or the person requires it) the first call, without `mfa`,
+     * emails a code and returns { mfa: true, type: 'email', to, expires } instead of a session; call again with
+     * the same credentials plus the code in `mfa` to get the session.
+     * With an `application` id (or when running on an application's domain) the person signs in to that
+     * application's organisation as an app user; otherwise as a dashboard user.
+     * By default a returned session is stored as the current one and 'change' fires; the code-required
+     * response is only returned, not stored.
+     * With useHttpOnlyCookies the tokens are set as httpOnly cookies instead of being returned for storage.
      * @alias auth.login
-     * @description Login and authenticate as a user
-     * @param  {Object} credentials The credentials used to login
-     * @param  {String} credentials.email The email address to login to
-     * @param  {String} credentials.password The password to login with
-     * @param  {String} credentials.mfa The MFA (Multi Factor Authentication) code
-     * @param  {Object} options Additional options
-     * @param  {Boolean} options.disableAutoAuthentication By default when logging in the current user session
-     * will be updated automatically to reflect the new session, you can use this option to disable that behavior and instead return the 
-     * session that was logged in to without dispatching any events
+     * @param {Object} credentials The sign-in details.
+     * @param {String} credentials.email The email address.
+     * @param {String} credentials.password The password.
+     * @param {String} [credentials.mfa] The one-time code from the email, on the second call.
+     * @param {String} [credentials.application] Application id, to sign in to an application's organisation as an app user.
+     * @param {String} [credentials.organisation] Organisation id to sign in to (dashboard users who belong to several).
+     * @param {Object} [options] Options.
+     * @param {Boolean} [options.disableAutoAuthentication] Only return the response; don't store the session or fire 'change'.
+     * @param {String} [options.url] Post to this URL instead of the API's /user/login.
+     * @returns {Promise<Object>} The axios response. Its `data` is either the code request { mfa: true, type, to, expires } or the session { session, token }. Rejects with { message } when email or password is missing, or with the server error (400 for wrong credentials or code).
      * @example
-     *
-     * const credentials = {
-     *     email:'me@email.com', 
-     *     password:'******',
-     *     mfa:'1234',
+     * const credentials = { email: 'me@example.com', password: '******' };
+     * let { data } = await sdk.auth.login(credentials);
+     * if (data.mfa) {
+     *     // ask for the code emailed to data.to, then:
+     *     ({ data } = await sdk.auth.login({ ...credentials, mfa: '123456' }));
      * }
-     * 
-     * sdk.auth.login(credentials);
-     * // Current user session will be automatically updated
-     *
-     * const newSession = await sdk.auth.login(credentials, {disableAutoAuthentication:true});
-     * // Current user session will not be updated
-     * sdk.auth.set(newSession);
+     * console.log(data.session.firstName);
      */
     service.login = async function(credentials, options) {
 
@@ -321,7 +342,9 @@ var QikAuth = function(qik) {
 
             qik.api.post(url, credentials, postOptions).then(function(res) {
 
-                if (autoAuthenticate) {
+                // A { mfa: true } response asks for a one-time code; it isn't a session,
+                // so only store real sessions
+                if (autoAuthenticate && !(res.data && res.data.mfa)) {
                     service.set(res.data);
                 }
 
@@ -337,6 +360,33 @@ var QikAuth = function(qik) {
 
     ///////////////////////////////////////////////////
 
+    /**
+     * Creates a new account (POST /user/signup). Checks locally that firstName, lastName, email, password and
+     * a matching confirmPassword were given. If the email already has an account and the password matches, the
+     * person is signed in instead. With an `application` id in the credentials the account is created as an app
+     * user in that application's organisation. By default the returned session is stored and 'change' fires.
+     * @alias auth.signup
+     * @param {Object} credentials The new account's details.
+     * @param {String} credentials.firstName First name.
+     * @param {String} credentials.lastName Last name.
+     * @param {String} credentials.email Email address.
+     * @param {String} credentials.password Password.
+     * @param {String} credentials.confirmPassword Must equal password.
+     * @param {String} [credentials.application] Application id, to sign up to an application's organisation as an app user.
+     * @param {Object} [options] Options.
+     * @param {Boolean} [options.disableAutoAuthentication] Only return the response; don't store the session or fire 'change'.
+     * @param {Boolean} [options.application] Post to the current site's /qik/application/signup route (sdk.domain) instead of the API.
+     * @param {String} [options.url] Post to this URL instead.
+     * @returns {Promise<Object>} The axios response; its `data` is the new { session, token }. Rejects with { message } when a detail is missing or the passwords differ.
+     * @example
+     * const { data } = await sdk.auth.signup({
+     *     firstName: 'Mickey',
+     *     lastName: 'Mouse',
+     *     email: 'mickey@example.com',
+     *     password: '******',
+     *     confirmPassword: '******',
+     * });
+     */
     service.signup = async function(credentials, options) {
 
         if (!options) {
@@ -457,18 +507,16 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Looks up who a password reset token belongs to (GET /user/reset/:token), e.g. to greet them on the
+     * reset page. Reset tokens are short-lived and come from the link in a reset email.
      * @alias auth.retrieveUserFromResetToken
-     * @description Retrieve user session through use of a valid reset token, 
-     * Reset tokens are short lived tokens that can be generated when a user has forgotten their password or their
-     * password has been reset by an administrator
-     * @param  {String} resetToken The token to use to authenticate
-     * @param  {Object} options Additional options for the request
+     * @param {String} resetToken The token from the reset link.
+     * @param {Object} [options] Options.
+     * @param {String} [options.url] Request this URL instead.
+     * @returns {Promise<Object>} For a dashboard user { _id, firstName, lastName, email }; for an app user the persona { _id, firstName, lastName, username, application: { title, primaryDomain } }. Rejects with 400 when the token is used up or expired.
      * @example
-     *
-     * const resetToken = 'XXX-324623-$$...';
-     *
-     * // Retrieve the user session by providing a reset token
-     * const user = await sdk.auth.retrieveUserFromResetToken(resetToken);
+     * const person = await sdk.auth.retrieveUserFromResetToken(token);
+     * console.log(`Choose a new password, ${person.firstName}`);
      */
     service.retrieveUserFromResetToken = async function(resetToken, options) {
 
@@ -491,20 +539,19 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Sets a new password (and optionally name) using a reset token (POST /user/reset/:token). The token
+     * works once. For a dashboard user the response is a new session, which by default is stored, caches are
+     * cleared and 'change' fires; for an app user the response is { done: true } (sign in afterwards) — note the
+     * SDK currently stores that as the session too unless disableAutoAuthentication is set.
      * @alias auth.updateUserWithToken
-     * @description Update a user's credentials through use of a reset token
-     * @param  {String} resetToken The token to use to authenticate
-     * @param  {Object} body Updates to be made to the user
-     * @param  {Object} options Additional options for the request
-     * @param  {Boolean} options.disableAutoAuthentication By default the current user session
-     * will be updated automatically to reflect the new updated session, you can use this option to disable that behavior 
-     * and instead return the result without dispatching any events
+     * @param {String} resetToken The token from the reset link.
+     * @param {Object} body The changes: { password, firstName, lastName }, plus email (dashboard users) or username (app users).
+     * @param {Object} [options] Options.
+     * @param {Boolean} [options.disableAutoAuthentication] Only return the result; don't store it or fire 'change'.
+     * @param {String} [options.url] Post to this URL instead.
+     * @returns {Promise<Object>} A new { session, token } for a dashboard user, or { done: true } for an app user.
      * @example
-     *
-     * const resetToken = 'XXX-324623-$$...';
-     *
-     * // Retrieve the user session by providing a reset token
-     * const user = await sdk.auth.retrieveUserFromResetToken(resetToken);
+     * await sdk.auth.updateUserWithToken(token, { password: 'a new password' });
      */
     service.updateUserWithToken = async function(resetToken, body, options) {
 
@@ -547,17 +594,16 @@ var QikAuth = function(qik) {
     }
 
     /**
+     * Emails the person a password reset link (POST /user/forgot). On an application's domain (or with an
+     * application in the details) the link is for that application's app users.
      * @alias auth.sendResetPasswordRequest
-     * @description This function allows a reset token to be generated and emailed to the requesting user
-     * allowing them to modify their user details
-     * @param  {Object} body Details for the reset request
-     * @param  {String} body.email The email of the user to generate a token for
+     * @param {Object} details The request.
+     * @param {String} details.email The account's email address.
+     * @param {Object} [options] Options.
+     * @param {String} [options.url] Post to this URL instead.
+     * @returns {Promise<Object>} The axios response; for dashboard users its `data` is { done: true }. Rejects with { message } when no email is given.
      * @example
-     *
-     * const resetToken = 'XXX-324623-$$...';
-     *
-     * // Retrieve the user session by providing a reset token
-     * const user = await sdk.auth.retrieveUserFromResetToken(resetToken);
+     * await sdk.auth.sendResetPasswordRequest({ email: 'me@example.com' });
      */
     service.sendResetPasswordRequest = function(details, options) {
 
@@ -591,17 +637,15 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Makes sure the current access token is still valid, refreshing it (POST /user/refresh) when it expires
+     * within the next few seconds. Requests through sdk.api already do this automatically; call it before handing
+     * the token to something else, such as a URL or another library.
      * @alias auth.ensureValidToken
-     * @description This function forces a check to ensure that the current access token has not expired.
-     * If the token has expired, the user session will be refreshed with a new token.
-     * @param  {Boolean} forceRefresh Whether to force the current token to be refreshed, even if it has not yet expired.
+     * @param {Boolean} [forceRefresh] Refresh even if the token hasn't expired yet.
+     * @returns {Promise<Object|String>} The current token object { accessToken, refreshToken, expires } when it is still valid, or the new access token string after a refresh. In cookie mode, a placeholder string. Rejects when nobody is signed in.
      * @example
-     *
-     * // Check to ensure that the current access token is valid
-     * sdk.auth.ensureValidToken();
-     *
-     * // Force the token to be refreshed, even if the current token in use has not yet expired.
-     * sdk.auth.ensureValidToken(true);
+     * await sdk.auth.ensureValidToken();
+     * const url = `${sdk.apiURL}/file/${fileID}?access_token=${sdk.auth.getCurrentToken()}`;
      */
     service.ensureValidToken = async function(forceRefresh) {
 
@@ -656,6 +700,16 @@ var QikAuth = function(qik) {
 
     const refreshContext = {};
 
+    /**
+     * Exchanges the refresh token for a new access token (POST /user/refresh), stores the refreshed session
+     * and fires 'change'. Calls made while a refresh is already running share it. Usually you want
+     * ensureValidToken() instead, which only refreshes when needed.
+     * @alias auth.refreshAccessToken
+     * @param {String} [refreshToken] The refresh token (getCurrentUser().token.refreshToken). Not needed in cookie mode.
+     * @returns {Promise<String>} The new access token (in cookie mode, the string 'cookie_token_refreshed').
+     * @example
+     * const accessToken = await sdk.auth.refreshAccessToken(sdk.auth.getCurrentUser().token.refreshToken);
+     */
     service.refreshAccessToken = async function(refreshToken) {
 
         //If there is already a request in progress
@@ -739,14 +793,21 @@ var QikAuth = function(qik) {
     ///////////////////////////////////////////////////
 
     /**
+     * Re-reads the current session from the server (GET /user) and stores it, e.g. after the user's
+     * permissions or profile changed. If the request fails the session is cleared (signed out), unless
+     * options.keepOnError is set, in which case the signed-in user is left exactly as it was.
+     * Fires 'change' when done.
      * @alias auth.sync
-     * @description A useful function to sync the current user session with the server.
+     * @param {Object} [options]
+     * @param {Boolean} [options.keepOnError] Keep the current user if the request fails (e.g. a network
+     * blip) instead of signing out. The socket uses this when told the person's access changed.
+     * @returns {Promise<undefined>} Resolves when the stored session has been updated.
      * @example
-     *
-     * // Makes request to the API and updates the current user session to match the response
-     * sdk.auth.sync();
+     * await sdk.auth.sync();
+     * const { session } = sdk.auth.getCurrentUser();
      */
-    service.sync = function() {
+    service.sync = function(options) {
+        options = options || {};
 
         return qik.api.get('/user')
             .then(function(res) {
@@ -771,6 +832,9 @@ var QikAuth = function(qik) {
                 dispatch();
             })
             .catch(function(err) {
+                if (options.keepOnError) {
+                    return;
+                }
                 service.set(null);
                 dispatch();
             });
@@ -779,11 +843,15 @@ var QikAuth = function(qik) {
     /////////////////////////////////////////////////////
 
     /**
+     * Returns the stored session straight away (no request).
      * @alias auth.getCurrentUser
-     * @description Retrieves the current user session
+     * @returns {Object|null} { session, token } when signed in, otherwise null. Pass `session` to the sdk.access helpers.
      * @example
-     *
-     * const me = sdk.auth.getCurrentUser();
+     * const current = sdk.auth.getCurrentUser();
+     * if (current) {
+     *     const { session } = current;
+     *     console.log(session.firstName, session.organisation.title);
+     * }
      */
     service.getCurrentUser = function() {
         return storageAdapter.getUser();
@@ -791,12 +859,12 @@ var QikAuth = function(qik) {
 
 
     /**
+     * Returns the access token requests are sent with: the signed-in user's token, or when nobody is signed in
+     * the application token the SDK was created with. Doesn't check expiry (see ensureValidToken).
      * @alias auth.getCurrentToken
-     * @description Retrieves the current access token. If the user is authenticated
-     * the response will be the current user's access token, otherwise will fall back to the 
-     * applications token.
+     * @returns {String|undefined} The access token, or undefined when there is none. In cookie mode a signed-in user's token can't be read, so this is undefined for them.
      * @example
-     * const currentAccessToken = sdk.auth.getCurrentToken();
+     * const token = sdk.auth.getCurrentToken();
      */
     service.getCurrentToken = function() {