@qikdev/sdk 1.0.12 → 1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qikdev/sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "type": "module",
   "description": "Promise based Javascript SDK",
   "main": "./dist/main.js",

package/src/api/qik.access.js

@@ -1,11 +1,20 @@
 /**
- * Creates a new Access Module instance.
- * This module provides a number of helper functions for managing and understanding permissions of the current
- * application or user
+ * Permission and feature checks worked out locally from the signed-in user's session (no requests).
+ * Use them to decide what to show, e.g. whether to offer an Edit button; the server still checks every
+ * request itself, so these never grant access. Every check takes the session object
+ * (const { session } = sdk.auth.getCurrentUser()), not the whole stored { session, token } object.
+ * Permissions are strings of the form '<type or definition key>.<action>', e.g. 'profile.viewany',
+ * 'article.create', 'event.editown', granted within scopes. 'any' actions apply to every record in the scope,
+ * 'own' actions only to records the user owns or is assigned to. Administrators pass every check.
  * @alias access
  * @constructor
  * @hideconstructor
  * @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 { session } = sdk.auth.getCurrentUser();
+ * if (sdk.access.canEditItem(session, record)) {
+ *     // show the edit button
+ * }
  */
 
 var QikAccess = function (QikCore) {
@@ -28,13 +37,14 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether a feature is switched on for the user's organisation (session.organisation.features).
    * @alias access.hasFeature
-   * @description Checks if a user has a specific feature enabled for their organisation
-   * @param  {Object} user The user to check
-   * @param  {String} feature The feature to check is enabled/disabled
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {String} feature The feature key, e.g. 'forms', 'sms', 'messaging'.
+   * @returns {Boolean} True when the feature is on (or the organisation has every feature).
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const formsFeatureIsEnabled =  sdk.access.hasFeature(user, 'forms');
+   * const { session } = sdk.auth.getCurrentUser();
+   * const formsEnabled = sdk.access.hasFeature(session, 'forms');
    */
   service.hasFeature = function (user, feature) {
     const features = user?.organisation?.features || {};
@@ -47,11 +57,13 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the session is an administrator's (userType 'administrator'). Administrators pass every permission check.
    * @alias access.isAdministrator
-   * @description Check if a user object is an administrator
-   * @param  {Object} user The user session to check
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @returns {Boolean} True for an administrator; a falsy value otherwise (including when no session is given).
    * @example
-   * const userIsAnAdministrator = sdk.access.isAdministrator({firstName:'Jeffrey', lastName:'Winger', ...});
+   * const { session } = sdk.auth.getCurrentUser();
+   * const isAdmin = sdk.access.isAdministrator(session);
    */
   service.isAdministrator = function (user) {
     return user && user?.userType == "administrator";
@@ -60,11 +72,13 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Collects the ids of a scope and every scope nested inside it (through `children`).
    * @alias access.getAllDescendants
-   * @description Get all children of a specified scope
-   * @param  {Object} scope A scope object with child scopes
+   * @param {Object} scope A scope with nested `children` arrays, e.g. an entry of session.permissions.
+   * @returns {Array<String>} The scope's own id followed by the ids of all its descendants, without duplicates.
    * @example
-   * const childScopes = sdk.access.getAllDescendants({title:'Global', children:[{title:'Australia', ...}, {title:'New Zealand', ...}]});
+   * const ids = sdk.access.getAllDescendants({ _id: '61eca4746971e75c1fc670cf', children: [{ _id: '61eca4746971e75c1fc670ca', children: [] }] });
+   * // ['61eca4746971e75c1fc670cf', '61eca4746971e75c1fc670ca']
    */
   service.getAllDescendants = function (scope) {
     //Start by including the scope id. A Set because the same scope can be
@@ -89,11 +103,15 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Builds a lookup of every permission the user holds and the scopes it applies in, including the scopes
+   * nested under the ones it was granted in. The result is remembered for a few seconds per session.
    * @alias access.hashPermissions
-   * @description Get a lookup of all permissions a user has been granted
-   * @param  {Object} user A user session object
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @returns {Object} An object mapping each permission string to an array of scope ids, e.g. { 'profile.viewany': ['61eca...', ...] }.
    * @example
-   * const permissions = sdk.access.hashPermissions({firstName:'Mighty', lastName:'Mouse', permissionSets:[...], ...});
+   * const { session } = sdk.auth.getCurrentUser();
+   * const lookup = sdk.access.hashPermissions(session);
+   * const scopesWhereICanCreateArticles = lookup['article.create'] || [];
    */
   // Memo for hashPermissions, keyed on the session's cacheKey.
   //
@@ -175,14 +193,14 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Lists the ids of every scope the user holds any permission in, including nested scopes.
    * @alias access.allUserScopes
-   * @description Return an array of ids of all scopes that a given user has been granted a permission in
-   * @param  {Object} user A user session object
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @returns {Array<String>} Scope ids.
    * @example
-   * const permissions = sdk.access.allUserScopes({firstName:'Mighty', lastName:'Mouse', permissionSets:[...], ...});
-   *
-   * // Would result in:
-   * ['61eca4746971e75c1fc670cf', '61eca4746971e75c1fc670ca', '77eca4746971e75c1fc670cf'],
+   * const { session } = sdk.auth.getCurrentUser();
+   * const scopeIDs = sdk.access.allUserScopes(session);
+   * // ['61eca4746971e75c1fc670cf', '61eca4746971e75c1fc670ca', ...]
    */
   service.allUserScopes = function (user) {
     var collected = {};
@@ -225,20 +243,20 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Lists the scopes in which the user may perform an action on a type of record, e.g. where they may create
+   * articles. Checks the permission for the definition key and for the base type key and combines the scopes.
+   * For administrators, every scope they hold a permission in.
    * @alias access.actionableScopes
-   * @description Return an array of all scopes that a given user can perform a specified action in
-   * @param  {Object} user A user session object
-   * @param  {String} action The action
-   * @param  {String} definition The defined type of item the action will be performed on
-   * @param  {String} type The basic type of item the action will be performed on
-   * @param  {Object} options Additional options and parameters
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {String} action The action: 'create', 'viewany', 'viewown', 'listany', 'editany', 'editown', 'deleteany', 'deleteown', 'restoreany', 'eraseany'...
+   * @param {String} [definition] The definition key, when checking a defined type (e.g. 'jobApplication'); pass null or undefined for a base type.
+   * @param {String} [type] The base type key (e.g. 'article', 'profile').
+   * @param {Object} [options] Not used; accepted for compatibility.
+   * @returns {Array<String>} Scope ids (may contain duplicates). Empty when the user can't do it anywhere, or when neither definition nor type is given.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const canCreateInScopes = sdk.access.actionableScopes(user, 'create', 'car', 'article');
-   * const canDeleteInScopes = sdk.access.actionableScopes(user, 'delete', 'profile');
-   *
-   * // Would result in something like:
-   * ['61eca4746971e75c1fc670cf', '61eca4746971e75c1fc670ca', '77eca4746971e75c1fc670cf'],
+   * const { session } = sdk.auth.getCurrentUser();
+   * const createScopes = sdk.access.actionableScopes(session, 'create', 'jobApplication', 'object');
+   * const deleteScopes = sdk.access.actionableScopes(session, 'deleteany', null, 'profile');
    */
   service.actionableScopes = function (
     user,
@@ -281,16 +299,16 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user counts as an owner of a record: they created it (meta.userAuthor / meta.personaAuthor),
+   * are listed as an owner (meta.userOwners / meta.personaOwners), or one of their profiles is in its `assignees`.
+   * Ownership is what 'own' permissions (e.g. 'article.editown') apply to.
    * @alias access.isOwner
-   * @description Return whether or not a user is considered an Owner of a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with its `meta` (and `assignees` if it has them).
+   * @returns {Boolean} True when the user owns the record.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const item = {title:'A piece of content', meta:{personaAuthor:'61eca4746971e75c1fc670ca'}, ...}
-   *
-   * // Returns true if the user owns the item
-   * const isTheOwner = sdk.access.isOwner(user, item);
+   * const { session } = sdk.auth.getCurrentUser();
+   * const mine = sdk.access.isOwner(session, { title: 'A post', meta: { personaAuthor: '61eca4746971e75c1fc670ca' } });
    */
   service.isOwner = function (user, item) {
     var userID = QikCore.utils.id(user);
@@ -332,16 +350,14 @@ var QikAccess = function (QikCore) {
   };
 
   /**
+   * Checks whether one of the user's profiles (session.profiles) is in the record's `assignees`, e.g. a workflow card assigned to them.
    * @alias access.isAssignee
-   * @description Return whether or not a user is an assignee of a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} contentItem The record, with an `assignees` array of profile ids or objects.
+   * @returns {Boolean} True when the user is an assignee.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const item = {title:'A workflow card', assignees:['61eca4746971e75c1fc670ca'], ...}
-   *
-   * // Returns true if the user owns the item
-   * const isAssignee = sdk.access.isAssignee(user, item);
+   * const { session } = sdk.auth.getCurrentUser();
+   * const assignedToMe = sdk.access.isAssignee(session, { title: 'Follow up', assignees: ['61eca4746971e75c1fc670ca'] });
    */
   service.isAssignee = function (user, contentItem) {
     // Check the user profile ids
@@ -368,15 +384,14 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Lists every permission string the user has been granted, across all scopes.
    * @alias access.allPermissions
-   * @description Returns an array of all permissions a given user has access to
-   * @param  {Object} user The user to check
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @returns {Array<String>} Permission strings (the same one can appear once per scope it was granted in); empty when no session is given.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const permissions =  sdk.access.allPermissions(user);
-   *
-   * // Returns
-   * ['image.viewany', 'testimonial.viewany', 'testimonial.viewfield.title', ...]
+   * const { session } = sdk.auth.getCurrentUser();
+   * const permissions = sdk.access.allPermissions(session);
+   * // ['image.viewany', 'testimonial.viewany', 'testimonial.viewfield.title', ...]
    */
   service.allPermissions = function (user) {
     var allPermissions = Object.values(user?.permissions || {})
@@ -391,19 +406,15 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Lists the type and definition keys the user holds at least one permission for.
    * @alias access.allPermissionTypes
-   * @description Returns an array of content types a given user has permission to interact with
-   * @param  {Object} user The user to check
-   * @param  {Boolean} asHash Whether to retrieve the result as a keyed object hash, by default
-   * the response will be an array
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Boolean} [asHash] Return an object { key: true } instead of an array.
+   * @returns {Array<String>|Object} The keys (the array can repeat keys), or an object keyed by them.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   *
-   * // Returns ['image', 'testimonial']
-   * const types = sdk.access.allPermissionTypes(user);
-   *
-   * // Returns {image:true, testimonial:true}
-   * const types = sdk.access.allPermissionTypes(user, true);
+   * const { session } = sdk.auth.getCurrentUser();
+   * const types = sdk.access.allPermissionTypes(session); // ['image', 'testimonial', ...]
+   * const lookup = sdk.access.allPermissionTypes(session, true); // { image: true, testimonial: true }
    */
   service.allPermissionTypes = function (user, asHash) {
     if (asHash) {
@@ -422,16 +433,15 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user holds any permission at all for a type or definition, e.g. to decide whether to show its menu entry.
    * @alias access.canKnowOf
-   * @description Checks if a user has any permissions relating to a specified type of content
-   * @param  {Object} user The user to check
-   * @param  {String} typeKey The type or definition to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {String} typeKey The type or definition key.
+   * @param {Object} [options] Not used; accepted for compatibility.
+   * @returns {Boolean|undefined} true when they hold a permission for it, otherwise undefined.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const canAccessImageSection =  sdk.access.canKnowOf(user, 'image');
-   * const canAccessCustomerUploadSection =  sdk.access.canKnowOf(user, 'customerUpload');
+   * const { session } = sdk.auth.getCurrentUser();
+   * const showImages = !!sdk.access.canKnowOf(session, 'image');
    */
   service.canKnowOf = function (user, typeKey, options) {
     options = options || {};
@@ -444,28 +454,21 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * The general check behind canViewItem, canEditItem and the others: may the user perform an action on a
+   * specific record? True when the user is an administrator, when they hold the 'any' action for the
+   * record's definition or type in one of the record's scopes, or when they own the record and hold the
+   * 'own' action in one of its scopes. For scope records the scope's own path is used as its scopes.
    * @alias access.checkActionAccess
-   * @description Helpful function for checking whether a given user has access to do a given action on a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {String} ANY_ACTION The 'any' action to check
-   * @param  {String} OWN_ACTION The 'owned' action to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {String} ANY_ACTION The action that applies to any record, e.g. 'editany'.
+   * @param {String} OWN_ACTION The action that applies to records the user owns, e.g. 'editown'.
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed. False when the record has no meta.type.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const canEditItem =  sdk.access.checkActionAccess(user, {_id:'61eca4746971e75c1fc670ca', meta:{...}}, 'editany', 'editown');
-   * const canViewItem =  sdk.access.checkActionAccess(user, {_id:'61eca4746971e75c1fc670ca', meta:{...}}, 'viewany', 'viewown');
-   *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
-   *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
-   *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.checkActionAccess(user, item, 'editany', 'editown', {cache});
-   * })
+   * const { session } = sdk.auth.getCurrentUser();
+   * const canEdit = sdk.access.checkActionAccess(session, record, 'editany', 'editown');
    */
   service.checkActionAccess = function (
     user,
@@ -592,13 +595,16 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user holds a specific permission in at least one scope.
    * @alias access.has
-   * @description Helpful function for checking whether a given user has a specified permission
-   * @param  {Object} user The user to check
-   * @param  {String} permission The permission the user may have been granted
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {String} permission The permission string, e.g. 'video.create' or 'profile.viewany'.
+   * @returns {Boolean|Array<String>} true for administrators; otherwise the array of scope ids the permission applies in (truthy) or undefined when it isn't held.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const isAllowedToCreateItems = sdk.access.has(user, 'video.create');
+   * const { session } = sdk.auth.getCurrentUser();
+   * if (sdk.access.has(session, 'video.create')) {
+   *     // show the upload button
+   * }
    */
   service.has = function (user, permission) {
     //Allow everything if we're a super user
@@ -613,16 +619,16 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may create records of a type in at least one scope.
    * @alias access.canCreate
-   * @description Helpful function for checking whether a given user can create a specified type of item
-   * @param  {Object} user The user to check
-   * @param  {String} definition The defined type key
-   * @param  {String} type The basic type key
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {String} [definition] The definition key when creating a defined type; null or undefined for a base type.
+   * @param {String} [type] The base type key.
+   * @param {Object} [options] Not used; accepted for compatibility.
+   * @returns {Boolean|Number} true for administrators; otherwise the number of scopes they can create in (0 = no).
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   * const userCanCreateShortFilms = sdk.access.canCreate(user, 'shortFilm', 'video');
+   * const { session } = sdk.auth.getCurrentUser();
+   * const canCreateShortFilms = !!sdk.access.canCreate(session, 'shortFilm', 'video');
    */
   service.canCreate = function (user, definition, type, options) {
     options = options || {};
@@ -645,24 +651,19 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may see a record in lists: 'listany'/'listown' permission, or anything that lets them view it. Administrators always may.
    * @alias access.canListItem
-   * @description Helpful function for checking whether a given user can list a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
+   * const { session } = sdk.auth.getCurrentUser();
    *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
-   *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.canListItem(user, item, {cache});
-   * })
+   * // Checking many items: share one cache object across the loop
+   * const cache = {};
+   * const allowed = items.filter((item) => sdk.access.canListItem(session, item, { cache }));
    */
   service.canListItem = function (user, item, options) {
     options = options || {};
@@ -693,24 +694,19 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may open a record: 'viewany' permission in one of its scopes, 'viewown' if they own it, or permission to edit it. Administrators always may.
    * @alias access.canViewItem
-   * @description Helpful function for checking whether a given user can view a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
-   *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
+   * const { session } = sdk.auth.getCurrentUser();
    *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.canViewItem(user, item, {cache});
-   * })
+   * // Checking many items: share one cache object across the loop
+   * const cache = {};
+   * const allowed = items.filter((item) => sdk.access.canViewItem(session, item, { cache }));
    */
   service.canViewItem = function (user, item, options) {
     options = options || {};
@@ -721,7 +717,7 @@ var QikAccess = function (QikCore) {
       user,
       item,
       "viewany",
-      "viewOwn",
+      "viewown",
       options,
     );
     if (canView) {
@@ -740,24 +736,19 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may edit a record: 'editany' in one of its scopes, or 'editown' if they own it. Administrators always may.
    * @alias access.canEditItem
-   * @description Helpful function for checking whether a given user can edit a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed.
    * @example
-   * const user = sdk.auth.getCurrentUser();
+   * const { session } = sdk.auth.getCurrentUser();
    *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
-   *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
-   *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.canEditItem(user, item, {cache});
-   * })
+   * // Checking many items: share one cache object across the loop
+   * const cache = {};
+   * const allowed = items.filter((item) => sdk.access.canEditItem(session, item, { cache }));
    */
   service.canEditItem = function (user, item, options) {
     options = options || {};
@@ -777,24 +768,19 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may delete (trash) a record: 'deleteany' in one of its scopes, or 'deleteown' if they own it. Administrators always may.
    * @alias access.canDeleteItem
-   * @description Helpful function for checking whether a given user can delete a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
+   * const { session } = sdk.auth.getCurrentUser();
    *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
-   *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.canDeleteItem(user, item, {cache});
-   * })
+   * // Checking many items: share one cache object across the loop
+   * const cache = {};
+   * const allowed = items.filter((item) => sdk.access.canDeleteItem(session, item, { cache }));
    */
   service.canDeleteItem = function (user, item, options) {
     options = options || {};
@@ -812,24 +798,19 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may restore a trashed record: 'restoreany' in one of its scopes, or 'restoreown' if they own it. Administrators always may.
    * @alias access.canRestoreItem
-   * @description Helpful function for checking whether a given user can restore a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
-   *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
+   * const { session } = sdk.auth.getCurrentUser();
    *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.canRestoreItem(user, item, {cache});
-   * })
+   * // Checking many items: share one cache object across the loop
+   * const cache = {};
+   * const allowed = items.filter((item) => sdk.access.canRestoreItem(session, item, { cache }));
    */
   service.canRestoreItem = function (user, item, options) {
     options = options || {};
@@ -847,24 +828,19 @@ var QikAccess = function (QikCore) {
   ///////////////////////////////////////////////
 
   /**
+   * Checks whether the user may permanently erase a record: 'eraseany' in one of its scopes, or 'eraseown' if they own it. Administrators always may.
    * @alias access.canEraseItem
-   * @description Helpful function for checking whether a given user can erase a specified item
-   * @param  {Object} user The user to check
-   * @param  {Object} item The item to check
-   * @param  {Object} options Additional options and parameters
-   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
+   * @param {Object} user The session to check: the `session` part of sdk.auth.getCurrentUser(), not the whole { session, token } object.
+   * @param {Object} item The record, with meta.type, meta.definition and meta.scopes (and owner fields).
+   * @param {Object} [options] Options.
+   * @param {Object} [options.cache] An object to reuse across calls (e.g. {} created before a loop) so repeated checks for the same type are faster.
+   * @returns {Boolean} True when allowed.
    * @example
-   * const user = sdk.auth.getCurrentUser();
-   *
-   * // Example of looping through a large array of items
-   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
-   *
-   * // Create an in memory cache object outside of the loop
-   * const cache = {}
+   * const { session } = sdk.auth.getCurrentUser();
    *
-   * const filtered = largeArrayOfItems.filter(function(item) {
-   *    return sdk.access.canEraseItem(user, item, {cache});
-   * })
+   * // Checking many items: share one cache object across the loop
+   * const cache = {};
+   * const allowed = items.filter((item) => sdk.access.canEraseItem(session, item, { cache }));
    */
   service.canEraseItem = function (user, item, options) {
     options = options || {};