@qikdev/sdk 1.0.12 → 1.0.13

package/src/api/qik.core.js

@@ -14,41 +14,32 @@ import { EventDispatcher } from './qik.utils.js';
 ///////////////////////////////////////
 
 /**
- * Creates a new QikCore instance including all of the default sub modules
+ * Creates an SDK instance with all its namespaces: api, auth, content, access, files, filter, utils, cache,
+ * socket, geo and system. The instance is also an event emitter (addEventListener / removeEventListener /
+ * dispatch) and emits 'error' (via sdk.error(err), with a readable message), 'notification' (via
+ * sdk.notify(message, options), with { message, options }), 'variables' and 'glossary' (when those load).
  * @alias qik
  * @constructor
- * @param {Object} options 
- * @param {String} options.apiURL    The remote URL of the Qik API you want to connect to. Options are 'staging', 'production' or you may set a specific URL eg. 'https://api.qik.io' (do not include trailing slash). If no value is provided, will default to 'production'.
- * @param {String} options.applicationToken When running as a static application, (for example a website) you may set the application's access token before you initialize the Qik instance here.
- * @param {Boolean} options.useHttpOnlyCookies When set to true, authentication tokens will be stored in secure httpOnly cookies instead of localStorage. This provides enhanced security against XSS attacks. Requires backend support for cookie-based authentication.
- * @param {Object} options.cookieConfig Configuration options for cookie storage when useHttpOnlyCookies is true.
- * @param {String} options.cookieConfig.domain Cookie domain (auto-detected if not specified).
- * @param {Boolean} options.cookieConfig.secure Whether cookies should only be sent over HTTPS (default: true).
- * @param {String} options.cookieConfig.sameSite SameSite cookie attribute ('strict', 'lax', or 'none', default: 'lax').
+ * @param {Object} [options] Settings. They stay available as properties of the instance (sdk.apiURL...).
+ * @param {String} [options.apiURL] Which API to talk to: 'production' (https://api.qik.dev), 'staging' (https://api.staging.qik.dev), 'local', or a full URL without a trailing slash. When omitted the code currently defaults to 'staging', so pass 'production' explicitly.
+ * @param {String} [options.applicationToken] An application's access token, used for requests while no user is signed in (e.g. a public website).
+ * @param {String} [options.fileAPI] A separate host for file and media URLs (used by files.mediaUrl / downloadUrl with { file: true }).
+ * @param {String} [options.domain] The site's own origin, used by auth.signup with { application: true }.
+ * @param {Boolean} [options.useHttpOnlyCookies] Let the server keep the tokens in httpOnly cookies instead of the SDK holding them in memory (more resistant to script injection; needs the API on a domain that can set those cookies). Falls back to in-memory tokens when cookies aren't available.
+ * @param {Object} [options.cookieConfig] Cookie settings when useHttpOnlyCookies is on.
+ * @param {String} [options.cookieConfig.domain] Cookie domain (worked out from the page's host when omitted).
+ * @param {Boolean} [options.cookieConfig.secure] Only send cookies over HTTPS (default true).
+ * @param {String} [options.cookieConfig.sameSite] 'strict', 'lax' (default) or 'none'.
  * @example
- *
- * //Import the Qik package
  * import Qik from '@qikdev/sdk';
  *
- * //Create a new Qik instance with localStorage (default)
- * var qik = new Qik();
- *
- * //Create a new Qik instance with httpOnly cookies
- * var qik = new Qik({
- *   apiURL: 'production',
- *   useHttpOnlyCookies: true
- * });
+ * const sdk = new Qik({ apiURL: 'production' });
  *
- * //Request the current user session endpoint from the Qik API
- * qik.api.get('/session').then(function(res) {
- *   console.log('User session is ', res.data);
- * })
- * .catch(function(err) {
- *     console.log('There was an error', err);
- * });
+ * // A public website using an application token
+ * const site = new Qik({ apiURL: 'production', applicationToken: 'APPLICATION_TOKEN' });
  *
- * //Use the QikAsset package to generate an image url
- * var link = qik.asset.imageUrl('5ca3d64dd2bb085eb9d450db', 1920, 1080)
+ * const { data: session } = await sdk.api.get('/user');
+ * const src = sdk.files.mediaUrl('image', '5ca3d64dd2bb085eb9d450db', { w: 1920, h: 1080 });
  */
 
 import { version } from '../version.js';

package/src/api/qik.files.js

@@ -1,10 +1,15 @@
 /**
- * Creates a new Files Module instance.
- * This module provides a number of helper functions for interacting with binary file and media content via the REST API
+ * Helpers for files and media: building view and download URLs for images, videos, audio and files, and
+ * formatting durations and file sizes. The URLs include the current access token, so they work in <img>, <video>
+ * and <a> tags without extra headers. This namespace doesn't upload files: uploads go through the
+ * upload endpoints with sdk.api.
  * @alias files
  * @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 src = sdk.files.mediaUrl('image', image, { w: 800 });
+ * const href = sdk.files.downloadUrl('file', file);
  */
 export default function (qik) {
   ///////////////////////
@@ -14,18 +19,19 @@ export default function (qik) {
   ///////////////////////
 
   /**
-   *
-   * Get a valid download url for a specified record
+   * Builds a URL that downloads a file or media record (it adds download=true, so the browser saves it
+   * instead of showing it). The server redirects the URL to a short-lived signed file link.
    * @alias files.downloadUrl
-   * @param  {String} type The type or definition of the item we want to generate the url for
-   * @param  {(Object|String)} id The id or object with an _id property that we want to generate the url for
-   * @param  {Object} params Additional parameters and options for the url
+   * @param {String} type The kind of media endpoint: 'image', 'video', 'audio' or 'file'. 'image' also works with a profile, persona, user, event or video id (their avatar or poster image).
+   * @param {Object|String} id The record's id, or the record itself (anything with an _id).
+   * @param {Object} [params] Query string options. For images: w (width in pixels), h (height in pixels), q (quality 1-100), f (format: 'webp' by default, or 'jpg', 'png'...), c (crop to exactly w x h when present). Values that are false, 0 or empty are left out.
+   * @param {Object} [options] URL options.
+   * @param {Boolean} [options.withoutToken] Don't add the access token (for public media).
+   * @param {Boolean} [options.file] Use the file host (sdk.fileAPI) when one is configured.
+   * @returns {String} The URL, including ?access_token= unless withoutToken is set.
    * @example
-   * const url = sdk.files.downloadUrl('image', '61eca4746971e75c1fc670cf', {w:100, h:100});
-   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?w=100&h=100&download=true
-   *
-   * const url = sdk.files.downloadUrl('image', {_id:'61eca4746971e75c1fc670cf'...}, {f:'png'});
-   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?w=100&h=100&download=true
+   * const url = sdk.files.downloadUrl('file', '61eca4746971e75c1fc670cf');
+   * // https://api.qik.dev/file/61eca4746971e75c1fc670cf?access_token=XXXX&download=true
    */
   service.downloadUrl = function (type, id, params, options) {
     options = options || {};
@@ -36,12 +42,13 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Format a number of (seconds) as timecode (01:35)
+   * Formats a number of seconds as a clock-style duration: m:ss, or h:mm:ss from an hour up. Seconds are rounded.
    * @alias files.duration
-   * @param  {Number} seconds The number of seconds
+   * @param {Number} seconds The duration in seconds.
+   * @returns {String} The formatted duration.
    * @example
-   * const timecode = sdk.files.formatDuration(392.6)
+   * sdk.files.duration(392.6); // '6:33'
+   * sdk.files.duration(3725); // '1:02:05'
    */
   service.duration = function (seconds) {
     // Round to handle floating point values
@@ -61,18 +68,22 @@ export default function (qik) {
   };
 
   /**
-   *
-   * Get a valid media url for a specified image, video or audio item
+   * Builds a URL that shows an image, video, audio or file record inline, e.g. for an <img> or <video> src.
+   * Images are resized on the server to the requested size and format.
    * @alias files.mediaUrl
-   * @param  {String} type The type or definition of the item we want to generate the url for
-   * @param  {(Object|String)} id The id or object with an _id property that we want to generate the url for
-   * @param  {Object} params Additional parameters and options for the url
+   * @param {String} type The kind of media endpoint: 'image', 'video', 'audio' or 'file'. 'image' also works with a profile, persona, user, event or video id (their avatar or poster image).
+   * @param {Object|String} id The record's id, or the record itself (anything with an _id).
+   * @param {Object} [params] Query string options. For images: w (width in pixels), h (height in pixels), q (quality 1-100), f (format: 'webp' by default, or 'jpg', 'png'...), c (crop to exactly w x h when present). Values that are false, 0 or empty are left out.
+   * @param {Object} [options] URL options.
+   * @param {Boolean} [options.withoutToken] Don't add the access token (for public media).
+   * @param {Boolean} [options.file] Use the file host (sdk.fileAPI) when one is configured.
+   * @param {String} [options.extension] Add a file name to the path so players and browsers see an extension: 'mp4' gives /<type>/<id>/<type>.mp4, and a value containing a dot (e.g. 'song.mp3') is used as the file name.
+   * @returns {String} The URL, including ?access_token= unless withoutToken is set.
    * @example
-   * const url = sdk.files.mediaUrl('image', '61eca4746971e75c1fc670cf', {w:100, h:100});
-   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?w=100&h=100&download=true
+   * const src = sdk.files.mediaUrl('image', '61eca4746971e75c1fc670cf', { w: 400, h: 400, c: true });
+   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?access_token=XXXX&w=400&h=400&c=true
    *
-   * const url = sdk.files.mediaUrl('image', {_id:'61eca4746971e75c1fc670cf'...}, {f:'png'});
-   * // https://api.qik.dev/image/61eca4746971e75c1fc670cf?w=100&h=100&download=true
+   * const video = sdk.files.mediaUrl('video', record, {}, { extension: 'mp4' });
    */
   service.mediaUrl = function (type, id, params, options) {
     options = options || {};
@@ -94,13 +105,14 @@ export default function (qik) {
   ///////////////////////
 
   /**
-   *
-   * Convert bytes to a human readable file size
+   * Formats a number of bytes as a readable size, using 1024 bytes per KB.
    * @alias files.filesize
-   * @param  {Integer} bytes The number of bytes
+   * @param {Number} bytes The size in bytes.
+   * @param {Number} [decimals] Decimal places, default 2 (trailing zeros are dropped).
+   * @returns {String} e.g. '1.46 KB'.
    * @example
-   * const size = sdk.files.filesize(1500);
-   * // 1.5kb
+   * sdk.files.filesize(1500); // '1.46 KB'
+   * sdk.files.filesize(0); // '0 Bytes'
    */
   service.filesize = function (bytes, decimals) {
     if (bytes == 0) return "0 Bytes";
@@ -114,16 +126,14 @@ export default function (qik) {
   ///////////////////////
 
   /**
-   *
-   * Get the basic primitive type of a file from it's mime type value
+   * Works out which media type a MIME type belongs to.
    * @alias files.getBinaryTypeFromMime
-   * @param  {String} fileMime The mime type of the file
+   * @param {String} fileMime The MIME type, e.g. 'image/png'.
+   * @returns {String} 'image', 'video', 'audio', or 'file' for anything else (including no MIME type).
    * @example
-   * const type = sdk.files.getBinaryTypeFromMime('image/svg+xml');
-   * // 'image'
-   *
-   * const type = sdk.files.getBinaryTypeFromMime('video/webm');
-   * // 'video'
+   * sdk.files.getBinaryTypeFromMime('image/svg+xml'); // 'image'
+   * sdk.files.getBinaryTypeFromMime('video/webm'); // 'video'
+   * sdk.files.getBinaryTypeFromMime('application/pdf'); // 'file'
    */
   service.getBinaryTypeFromMime = function (fileMime) {
     if (!fileMime) {