@zoho_apptics/apptics-js-sdk 2.0.0-beta → 2.0.0-beta.2

package/dist/cjs/device/index.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var constants = require('../core/constants.js');
@@ -6,6 +6,7 @@ var state = require('../core/state.js');
 var logger = require('../core/logger.js');
 var utils = require('../core/utils.js');
 var storage = require('../core/storage.js');
+var locks = require('../core/locks.js');
 var env = require('../core/env.js');
 var consent = require('../core/consent.js');
 var transport = require('../core/transport.js');
@@ -95,7 +96,11 @@ function checkAndUpdateDeviceInfo() {
         // appreleaseversionid from app/addversion
         modelid: storage.getKeyFromDeviceInfo('modelid'), // no i18n
         appreleaseversionid: storage.getKeyFromDeviceInfo('appreleaseversionid'), // no i18n
-        timezone: env.getTimeZone()
+        timezone: env.getTimeZone(),
+        // kept here rather than as keys of their own: the id the browser is registered under, and
+        // whether it has had a session (a session's firstsession says so)
+        uuid: state._ZAP._uuid || storage.getKeyFromDeviceInfo('uuid'), // no i18n
+        hadsession: storage.getKeyFromDeviceInfo('hadsession') === true ? true : undefined, // no i18n
     };
     // the rebuild above starts from browser facts, so the ids app/addversion returned are put
     // back before anything is stored or compared
@@ -103,10 +108,18 @@ function checkAndUpdateDeviceInfo() {
     storage.user_defaults.add('device_info', state._ZAP._device_info); // no i18n
     addOrUpdateDeviceID(state._ZAP._device_info, previous);
 }
+/**
+ * Whether device/add has registered this device: it has a deviceid. anonymousid is not required:
+ * not every Apptics server sends one, nothing the SDK sends carries it, and requiring it had a
+ * server that leaves it out register the same device again on every page load.
+ */
+function isRegistered(info) {
+    return !!info && !utils.isEmpty(info.deviceid);
+}
 function addOrUpdateDeviceID(device_info, previous) {
     var old_device_info = previous !== undefined ? previous : storage.user_defaults.item('device_info') || {}; // no i18n
     // Compare the old and new device infos and update the server if anything changed in the new.
-    if (device_info.deviceid == null || device_info.frameworkid == null || device_info.anonymousid == null) {
+    if (!isRegistered(device_info) || device_info.frameworkid == null) {
         device_info.frameworkid = state._ZAP._frameworkID;
         logger.Console.log('addOrUpdateDeviceID: Initiated register the device'); // no i18n
         registerDeviceWithApptics().then(function (result_device_info) {
@@ -143,7 +156,7 @@ function addOrUpdateDeviceID(device_info, previous) {
  * out as an empty header.
  */
 const DEVICE_RESPONSE_KEYS = ['deviceid', 'anonymousid', 'aaid', 'apid', 'mapid', 'appversionid', 'osversionid', 'timezoneid', 'platformid', 'devicetypeid', 'modelid']; // no i18n
-/** Copies server-assigned ids into state and persists device info. */
+/** Copies server-assigned ids into state and persists device info; resolves once it is stored. */
 function applyDeviceResponse(data) {
     DEVICE_RESPONSE_KEYS.forEach(function (key) {
         // an id the answer does not mention is one we already hold, or one we never had:
@@ -159,12 +172,81 @@ function applyDeviceResponse(data) {
     if (!utils.isEmpty(data.mapid)) {
         state._ZAP._mapid = data.mapid;
     }
-    // Update the new device info into the localstorage
-    storage.user_defaults.add('device_info', state._ZAP._device_info); // no i18n
+    // stored before the registration counts as done, so another tab waiting to register reads it
+    return storage.user_defaults.save('device_info', state._ZAP._device_info); // no i18n
+}
+/**
+ * The browser's uuid: the one in storage, or a new one stored now. Every tab of the site uses the
+ * same one, because the device is registered under it.
+ */
+function useStoredUuid() {
+    // kept in device_info: it is the id this browser is registered under
+    var uuid = storage.getKeyFromDeviceInfo('uuid'); // no i18n
+    if (utils.isEmpty(uuid)) {
+        uuid = utils.getNewUUID();
+        storage.setDeviceInfoKey('uuid', uuid); // no i18n
+    }
+    state._ZAP._uuid = uuid;
+}
+/**
+ * The ids another tab of this site registered after this one loaded its settings: those are in
+ * storage but not in this tab's copy. Resolves with them, applied to this tab, or null when the
+ * browser is still unregistered and this tab has to register it.
+ */
+function adoptRegisteredDevice() {
+    return storage.reloadSettings(['device_info']).then(function () {
+        var stored = storage.user_defaults.item('device_info') || {}; // no i18n
+        if (!isRegistered(stored)) {
+            return null;
+        }
+        // the device is registered under the uuid the other tab sent
+        if (!utils.isEmpty(stored.uuid)) {
+            state._ZAP._uuid = stored.uuid;
+        }
+        logger.Console.log('registerDeviceWithApptics: another tab registered this browser, using its device ' + stored.deviceid); // no i18n
+        return applyDeviceResponse(stored).then(function () {
+            return { result: 'success', data: stored }; // no i18n
+        });
+    });
+}
+/**
+ * Sets up this browser's device at start-up: the uuid, the device info, and a registration when
+ * the browser has none.
+ *
+ * Settings are this tab's own copy, loaded when it started. On a browser with no device yet, two
+ * tabs started together would each register it and store two devices, so the first visit runs
+ * under a lock shared by every tab of the site: the tab that gets it re-reads storage, registers
+ * only when no other tab has, and keeps the lock until the new ids are stored. The next tab then
+ * finds them. Start-up goes on as soon as the device info is set, without waiting for the server.
+ */
+function prepareDevice() {
+    var cached = storage.user_defaults.item('device_info') || {}; // no i18n
+    if (isRegistered(cached)) {
+        useStoredUuid();
+        checkAndUpdateDeviceInfo();
+        return Promise.resolve();
+    }
+    return new Promise(function (resolve) {
+        locks.withLock('device', function () {
+            return storage.reloadSettings(['device_info']).then(function () {
+                useStoredUuid();
+                checkAndUpdateDeviceInfo();
+                resolve();
+                // held until a registration this started is stored, or has failed
+                return deviceReady();
+            });
+        }).catch(function (err) {
+            logger.Console.log('prepareDevice: ' + err); // no i18n
+        }).then(function () {
+            resolve();
+        });
+    });
 }
 /** True while the device has no server ids, so nothing can be sent yet. */
 function needsDevice() {
-    return utils.isEmpty(transport.getHeaderParams('apid')) && utils.isEmpty(transport.getHeaderParams('mapid')); // no i18n
+    // the app ids from app/addversion, and the deviceid from device/add: either missing, and the
+    // device is registered before anything stored is sent
+    return (utils.isEmpty(transport.getHeaderParams('apid')) && utils.isEmpty(transport.getHeaderParams('mapid'))) || !transport.hasDeviceId(); // no i18n
 }
 /**
  * Resolves once a registration that is in flight has settled, succeeded or not, and right away
@@ -197,14 +279,14 @@ function registerDeviceWithApptics() {
         return blocked;
     }
     if (!state._ZAP._token) {
-        logger.Console.warn(label + ': You must call apptics.init() first'); // no i18n
-        return Promise.reject(label + ': You must call apptics.init() first'); // no i18n
+        logger.Console.warn(label + ': You must call Apptics.init() first'); // no i18n
+        return Promise.reject(label + ': You must call Apptics.init() first'); // no i18n
     }
     var offline = transport.rejectIfOffline(label);
     if (offline) {
         return offline;
     }
-    if (state._ZAP._device_info.deviceid && state._ZAP._device_info.anonymousid) {
+    if (isRegistered(state._ZAP._device_info)) {
         return Promise.resolve(state._ZAP._device_info);
     }
     return new Promise((resolve, reject) => {
@@ -215,17 +297,27 @@ function registerDeviceWithApptics() {
             return;
         }
         state._ZAP._regDeviceSending = true;
-        var payload = deviceBody(state._ZAP._device_info);
-        // device/add is the one url that allows all four: zak and uuid identify the caller,
-        // apid and mapid the app. app/addversion has already answered with apid and mapid by
-        // the time registration runs, so the first call can carry them like every later one.
-        var headers = { zak: transport.getHeaderParams('zak'), uuid: transport.getHeaderParams('uuid'), ...transport.apiHeaders() }; // no i18n
-        transport.postToApptics('regdevice', payload, headers, label).then(function (result) {
-            applyDeviceResponse(result.data || {});
+        adoptRegisteredDevice().then(function (adopted) {
+            if (adopted) {
+                return adopted;
+            }
+            var payload = deviceBody(state._ZAP._device_info);
+            // device/add is the one url that allows all four: zak and uuid identify the caller,
+            // apid and mapid the app. app/addversion has already answered with apid and mapid by
+            // the time registration runs, so the first call can carry them like every later one.
+            var headers = { zak: transport.getHeaderParams('zak'), uuid: transport.getHeaderParams('uuid'), ...transport.apiHeaders() }; // no i18n
+            return transport.postToApptics('regdevice', payload, headers, label).then(function (result) {
+                return applyDeviceResponse(result.data || {}).then(function () {
+                    return result;
+                });
+            });
+        }).then(function (result) {
             settleRegistration(true, result);
             resolve(result);
-            // first visit: the ids exist now, so fetch the server settings right away
-            refreshServerSettings();
+            // first visit: the ids exist now, so fetch the server settings right away. A device
+            // registered again later (its details or the framework id changed) asks nothing more:
+            // start-up has already asked on this page load
+            startServerSettingChecks();
         }).catch(function (err) {
             settleRegistration(false, err);
             reject(err);
@@ -257,7 +349,15 @@ function getUpdatesFromServer() {
     return transport.postToApptics('sdkconfig', '', transport.apiHeaders(), label).then(function (result) {
         var data = result.data || {};
         applyServerFlags(data);
-        storage.user_defaults.add('trackinfo', state._ZAP._trackinfo); // no i18n
+        if (state._ZAP._nextConfigCheck === 0) {
+            // no next_check_after: getupdates_interval from now, stored so a later page load
+            // can tell whether the answer is still current
+            state._ZAP._nextConfigCheck = utils.nowMs() + state.getConfig('getupdates_interval'); // no i18n
+            state._ZAP._trackinfo.next_check_after = state._ZAP._nextConfigCheck;
+        }
+        // the visitor's tracking status lives in trackinfo too, and is not the server's to replace
+        var saved = storage.storedTrackingStatus();
+        storage.user_defaults.add('trackinfo', saved === undefined ? state._ZAP._trackinfo : Object.assign({}, state._ZAP._trackinfo, { tracking_status: saved })); // no i18n
         logger.Console.log('getUpdatesFromServer: ' + JSON.stringify(state._ZAP._trackinfo)); // no i18n
         return data;
     });
@@ -290,6 +390,10 @@ function applyServerFlags(data) {
     if (data.hasOwnProperty('tracking_enabled')) { // no i18n
         state._ZAP._shouldTrack = data.tracking_enabled !== false;
     }
+    else if (data.hasOwnProperty('shouldtrack')) { // no i18n
+        // what this SDK saves, read back on the next visit
+        state._ZAP._shouldTrack = data.shouldtrack !== false;
+    }
     else {
         // the old shape: archived versions and untracked customer groups
         var versionArchived = !data.hasOwnProperty('versionarchivestatus') || utils.isEmpty(data.versionarchivestatus)
@@ -299,9 +403,14 @@ function applyServerFlags(data) {
         state._ZAP._shouldTrack = versionArchived || !customerGroupTracking;
     }
     if (hasModules) {
-        // sessions carry screens, events and api calls, so module 11 gates all of engagement
-        state._ZAP._engagementTracking = moduleEnabled(status, constants.SDK_MODULE.SESSION);
-        state._ZAP._errorTracking = moduleEnabled(status, constants.SDK_MODULE.CRASH);
+        // each kind of engagement item has its own module, so the server can turn one off alone
+        state._ZAP._engagementTracking = {
+            event: moduleEnabled(status, constants.SDK_MODULE.EVENT),
+            api: moduleEnabled(status, constants.SDK_MODULE.API),
+            screen: moduleEnabled(status, constants.SDK_MODULE.SCREEN),
+            session: moduleEnabled(status, constants.SDK_MODULE.SESSION),
+        };
+        state._ZAP._errorTracking = moduleEnabled(status, constants.SDK_MODULE.JS_ERROR);
         state._ZAP._heatmapTracking = moduleEnabled(status, constants.SDK_MODULE.HEATMAP);
         state._ZAP._remoteLoggerEnabled = moduleEnabled(status, constants.SDK_MODULE.REMOTE_LOGGER);
         state._ZAP._feedbackEnabled = moduleEnabled(status, constants.SDK_MODULE.FEEDBACK);
@@ -310,27 +419,52 @@ function applyServerFlags(data) {
         state._ZAP._remoteConfigEnabled = moduleEnabled(status, constants.SDK_MODULE.REMOTE_CONFIG);
     }
     else {
-        state._ZAP._engagementTracking = data.engagementtracking !== false;
-        state._ZAP._errorTracking = data.errortracking !== false;
-        state._ZAP._heatmapTracking = data.heatmaptracking !== false;
-        state._ZAP._remoteLoggerEnabled = data.remoteloggerenabled !== false;
-        state._ZAP._feedbackEnabled = data.feedbackenabled !== false;
+        // this SDK saves one flag per kind under engagement; an earlier build saved one
+        // engagementtracking flag for all four
+        var saved = (data.engagement && typeof data.engagement === 'object' // no i18n
+            ? data.engagement : null);
+        var kindOn = function (kind) {
+            return saved ? saved[kind] !== false : data.engagementtracking !== false;
+        };
+        state._ZAP._engagementTracking = { event: kindOn('event'), api: kindOn('api'), screen: kindOn('screen'), session: kindOn('session') }; // no i18n
+        // the same for the others: read the short key this SDK saves, else the earlier build's
+        var flagOn = function (key, oldKey) {
+            return (data.hasOwnProperty(key) ? data[key] : data[oldKey]) !== false;
+        };
+        state._ZAP._errorTracking = flagOn('error', 'errortracking'); // no i18n
+        state._ZAP._heatmapTracking = flagOn('heatmap', 'heatmaptracking'); // no i18n
+        state._ZAP._remoteLoggerEnabled = flagOn('remotelogger', 'remoteloggerenabled'); // no i18n
+        state._ZAP._feedbackEnabled = flagOn('feedback', 'feedbackenabled'); // no i18n
     }
+    // screen recording, set up in the console: everything the form needs comes from here
     var quartz = (data.quartz && typeof data.quartz === 'object' ? data.quartz : {});
-    state._ZAP._quartzEnabled = quartz.hasOwnProperty('quartz_enabled') // no i18n
-        ? quartz.quartz_enabled !== false
-        : data.quartzenabled !== false;
-    // when to ask again, which replaces polling on a fixed interval
-    if (typeof data.next_check_after === 'number' && data.next_check_after > 0) {
-        state._ZAP._nextConfigCheck = data.next_check_after;
-    }
+    var text = function (value) {
+        return typeof value === 'string' ? value.trim() : ''; // no i18n
+    };
+    state._ZAP._quartz = {
+        enabled: quartz.hasOwnProperty('quartz_enabled') ? quartz.quartz_enabled === true : data.quartzenabled === true, // no i18n
+        workspace: text(quartz.quartz_workspace),
+        department: text(quartz.quartz_department),
+        domain: text(quartz.quartz_domain),
+        cdnUrl: text(quartz.quartz_cdn_url),
+    };
+    // when to ask again, which replaces polling on a fixed interval. Kept as a timestamp, so the
+    // stored copy reads back the same. An answer without one falls back to getupdates_interval
+    state._ZAP._nextConfigCheck = nextCheckTime(data.next_check_after, utils.nowMs());
     state._ZAP._trackinfo = {
-        engagementtracking: state._ZAP._engagementTracking,
-        errortracking: state._ZAP._errorTracking,
-        heatmaptracking: state._ZAP._heatmapTracking,
-        remoteloggerenabled: state._ZAP._remoteLoggerEnabled,
-        feedbackenabled: state._ZAP._feedbackEnabled,
-        quartzenabled: state._ZAP._quartzEnabled,
+        engagement: state._ZAP._engagementTracking,
+        error: state._ZAP._errorTracking,
+        heatmap: state._ZAP._heatmapTracking,
+        remotelogger: state._ZAP._remoteLoggerEnabled,
+        feedback: state._ZAP._feedbackEnabled,
+        // in the server's own shape, so restoring it on the next visit reads it the same way
+        quartz: {
+            quartz_enabled: state._ZAP._quartz.enabled,
+            quartz_workspace: state._ZAP._quartz.workspace,
+            quartz_department: state._ZAP._quartz.department,
+            quartz_domain: state._ZAP._quartz.domain,
+            quartz_cdn_url: state._ZAP._quartz.cdnUrl,
+        },
         shouldtrack: state._ZAP._shouldTrack,
         next_check_after: state._ZAP._nextConfigCheck
     };
@@ -343,30 +477,164 @@ function restoreServerSettings() {
     var saved = storage.user_defaults.item('trackinfo'); // no i18n
     if (saved && typeof saved === 'object') { // no i18n
         applyServerFlags(saved);
+        // saved by an earlier build under the old names: store it again in this SDK's shape now,
+        // rather than at the next getsdkconfig, which may be a while off. The visitor's tracking
+        // status is kept as it is
+        if (OLD_TRACKINFO_KEYS.some(function (key) { return saved.hasOwnProperty(key); })) {
+            storage.user_defaults.add('trackinfo', saved.tracking_status === undefined ? state._ZAP._trackinfo // no i18n
+                : Object.assign({}, state._ZAP._trackinfo, { tracking_status: saved.tracking_status }));
+        }
         logger.Console.log('restoreServerSettings: ' + JSON.stringify(state._ZAP._trackinfo)); // no i18n
     }
 }
+/** trackinfo keys an earlier build saved, which this SDK saves under shorter names. */
+var OLD_TRACKINFO_KEYS = ['engagementtracking', 'errortracking', 'heatmaptracking', 'remoteloggerenabled', 'feedbackenabled']; // no i18n
 /**
- * Fetches the server settings now if the device is registered. On a first visit the ids don't
- * exist yet; registerDeviceWithApptics calls this as soon as device/add succeeds.
+ * next_check_after as a time: the server's value is milliseconds, either a timestamp or a wait
+ * from now. Anything below 1e12 (2001 as a timestamp) can only be a wait.
+ */
+function nextCheckTime(value, now) {
+    if (typeof value !== 'number' || !(value > 0)) { // no i18n
+        return 0;
+    }
+    return value >= 1e12 ? value : now + value;
+}
+/** setTimeout's longest wait; a longer one fires straight away. */
+var MAX_TIMEOUT = 2147483647;
+var configTimer = null;
+var configInFlight = false;
+/** Bumped by stopServerSettingChecks(), so an answer to an ask from before a reset schedules nothing. */
+var configRound = 0;
+/** Whether this page load has asked, or set the timer from the saved answer instead. */
+var configAsked = false;
+/** A user registered, or getupdates reported a change, while a getsdkconfig was in flight: asked again when it answers. */
+var configAskAgain = false;
+/** When the next getsdkconfig is due, as a timestamp. 0 until the first answer. */
+var configDueAt = 0;
+/**
+ * Asks for the server settings now if the device is registered, then schedules the next ask
+ * for the time the answer gave in next_check_after. On a first visit the ids don't exist yet;
+ * registerDeviceWithApptics calls this as soon as device/add succeeds.
  */
 function refreshServerSettings() {
-    if (utils.isEmpty(transport.getHeaderParams('apid')) && utils.isEmpty(transport.getHeaderParams('mapid'))) { // no i18n
+    if (configInFlight || !transport.hasDeviceId() || (utils.isEmpty(transport.getHeaderParams('apid')) && utils.isEmpty(transport.getHeaderParams('mapid')))) { // no i18n
         return;
     }
+    if (configTimer !== null) {
+        clearTimeout(configTimer);
+        configTimer = null;
+    }
+    configInFlight = true;
+    configAsked = true;
+    markTabAsked();
+    var round = configRound;
+    var askedAt = utils.nowMs();
     getUpdatesFromServer().catch(function (err) {
         logger.Console.log(err);
+    }).then(function () {
+        if (round !== configRound) {
+            // stopServerSettingChecks() ran while this was in flight
+            return;
+        }
+        configInFlight = false;
+        if (configAskAgain) {
+            configAskAgain = false;
+            refreshServerSettings();
+            return;
+        }
+        // an answer without a usable next_check_after, or a failed call, waits getupdates_interval
+        configDueAt = state._ZAP._nextConfigCheck > utils.nowMs() ? state._ZAP._nextConfigCheck : askedAt + state.getConfig('getupdates_interval'); // no i18n
+        scheduleServerSettingCheck();
     });
 }
+/**
+ * getsdkconfig now, not at the next check: setUser registered a user, or getupdates reported a
+ * module changed.
+ */
+function askServerSettings() {
+    if (configInFlight) {
+        // the one in flight went out before the change: ask again once it answers
+        configAskAgain = true;
+        return;
+    }
+    refreshServerSettings();
+}
+/**
+ * Start-up's getsdkconfig. Asked on a first visit and on the first page load in each tab; any
+ * other load (a reload, a link to another page of the site, back/forward) uses the saved answer
+ * and waits for its next_check_after, unless that has already passed. Nothing happens if one has
+ * gone out already on this load (after device/add).
+ */
+function startServerSettingChecks() {
+    if (configAsked) {
+        return;
+    }
+    if (tabHasAsked() && state._ZAP._nextConfigCheck > utils.nowMs()) {
+        logger.Console.log('getsdkconfig: the saved answer is still current'); // no i18n
+        configAsked = true;
+        configDueAt = state._ZAP._nextConfigCheck;
+        scheduleServerSettingCheck();
+        return;
+    }
+    refreshServerSettings();
+}
+/** sessionStorage: per tab, and kept across a reload and the site's own links. */
+var TAB_ASKED_KEY = '_apptics_sdkconfig_asked'; // no i18n
+/** Whether getsdkconfig has gone out in this tab before, on an earlier page load. */
+function tabHasAsked() {
+    try {
+        return sessionStorage.getItem(TAB_ASKED_KEY) === '1'; // no i18n
+    }
+    catch (e) {
+        return false; // no sessionStorage (private mode, sandboxed frame): every load asks
+    }
+}
+function markTabAsked() {
+    try {
+        sessionStorage.setItem(TAB_ASKED_KEY, '1'); // no i18n
+    }
+    catch (e) {
+        // as above: without it, every load asks
+    }
+}
+/** Sets the timer for the next getsdkconfig, at configDueAt. */
+function scheduleServerSettingCheck() {
+    if (configTimer !== null) {
+        clearTimeout(configTimer);
+    }
+    var wait = Math.min(Math.max(configDueAt - utils.nowMs(), 0), MAX_TIMEOUT);
+    logger.Console.log('getsdkconfig: next check in ' + wait + ' ms'); // no i18n
+    configTimer = setTimeout(function () {
+        configTimer = null;
+        refreshServerSettings();
+    }, wait);
+}
+/** reset(): no more checks, and the next init() asks again straight away. */
+function stopServerSettingChecks() {
+    if (configTimer !== null) {
+        clearTimeout(configTimer);
+    }
+    configTimer = null;
+    configRound++;
+    configInFlight = false;
+    configAsked = false;
+    configAskAgain = false;
+    configDueAt = 0;
+}
 hooks.hooks.updateDevice = updateDeviceWithApptics;
 hooks.hooks.refreshDeviceInfo = checkAndUpdateDeviceInfo;
+hooks.hooks.askServerSettings = askServerSettings;
 
 exports.addOrUpdateDeviceID = addOrUpdateDeviceID;
 exports.checkAndUpdateDeviceInfo = checkAndUpdateDeviceInfo;
 exports.deviceReady = deviceReady;
 exports.getUpdatesFromServer = getUpdatesFromServer;
 exports.needsDevice = needsDevice;
+exports.nextCheckTime = nextCheckTime;
+exports.prepareDevice = prepareDevice;
 exports.refreshServerSettings = refreshServerSettings;
 exports.registerDeviceWithApptics = registerDeviceWithApptics;
 exports.restoreServerSettings = restoreServerSettings;
+exports.startServerSettingChecks = startServerSettingChecks;
+exports.stopServerSettingChecks = stopServerSettingChecks;
 exports.updateDeviceWithApptics = updateDeviceWithApptics;

package/dist/cjs/engagement/api-rules.d.ts

@@ -1,62 +1,34 @@
-/**
- * What API tracking records, and under what name — Android's AppticsApiTracker.configure, built
- * with ApiTrackingBuilder the way user properties are built with UserBuilder:
- *
- *   configureApiTracking(new ApiTrackingBuilder()
- *       .allowOnlyDomains('api.zylker.com', 'api.zylker.in')
- *       .groupDomains('api.zylker.*')
- *       .ignoreEndpoint('/health', '/internal/**')
- *       .addPattern('/v2/catalog/{categoryId}/items/{itemId}')
- *       .build());
- *
- * Two jobs. Filtering decides whether a call is recorded at all: ignore rules first, and they
- * always win, then the allow lists. Normalization decides the path it is recorded under, so that
- * `/users/42/orders` and `/users/43/orders` are one endpoint on the console rather than two: the
- * query string goes, an explicit pattern is used when one matches, and otherwise numeric ids,
- * UUIDs and JWTs become `*`.
- *
- * Both apply to every call, the ones the fetch/XHR wrappers catch and the ones the app reports
- * with trackApi() or startTrackApi(), so one set of rules decides what the API page shows.
- */
 /** The rules, as ApiTrackingBuilder.build() returns them. Every list may be empty. */
 export interface ApiTrackingConfig {
-    ignoreDomains: string[];
-    allowOnlyDomains: string[];
-    allowOnlyTLDs: string[];
-    ignoreTLDs: string[];
-    ignoreDomainPrefixes: string[];
-    ignoreDomainSuffixes: string[];
-    groupDomains: string[];
-    ignoreEndpoints: string[];
-    patterns: string[];
-    preserveSegments: string[];
-    autoDetection: boolean;
+    /** URLs recorded, exactly; with any allow rule, only calls matching one are recorded. */
+    allowEquals: string[];
+    /** URLs never recorded, exactly. */
+    ignoreEquals: string[];
+    /** Regular expressions a recorded URL may match; with any allow rule, it must match one. */
+    allowRegex: RegExp[];
+    /** Regular expressions whose URLs are never recorded. */
+    ignoreRegex: RegExp[];
 }
-/** Builds the rules for configureApiTracking, with AppticsApiTracker.configure's names. */
+/**
+ * A URL as the rules compare it: `scheme://host[:port]/path`, the scheme and host lower-cased,
+ * the default port dropped, the query, fragment and a trailing slash removed. '' when it is not
+ * an absolute http(s) URL.
+ */
+export declare function ruleUrl(raw: string): string;
+/**
+ * Builds the rules configure takes. Each method may be called more than once, and takes any number
+ * of values: `new ApiTrackingBuilder().allowEquals(a, b).ignoreRegex(/x/).build()`.
+ */
 export declare class ApiTrackingBuilder {
     private rules;
-    /** Never records these hosts. */
-    ignoreDomains(...domains: string[]): this;
-    /** Records only these hosts; every other is skipped. */
-    allowOnlyDomains(...domains: string[]): this;
-    /** Records only hosts ending in these TLDs, e.g. `.com`. */
-    allowOnlyTLDs(...tlds: string[]): this;
-    /** Never records hosts ending in these TLDs, e.g. `.local`. */
-    ignoreTLDs(...tlds: string[]): this;
-    /** Never records hosts starting with these, e.g. `dev.`. */
-    ignoreDomainPrefixes(...prefixes: string[]): this;
-    /** Never records hosts ending with these, e.g. `.cdn.net`. */
-    ignoreDomainSuffixes(...suffixes: string[]): this;
-    /** Records the hosts a pattern such as `api.myapp.*` matches under that one name. */
-    groupDomains(...patterns: string[]): this;
-    /** Never records these paths: exact, `*` or `{name}` for one segment, `**` at the end for a prefix. */
-    ignoreEndpoint(...paths: string[]): this;
-    /** Records a path this pattern matches as the pattern, with each `{name}` as `*`. Tried before auto-detection. */
-    addPattern(...patterns: string[]): this;
-    /** Segments never turned into `*`, e.g. `v1` or `404`. */
-    preserveSegments(...segments: string[]): this;
-    /** `false`: only addPattern paths are normalized; every other path is recorded as it is. */
-    autoDetection(enabled: boolean): this;
+    /** Records only these URLs (and those any allowRegex matches): `https://api.example.com/orders`. */
+    allowEquals(...urls: string[]): this;
+    /** Never records these URLs: `https://api.example.com/health`. */
+    ignoreEquals(...urls: string[]): this;
+    /** Records only URLs these match (and those any allowEquals names): `/^https:\/\/api\.example\.com\//`. */
+    allowRegex(...patterns: Array<RegExp | string>): this;
+    /** Never records URLs these match: `/\/internal\//`. */
+    ignoreRegex(...patterns: Array<RegExp | string>): this;
     build(): ApiTrackingConfig;
 }
 /**
@@ -66,19 +38,12 @@ export declare class ApiTrackingBuilder {
 export declare function configureApiTracking(config: ApiTrackingConfig | ApiTrackingBuilder): void;
 /** The rules in force, for tests and the playground. */
 export declare function apiTrackingConfig(): ApiTrackingConfig;
-/** Whether calls to this host are recorded. Ignore rules are checked first and always win. */
-export declare function hostAllowed(hostname: string): boolean;
-/** The name a host is recorded under: the first groupDomains pattern it matches, or itself. */
-export declare function groupedHost(hostname: string): string;
-/** Whether a host is one of the groupDomains names, which carry a `*` no real host has. */
-export declare function isGroupedHost(hostname: string): boolean;
-/** The path without its query string or fragment, which is where ids and tokens travel. */
-export declare function withoutQuery(path: string): string;
-/** Whether ignoreEndpoint leaves this path out. Matched on the path as called, query removed. */
-export declare function endpointIgnored(path: string): boolean;
 /**
- * The path a call is recorded under. The query goes; then the first addPattern that matches is
- * used, with each `{name}` as `*` (the server's path rule has no room for braces); otherwise, with
- * autoDetection on, numeric ids, UUIDs and JWTs become `*`, except preserveSegments.
+ * Whether a call to `url` is recorded. Ignore rules are tried first and always win; then, when
+ * there are allow rules, the URL must match one. A URL that cannot be read is not recorded.
  */
+export declare function urlTracked(url: string): boolean;
+/** The path without its query string or fragment, which is where ids and tokens travel. */
+export declare function withoutQuery(path: string): string;
+/** The path a call is recorded under: the query goes, and numeric ids, UUIDs and JWTs become `*`. */
 export declare function normalizeApiPath(path: string): string;