@qikdev/sdk 1.0.10 → 1.0.13

package/src/api/qik.content.js

@@ -1,8 +1,10 @@
 ///////////////////////////////////////////////////
 
 /**
- * Creates a new QikContent instance.
- * This module provides a number of helper functions for creating and modifying content via the REST API
+ * Reading and writing records (content) through the REST API: list, get, create, update, patch,
+ * delete and restore, plus the glossary of content types, filter comparators and field validation helpers.
+ * Every call runs as the signed-in user (or the application token) and is subject to their permissions:
+ * records they can't see aren't returned, and fields they can't see are removed from the records that are.
  * @alias content
  * @constructor
  * @hideconstructor
@@ -26,14 +28,16 @@ export default function (qik) {
   let inflightVariablesRequest;
 
   /**
-   *
-   * Retrieves all global variables for the current user. This is often used when running custom code in an action.
+   * Retrieves the organisation's variables (stored key/value settings such as API keys) that the current user
+   * is allowed to see, as one object keyed by variable key (POST /variables, up to 1000 variables).
+   * Often used by action code to read credentials. The result is kept in memory after the first call;
+   * later calls return that copy unless `options.reload` is set.
    * @alias content.variables
-   * @param  {Array} keys Provide specific keys of variables you want to retrieve
-   * @param  {Object} options Additional options when making the request
-   * @param  {Boolean} options.reload Force variables to reload and not be cached. If false will retrieve any variables that are already known from the in memory cache.
+   * @param {Array<String>} [keys] Sent to the server, but currently ignored there: every visible variable is always returned. Pick the ones you need from the result.
+   * @param {Object} [options] Request options.
+   * @param {Boolean} [options.reload] Fetch again instead of returning the in-memory copy (`options.refresh` works too).
+   * @returns {Promise<Object>} An object mapping each variable key to its value, e.g. { OAUTH_CLIENT_ID: 'abc', OAUTH_KEY: 'xyz' }.
    * @example
-   *
    * const { OAUTH_CLIENT_ID, OAUTH_KEY } = await sdk.content.variables();
    */
 
@@ -117,22 +121,23 @@ export default function (qik) {
   }
 
   /**
-     *
-     * Retrieves the glossary of all content types visible to the requesting user.
-     By default this will include all fields, validation, expressions and other configuration
-     * @alias content.glossary
-     * @param  {Object} options Additional options
-     * @param  {Boolean} options.hash Whether to return the data as a keyed object
-     allowing for fast selection of specific content types, by default will return as an array
-     * @param  {Boolean} options.reload Force glossary to reload and not be cached.
-      If false will retrieve content type data from the in memory cache
-     * @param  {Boolean} options.uncompressed Use the uncompressed endpoint
-     * @example
-     *
-     * const { article, profile } = await sdk.content.glossary({hash:true});
-     * // Use compressed endpoint for faster loading
-     * const glossary = await sdk.content.glossary({compressed:true});
-     */
+   * Retrieves the glossary: every content type the current user can know about, built-in types and the
+   * organisation's own definitions alike, each with its key, title, plural, fields (including definedFields
+   * for definitions), validation and other configuration. Use it to find the real type key for
+   * content.list / content.create; keys can't be inferred from titles.
+   * Loaded from GET /glossary/compressed (or GET /glossary with `uncompressed`) and kept in the SDK cache
+   * until `options.reload` or sdk.cache.reset() (which logout and organisation switches call).
+   * @alias content.glossary
+   * @param {Object} [options] Options.
+   * @param {Boolean} [options.hash] Return an object keyed by type key ({ profile: {...}, article: {...} }) instead of an array.
+   * @param {Boolean} [options.hex] Return an object keyed by each type's two-character id prefix instead of an array.
+   * @param {Boolean} [options.reload] Fetch again instead of using the cached copy (`options.refresh` works too).
+   * @param {Boolean} [options.uncompressed] Load from the uncompressed endpoint. The default compressed endpoint returns the same data, smaller.
+   * @returns {Promise<Array|Object>} An array of content type definitions, or an object keyed by type key when `hash` is set (by id prefix when `hex` is set).
+   * @example
+   * const { article, profile } = await sdk.content.glossary({ hash: true });
+   * const fieldKeys = profile.fields.map((field) => field.key);
+   */
   service.glossary = async function (options) {
     options = options || {};
 
@@ -190,18 +195,17 @@ export default function (qik) {
   let inflightScopeGlossaryRequest;
 
   /**
-     *
-     * Retrieves the scope glossary of all scopes the user can know about. This helps to convert a scope id into a human readable title.
-     * @alias content.scopeGlossary
-     * @param  {Object} options Additional options
-     * @param  {Boolean} options.hash Whether to return the data as a keyed object with each scopes _id as the key
-     allowing for fast selection of specific scopes, by default will return a structured tree
-     * @param  {Boolean} options.reload Force the glossary to reload and not be cached.
-      If false will retrieve content type data from the in memory cache
-     * @example
-     *
-     * const scopes = await sdk.content.scopeGlossary();
-     */
+   * Retrieves every scope the current user holds a permission in (GET /scope/glossary), handy for turning
+   * a scope id into a readable title. The result is kept in memory after the first call.
+   * @alias content.scopeGlossary
+   * @param {Object} [options] Options.
+   * @param {Boolean} [options.hash] Return an object keyed by scope _id instead of an array.
+   * @param {Boolean} [options.reload] Fetch again instead of returning the in-memory copy (`options.refresh` works too).
+   * @returns {Promise<Array|Object>} A flat array of scopes, each { _id, title, bgColor, color, meta: { definition } }, or an object keyed by _id when `hash` is set.
+   * @example
+   * const scopes = await sdk.content.scopeGlossary({ hash: true });
+   * const scopeTitle = scopes['61eca4746971e75c1fc670cf']?.title;
+   */
 
   service.scopeGlossary = async function (options) {
     options = options || {};
@@ -234,15 +238,19 @@ export default function (qik) {
   ///////////////////////////////////////////////////
 
   /**
-   *
-   * Retrieves all available filter comparators for each data type
+   * Retrieves every filter comparator the server understands (GET /system/comparators), for building the
+   * `filter` of content.list. Each comparator has a `title`, an `operator` (the name to use as a filter's
+   * `comparator`), optional `aliases` (e.g. '>' for 'greater') and the data types it applies to.
+   * The result is kept in memory after the first call.
    * @alias content.comparators
-   * @param  {Object} options Additional options
-   * @param  {Boolean} options.reload Ignore any locally cached data
+   * @param {Object} [options] Options.
+   * @param {Boolean} [options.reload] Fetch again instead of returning the in-memory copy (`options.refresh` works too).
+   * @returns {Promise<Object>} { hash, types, available }: `hash` maps each operator name and alias to its comparator; `types` maps each data type (string, number, date, boolean, reference...) to the operator names that apply to it; `available` maps each data type to the comparator objects themselves.
    * @example
-   * const {hash, available, types} = await sdk.content.comparators();
-   * console.log(available) // {boolean:[{title:'Is equal to', operator:'equal'...}]}
-   * console.log(hash) // {equal:[{title:'Is equal to', operator:'equal'...}]}
+   * const { hash, available, types } = await sdk.content.comparators();
+   * console.log(types.date); // includes 'datebefore', 'dateafter', 'datebetween' ...
+   * console.log(available.boolean[0]); // { title: 'Is equal to', operator: 'equal', ... }
+   * console.log(hash['>'].operator); // 'greater'
    */
 
   const comparators = {};
@@ -295,6 +303,22 @@ export default function (qik) {
     return { minimum, maximum };
   }
 
+  /**
+   * Checks a single value against a field's extra length and range rules. Used by validateField; it does
+   * not check the data type or how many values a field needs.
+   * @alias content.meetsValidationRequirements
+   * @param {*} input The value to check.
+   * @param {String} fieldType The field's data type (currently not used by the check).
+   * @param {Object} validationCriteria The rules to apply. Each is skipped when missing or 0.
+   * @param {Number} [validationCriteria.minLength] Minimum number of characters.
+   * @param {Number} [validationCriteria.maxLength] Maximum number of characters.
+   * @param {Number} [validationCriteria.minValue] Smallest number allowed.
+   * @param {Number} [validationCriteria.maxValue] Largest number allowed.
+   * @returns {String|undefined} A message describing the first rule the value breaks, or undefined when it passes.
+   * @example
+   * sdk.content.meetsValidationRequirements('Jo', 'string', { minLength: 3 });
+   * // 'Must be at least 3 characters'
+   */
   service.meetsValidationRequirements = function (
     input,
     fieldType,
@@ -334,19 +358,25 @@ export default function (qik) {
   };
 
   /**
-   * Checks if a certain input validates against a field definition
+   * Checks a value against a field definition the way forms do before submitting: required (minimum),
+   * how many values are allowed (maximum, 0 = unlimited; a field with maximum other than 1 expects an array),
+   * the data type, and minLength / maxLength / minValue / maxValue rules. Runs locally, no request is made.
+   * A required boolean field only passes when the value is true.
    * @alias content.validateField
-   * @param  {Any} input The input to validate
-   * @param  {Object} fieldDefinition The field to validate against
-   * @param  {Object} options Additional options when calling the function
+   * @param {*} input The value to check (an array for multi-value fields).
+   * @param {Object} fieldDefinition The field from a definition or glossary entry: { title, key, type, minimum, maximum, minLength, maxLength, minValue, maxValue, validation, widget, asObject }.
+   * @param {Object} [options] Options.
+   * @param {Boolean} [options.strict] Require values to already be the right JavaScript type (e.g. a real number or Date) instead of accepting values that can be converted.
+   * @returns {Object} { valid: true } when the value passes, otherwise { valid: false, status: 400, message } with a readable message.
    * @example
-   * const validationResult = await sdk.content.validateField('Johnny Bobbins', {title:'Name', key:'firstName', type:'string', minimum:1, maximum:1, ...});
-   * console.log(validationResult)
-   * // Results in { valid:true }
+   * sdk.content.validateField('Johnny', { title: 'Name', key: 'firstName', type: 'string', minimum: 1, maximum: 1 });
+   * // { valid: true }
    *
-   * const validationResult = await sdk.content.validateField('Johnny Bobbins', {title:'Number', key:'number', type:'integer', minimum:1, maximum:1, ...});
-   * console.log(validationResult)
-   * // Results in { valid:false, status:400, message:'Invalid number input for field' }
+   * sdk.content.validateField('Johnny', { title: 'Number', key: 'number', type: 'integer', minimum: 1, maximum: 1 });
+   * // { valid: false, status: 400, message: "Single value 'Johnny' is not a valid integer for Number", criteria: {...} }
+   *
+   * sdk.content.validateField(undefined, { title: 'Email', key: 'email', type: 'email', minimum: 1, maximum: 1 });
+   * // { valid: false, status: 400, message: 'Email is a required field' }
    */
 
   service.validateField = function (input, fieldDefinition, options) {
@@ -615,7 +645,24 @@ export default function (qik) {
     };
   };
 
+  /**
+   * Converts a raw value to a data type the way validateField does before checking it: numbers are parsed,
+   * booleans read from 'yes' / 'true' / '1' style strings, emails lowercased, references reduced to an id,
+   * dates parsed. Runs locally.
+   * @alias content.getCleanedValue
+   * @param {*} input The raw value.
+   * @param {String} dataType The data type: 'number' | 'decimal' | 'float' | 'integer' | 'boolean' | 'email' | 'reference' | 'date' | 'url' | 'key' | 'string' | 'object' ...
+   * @param {Object} [options] Options.
+   * @param {Boolean} [options.strict] Return the value unchanged (numbers, integers and booleans are still converted).
+   * @returns {*} The converted value. Missing or unconvertible values come back as undefined (false for a url that can't be parsed).
+   * @example
+   * sdk.content.getCleanedValue('42', 'integer', {}); // 42
+   * sdk.content.getCleanedValue('Yes', 'boolean', {}); // true
+   * sdk.content.getCleanedValue('Hi@Example.COM', 'email', {}); // 'hi@example.com'
+   */
   service.getCleanedValue = function (input, dataType, options) {
+    options = options || {};
+
     switch (dataType) {
       case "number":
       case "float":
@@ -658,43 +705,67 @@ export default function (qik) {
   ///////////////////////////////////////////////////
 
   /**
+   * Lists the records of one content type that match a query (POST /content/:type/list). This is the way to
+   * read many records at once: filter, search, sort and page on the server, and ask for exactly the fields you need.
    *
-   * Retrieves a list of records matching the provided criteria
+   * ALWAYS pass `select` listing the fields you want. Without it each row contains only `_id` and `title`,
+   * and reading anything else would mean fetching every record again with content.get.
+   * Rows are filtered by the viewer's field permissions: a selected field the viewer isn't allowed to see is
+   * simply left out of the row (no error), and records they can't see aren't returned at all.
+   * By default only active, non-deleted records are listed.
    * @alias content.list
-   * @param  {String} type The type or definition of records we want to retrieve
-   * @param  {Object} options The options for our query
-   * @param  {String} options.search Freeform text keywords
-   * @param  {Object} options.sort How to sort the results
-   * @param  {String} options.sort.key Which key to sort on
-   * @param  {String} options.sort.direction Which direction to sort on
-   * @param  {Object} options.sort.type What type of data is being sorted
-   * @param  {Object} options.page Page configuration
-   * @param  {Number} options.page.size Page size
-   * @param  {Number} options.page.index Page index
-   * @param  {Object} options.filter How to filter the results
+   * @param {String} type The type key or definition key to list, e.g. 'profile', 'event', or an organisation's own definition key. Look keys up with content.glossary(); they can't be inferred from titles.
+   * @param {Object} [options] The query. Every property is optional.
+   * @param {Array<String>} [options.select] Fields to include on each row, as dot paths: 'firstName', 'data.shirtSize', 'meta.created', 'meta.scopes'. Must be an array (a string is rejected with a 400). A parent key returns everything under it ('data' returns all custom fields). `_id` is always included. Reference fields named here come back populated with the referenced records. Computed keys are accepted too: '_age' and '_dob' on profiles, and 'join_...' keys for related data. Without select, rows contain only `_id` and `title`.
+   * @param {String} [options.search] Keywords. Matches whole words and the start of words (not the middle of words) in the record's indexed terms such as names, titles, emails and phone numbers. On profiles every word must match; on other types a record also matches when any one word matches a whole term. A 24-character record id finds that record.
+   * @param {Object} [options.filter] A filter group: { operator, filters }. `operator` is 'and' (default), 'or' or 'nor'. `filters` is an array of conditions or nested groups. A condition is { key, comparator, value, value2, values }: `key` is a field path ('data.shirtSize', 'meta.created', '_age'); `comparator` is a comparator name such as 'equal', 'notequal', 'in', 'notin', 'contains', 'startswith', 'greater', 'lesser', 'between', 'empty', 'notempty', 'datebefore', 'dateafter', 'datebetween', 'datenext', 'datepast' (content.comparators() lists them all, with aliases such as '>' and '=='); `value` is the value to compare with; `value2` the upper bound for between-style comparators; `values` the array for 'in' / 'notin'. A condition with no key, or no value for a comparator that needs one, is ignored. A key that isn't a real field matches nothing (see options.validateFilterKeys).
+   * @param {Object} [options.sort] How to order the results. When omitted: most recently updated first ('meta.updated', newest first); emails and SMS newest created first; events and assignments by start date, soonest first.
+   * @param {String} options.sort.key The field path to sort on, e.g. 'title', 'meta.created', 'data.rank'.
+   * @param {String} [options.sort.direction] 'asc' (the default when a sort is given) or 'desc' ('dsc' also works).
+   * @param {String} [options.sort.type] How values are compared: 'string' (default), 'number' ('integer', 'decimal' and 'float' also work), 'date', 'boolean', 'natural' (so 'Item 2' comes before 'Item 10') or 'dateproximity' (closest to now first).
+   * @param {Object} [options.page] Paging.
+   * @param {Number} [options.page.size] Rows per page. Default 50, maximum 5000.
+   * @param {Number} [options.page.index] Which page, starting at 1. Default 1.
+   * @param {Object} [options.date] A date range, { startDate, endDate } (dates or ISO strings; either may be left out). For most types it applies to meta.created. For events it returns events that overlap the range; for assignments and check-ins, those whose event overlaps it. Log queries default to the last 12 hours. (The property is `date`; `dates` is rejected with a 400.)
+   * @param {Array<String>} [options.ids] Only return records with these ids (inactive and deleted ones included). An empty array does NOT restrict the list: it is ignored and every matching record is returned.
+   * @param {Boolean} [options.includeInactive] Include records whose meta.status isn't 'active'. Events, runsheets, rosters, assignments and check-ins are never limited by status, and filtering on meta.status includes inactive records automatically.
+   * @param {Boolean} [options.includeTrash] Include deleted records alongside live ones.
+   * @param {Boolean} [options.trash] Return only deleted records (the trash).
+   * @param {Boolean} [options.includeAll] Also return `all`: the ids of every matching record across all pages, in sorted order.
+   * @param {Array<Object>} [options.math] Totals over every matching record, not just the page: [{ key: 'data.amount' }, ...]. Returned as `math`, keyed by field path: { total, count, mean, small, large, unique }.
+   * @param {Number} [options.sample] Return this many matching records picked at random.
+   * @param {Boolean} [options.validateFilterKeys] Fail with a 400 and "did you mean" suggestions when a filter key isn't a field of the type, instead of quietly matching nothing.
+   * @param {Boolean} [options.includeThreads] Attach each record's comment thread to its row.
+   * @param {String} [options.rolodexPrimary] Only records whose alphabetical index letter (meta.rolodexPrimary) is this letter.
+   * @param {String} [options.rolodexSecondary] Only records whose second index letter (meta.rolodexSecondary) is this letter.
+   * @param {Object} [advanced] SDK settings for the request itself; nothing here is sent as part of the query.
+   * @param {Boolean} [advanced.cancellable] Return { promise, cancel(message) } straight away instead of waiting. `promise` resolves to the full axios response, so read its `.data`; a cancelled request rejects with an error that sdk.api.wasCancelled(err) recognises.
+   * @param {Object} [advanced.config] Extra axios request config for the call (headers, timeout...).
+   * @param {String} [advanced.remoteURL] Send the query to this endpoint instead of /content/:type/list.
+   * @returns {Promise<Object>} { items, total, page: { index, total }, benchmarks } plus, when relevant, `all` (with includeAll), `math` (with math), `warnings` (problems found in the query) and `suggestions` (similar names, for a profile search that found nothing). `items` holds the rows of the requested page, `total` counts every matching record and `page.total` is the number of pages. With advanced.cancellable: { promise, cancel } instead.
    * @example
-   *
-   *
-   * sdk.content.list('profile', {
-   *     search:'Jim',
-   *     page:{
-   *         size:50,
-   *         index:2,
-   *     },
-   *     sort:{
-   *         key:'age',
-   *         direction:'asc',
-   *         type:'integer',
+   * const { items, total, page } = await sdk.content.list('profile', {
+   *     select: ['firstName', 'lastName', 'emails', 'data.shirtSize', 'meta.created'],
+   *     search: 'jim',
+   *     filter: {
+   *         operator: 'and',
+   *         filters: [
+   *             { key: '_age', comparator: 'greater', value: 17 },
+   *             { key: 'meta.created', comparator: 'datebetween', value: '2026-01-01', value2: '2026-06-30' },
+   *         ],
    *     },
-   *     filter:{
-   *         operator:'and',
-   *         filters:[{
-   *             key:'age',
-   *             comparator:'>',
-   *             value:5,
-   *         }],
-   *     },
-   * })
+   *     sort: { key: 'lastName', direction: 'asc', type: 'string' },
+   *     page: { size: 100, index: 1 },
+   * });
+   *
+   * // Walk every page
+   * let index = 1, rows = [];
+   * while (true) {
+   *     const result = await sdk.content.list('event', { select: ['title', 'startDate'], page: { size: 500, index } });
+   *     rows.push(...result.items);
+   *     if (index >= result.page.total) break;
+   *     index++;
+   * }
    */
 
   service.list = async function (type, options, advanced) {
@@ -730,30 +801,44 @@ export default function (qik) {
   ///////////////////////////////////////////////////
 
   /**
-   *
-   * Create an item
+   * Creates a record (POST /content/:type/create). The input is validated against the type's fields;
+   * a missing required field or a wrong value rejects with a 400 explaining which.
+   * Built-in fields go at the top level, an organisation definition's own fields go under `data`,
+   * and `meta.scopes` says which scopes (permission groups) the record belongs to — the user needs
+   * create permission in them. Objects in meta.scopes are reduced to their ids in the request; the input you pass in is left unchanged.
+   * To use the endpoint's query options (e.g. ?skipGetContent=true for a smaller response), call sdk.api.post directly.
    * @alias content.create
-   * @param  {String} type The type or definition of the record we want to create
-   * @param  {Object} input The data for our new record
+   * @param {String} type The type key or definition key of the new record, e.g. 'profile', 'article' or an organisation's definition key (see content.glossary()).
+   * @param {Object} input The new record's fields.
+   * @param {Object} [input.data] Values for the definition's own fields, keyed by field key.
+   * @param {Object} [input.meta] Record settings. The ones most often set: scopes (array of scope ids) and status ('active', the default, or 'inactive').
+   * @param {Array<String>} [input.tags] Tag names to attach; tags that don't exist yet are created.
+   * @returns {Promise<Object>} The created record, including its new `_id`, as the creator is allowed to see it.
    * @example
+   * const profile = await sdk.content.create('profile', {
+   *     firstName: 'Mickey',
+   *     lastName: 'Mouse',
+   *     emails: ['mickey@example.com'],
+   *     meta: { scopes: ['61eca4746971e75c1fc670cf'] },
+   * });
    *
-   *
-   * const result = await sdk.content.create('profile', {
-   *     firstName:'Mickey',
-   *     lastName:'Mouse',
-   *     gender:'male',
-   *     meta:{
-   *       scopes:['61eca4746971e75c1fc670cf'],
-   *     }
-   * })
+   * const application = await sdk.content.create('jobApplication', {
+   *     title: 'Mickey Mouse',
+   *     data: { role: 'Receptionist', startDate: '2026-10-01' },
+   *     meta: { scopes: ['61eca4746971e75c1fc670cf'] },
+   * });
    */
 
   service.create = async function (type, input) {
     const dataModel = { ...input };
 
-    // Sanitize down to just ids before we send
+    // Sanitize down to just ids before we send. Copy meta rather than
+    // changing it in place, so the caller's own object keeps its scopes.
     if (dataModel.meta?.scopes) {
-      dataModel.meta.scopes = qik.utils.ids(dataModel.meta.scopes);
+      dataModel.meta = {
+        ...dataModel.meta,
+        scopes: qik.utils.ids(dataModel.meta.scopes),
+      };
     }
 
     const { data } = await qik.api.post(`/content/${type}/create`, dataModel);
@@ -761,30 +846,35 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Update an item, Only fields the user has permission to view will be returned
+   * Replaces a record with the input (PUT /content/:id). This is a full replacement, not a merge:
+   * top-level fields left out of the input are cleared and `data` is replaced as a whole, so send the
+   * complete record (for example what content.get returned, with your changes applied). Use content.patch
+   * to change only some fields. If the user isn't allowed to edit some of the record's fields, the server
+   * switches to a merge so those fields are kept. Objects in meta.scopes are reduced to their ids in the request; the input you pass in is left unchanged.
+   * To use the endpoint's query options (e.g. ?expectedUhash=... to reject the write with a 409 if someone else
+   * changed the record first), call sdk.api.put directly.
    * @alias content.update
-   * @param  {String} id The id of the record we want to update
-   * @param  {Object} input The data to update
+   * @param {String|Object} id The record's id, or an object with an _id.
+   * @param {Object} input The complete record.
+   * @returns {Promise<Object>} The updated record, showing only the fields the user is allowed to see.
    * @example
-   *
-   * const result = await sdk.content.update('61eca4746971e75c1fc670cd', {
-   *     firstName:'Minnie',
-   *     lastName:'Mouse',
-   *     gender:'female',
-   *     meta:{
-   *       scopes:['61eca4746971e75c1fc670cd'],
-   *     }
-   * })
+   * const profile = await sdk.content.get('61eca4746971e75c1fc670cd');
+   * profile.firstName = 'Minnie';
+   * profile.data = { ...profile.data, shirtSize: 'M' };
+   * const updated = await sdk.content.update(profile._id, profile);
    */
   service.update = async function (id, input) {
     id = qik.utils.id(id);
 
     const dataModel = { ...input };
 
-    // Sanitize down to just ids before we send
+    // Sanitize down to just ids before we send. Copy meta rather than
+    // changing it in place, so the caller's own object keeps its scopes.
     if (dataModel.meta?.scopes) {
-      dataModel.meta.scopes = qik.utils.ids(dataModel.meta.scopes);
+      dataModel.meta = {
+        ...dataModel.meta,
+        scopes: qik.utils.ids(dataModel.meta.scopes),
+      };
     }
 
     const { data } = await qik.api.put(`/content/${id}`, dataModel);
@@ -792,26 +882,35 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Partially update and patch an item, Only fields the user has permission to edit will be updated
+   * Changes only the fields you send (PATCH /content/:id); everything else is kept. How values combine:
+   * a top-level field you send replaces the current value, arrays included (sending `emails` replaces the whole list);
+   * `data` is merged key by key, deeply; an array inside `data` is COMBINED with the existing one (new items
+   * are added, nothing is removed; an object with the same _id, id, title or name as an existing one replaces it). To remove items from a data array, either send the whole record with
+   * content.update, or call sdk.api.patch(`/content/${id}?mergeReplaceArrays=true`, input) so arrays are replaced.
+   * Within `meta` only some settings can be changed this way (scopes, status, security, slug, keywords, owners and a few more).
+   * Fields the user isn't allowed to edit are left unchanged. Objects in meta.scopes are reduced to their ids in the request; the input you pass in is left unchanged.
    * @alias content.patch
-   * @param  {String} id The id of the record we want to update
-   * @param  {Object} input The data to update, this will be merged with existing data
+   * @param {String|Object} id The record's id, or an object with an _id.
+   * @param {Object} input The fields to change.
+   * @returns {Promise<Object>} The updated record, showing only the fields the user is allowed to see.
    * @example
-   *
-   * const result = await sdk.content.patch('61eca4746971e75c1fc670cd', {
-   *     firstName:'Mickey',
-   *     gender:'male',
-   * })
+   * const updated = await sdk.content.patch('61eca4746971e75c1fc670cd', {
+   *     firstName: 'Mickey',
+   *     data: { shirtSize: 'L', tags: ['mentor'] }, // 'mentor' is added to data.tags, other data fields are kept
+   * });
    */
   service.patch = async function (id, input) {
     id = qik.utils.id(id);
 
     const dataModel = { ...input };
 
-    // Sanitize down to just ids before we send
+    // Sanitize down to just ids before we send. Copy meta rather than
+    // changing it in place, so the caller's own object keeps its scopes.
     if (dataModel.meta?.scopes) {
-      dataModel.meta.scopes = qik.utils.ids(dataModel.meta.scopes);
+      dataModel.meta = {
+        ...dataModel.meta,
+        scopes: qik.utils.ids(dataModel.meta.scopes),
+      };
     }
 
     const { data } = await qik.api.patch(`/content/${id}`, dataModel);
@@ -819,13 +918,26 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Get an item from the database, Only fields the user has permission to view will be returned
+   * Fetches one record by id (GET /content/:id). The type is worked out from the id, so no type is needed.
+   * Returns every field the user is allowed to see (the rest are removed), with reference fields populated.
+   * Rejects with 403 when the user may not view the record, 404 when it doesn't exist and 400 for an invalid id.
+   * To fetch many records use content.list with `select` rather than calling this in a loop.
    * @alias content.get
-   * @param  {String} id The id of the record we want to update
+   * @param {String|Object} id The record's id, or an object with an _id.
+   * @param {Object} [params] axios request config, passed unchanged to sdk.api.get. Query options for the server go inside its `params` property (see below).
+   * @param {Object} [params.params] Query string options for the server.
+   * @param {Array<String>} [params.params.select] Only return these fields (dot paths) plus _id. Give at least two keys: a single key is sent as a plain string, which the server doesn't read as a list.
+   * @param {String} [params.params.version] Id of an entry from the record's history (log) to return that earlier version instead of the current one. Needs edit access to the record (or the log.viewany permission).
+   * @param {String} [params.params.context] 'edit' to require edit permission instead of view permission.
+   * @param {Boolean} [params.params.unpopulated] Leave reference fields as ids instead of populating them.
+   * @returns {Promise<Object>} The record.
    * @example
+   * const profile = await sdk.content.get('61eca4746971e75c1fc670cd');
    *
-   * const result = await sdk.content.get('61eca4746971e75c1fc670cd')
+   * // Only some fields
+   * const partial = await sdk.content.get('61eca4746971e75c1fc670cd', {
+   *     params: { select: ['firstName', 'lastName', 'data.shirtSize'] },
+   * });
    */
   service.get = async function (id, params) {
     id = qik.utils.id(id);
@@ -835,17 +947,33 @@ export default function (qik) {
     return data;
   };
 
+  /**
+   * Same as content.get(id) with no options.
+   * @alias content.getFromID
+   * @param {String|Object} id The record's id, or an object with an _id.
+   * @returns {Promise<Object>} The record.
+   * @example
+   * const record = await sdk.content.getFromID('61eca4746971e75c1fc670cd');
+   */
   service.getFromID = async function (id) {
     return service.get(id);
   };
 
   /**
-   *
-   * Delete an item from the database
+   * Deletes a record (DELETE /content/:id). By default this moves it to the trash (meta.deleted = true),
+   * from where content.restore brings it back; trashed records are hidden from content.list unless
+   * `trash` or `includeTrash` is set. Needs delete permission on the record.
    * @alias content.delete
-   * @param  {String} id The id of the record we want to delete
+   * @param {String|Object} id The record's id, or an object with an _id.
+   * @param {Object} [input] axios request config, passed unchanged to sdk.api.delete. A request body goes in its `data` property.
+   * @param {Object} [input.data] Request body.
+   * @param {Boolean} [input.data.erase] Permanently erase the record instead of trashing it. Can't be undone; needs erase permission.
+   * @returns {Promise<Object>} For a normal delete: { _id, meta: { type, definition, deleted: true } }.
    * @example
-   * const result = await sdk.content.delete('61eca4746971e75c1fc670cd')
+   * await sdk.content.delete('61eca4746971e75c1fc670cd');
+   *
+   * // Permanently erase
+   * await sdk.content.delete('61eca4746971e75c1fc670cd', { data: { erase: true } });
    */
   service.delete = async function (id, input) {
     id = qik.utils.id(id);
@@ -854,12 +982,14 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Restore a deleted item from the database
+   * Brings a trashed record back (GET /content/:id/restore). Needs restore permission on the record.
+   * Erased records can't be restored.
    * @alias content.restore
-   * @param  {String} id The id of the record we want to restore
+   * @param {String|Object} id The record's id, or an object with an _id.
+   * @param {Object} [input] axios request config, passed unchanged to sdk.api.get.
+   * @returns {Promise<Object>} The restored record.
    * @example
-   * const result = await sdk.content.restore('61eca4746971e75c1fc670cd')
+   * const restored = await sdk.content.restore('61eca4746971e75c1fc670cd');
    */
   service.restore = async function (id, input) {
     id = qik.utils.id(id);
@@ -868,16 +998,14 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Retrieve an item from the database by providing it's 'slug'
+   * Fetches one record by its slug (GET /content/slug/:slug) instead of its id, with the same permission
+   * rules as content.get. The slug is written as '<type or definition key>:<slug>', e.g. 'article:how-to-get-started';
+   * a record's `meta.abs` holds this form.
    * @alias content.getFromSlug
-   * @param  {String} slug The slug id of the record we want to retrieve
-   * it must be provided as either `(type):(slug)`` or `(definition):(slug)`
-   * (if unsure use the `meta.abs` absolute slug property of the item you are wanting to retrieve).
+   * @param {String} slug '<type or definition key>:<the record's meta.slug>'.
+   * @returns {Promise<Object>} The record.
    * @example
-   * const result = await sdk.content.getFromSlug('article:how-to-get-started')
-   * const result = await sdk.content.getFromSlug('car:toyota-landcruiser')
-   * const result = await sdk.content.getFromSlug('article:toyota-landcruiser')
+   * const article = await sdk.content.getFromSlug('article:how-to-get-started');
    */
   service.getFromSlug = async function (slug) {
     const { data } = await qik.api.get(`/content/slug/${slug}`);