@zoho_apptics/apptics-js-sdk 1.0.2 → 2.0.0-beta

package/dist/esm/device/index.js

@@ -0,0 +1,362 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { SDK_MODULE } from '../core/constants.js';
+import { _ZAP } from '../core/state.js';
+import { Console } from '../core/logger.js';
+import { isEmpty, isSuccess, compareTwoObjects } from '../core/utils.js';
+import { user_defaults, getKeyFromDeviceInfo } from '../core/storage.js';
+import { getTimeZone, getConnectionType, getReferringURL, getDevice, getBrowserVersion, getBrowser, getOS } from '../core/env.js';
+import { hasDoNotTrackEnabled } from '../core/consent.js';
+import { getHeaderParams, rejectIfDisabled, rejectIfOffline, apiHeaders, postToApptics, rejectIfNoDeviceIds } from '../core/transport.js';
+import { hooks } from '../core/hooks.js';
+import { applyStoredAppVersion } from './appversion.js';
+
+/** Server-assigned ids, never sent back in device payloads. */
+/**
+ * Exactly the keys deviceInfoWebSDKV2 declares, which is exactly what device/add accepts.
+ *
+ * An allow-list rather than an exclusion list: the template is a closed set of eleven mandatory
+ * keys, so anything else on device_info is refused as EXTRA_PARAM_FOUND and takes the whole
+ * registration with it. v1 carried `frameworkid` in the body; v2 moved it to a query param, and
+ * `platformid` — which v1 left out — became mandatory here. It comes from app/addversion, which
+ * is why that call has to land first.
+ */
+const DEVICE_BODY_KEYS = ['devicetype', 'osversion', 'timezone', 'screenheight', 'screenwidth', 'referrer', 'referringdomain', 'browser', 'browserversion', 'donottrackenabled', 'platformid']; // no i18n
+/** The ones the template types as int, so an empty value has to become 0 rather than ''. */
+const DEVICE_BODY_NUMERIC = ['screenheight', 'screenwidth', 'donottrackenabled', 'platformid']; // no i18n
+/**
+ * The device/add body: all eleven declared keys, always.
+ *
+ * Every one is min-occurrences="1", so a key is sent even when its value is empty — `referrer` is
+ * empty on any direct visit, and leaving it out would refuse the registration over a blank the
+ * server is happy to receive.
+ */
+function deviceBody(info) {
+    var out = {};
+    DEVICE_BODY_KEYS.forEach(function (key) {
+        var value = info[key];
+        var numeric = DEVICE_BODY_NUMERIC.indexOf(key) !== -1;
+        out[key] = isEmpty(value) ? (numeric ? 0 : '') : value; // no i18n
+    });
+    return JSON.stringify(out);
+}
+/**
+ * The fields that describe the device itself, and so the only ones worth a device/add when they
+ * change: a browser or OS upgrade, a new screen, a move between timezones, a do-not-track switch.
+ *
+ * `referrer` and `connectionType` are deliberately absent. Both change constantly — the referrer on
+ * most navigations, the connection on every network switch — so including them would send a
+ * device/add on nearly every page load. The server-assigned ids are absent for the opposite reason:
+ * they arrive from the server, so comparing them would report a change the moment registration
+ * fills them in.
+ */
+const DEVICE_IDENTITY_KEYS = ['osversion', 'browser', 'browserversion', 'devicetype', 'screenheight', 'screenwidth', 'timezone', 'donottrackenabled',
+    // the SDK build this device runs: an upgrade to a new SDK version is a change the server is told about
+    'frameworkid']; // no i18n
+/** The identity fields alone, for comparing one stored device_info against a fresh one. */
+function deviceIdentity(info) {
+    var identity = {};
+    DEVICE_IDENTITY_KEYS.forEach(function (key) {
+        identity[key] = info ? info[key] : undefined;
+    });
+    return identity;
+}
+function checkAndUpdateDeviceInfo() {
+    // read the stored info before it is overwritten below: addOrUpdateDeviceID compares the two to
+    // decide whether the server needs telling, and cannot do that once the new info has replaced it
+    var previous = user_defaults.item('device_info'); // no i18n
+    // params -> https://help.apptics.com/hc/en-us/articles/115004613766-Default-Properties-Collected-by-apptics
+    _ZAP._device_info = {
+        osversion: getOS(),
+        browser: getBrowser(),
+        browserversion: String(getBrowserVersion()),
+        donottrackenabled: hasDoNotTrackEnabled() ? 1 : 0, // no i18n
+        devicetype: getDevice(),
+        screenheight: screen.height,
+        screenwidth: screen.width,
+        referrer: getReferringURL(),
+        connectionType: getConnectionType(),
+        referringdomain: window.location.hostname || '', // no i18n
+        deviceid: getKeyFromDeviceInfo('deviceid'), // no i18n
+        anonymousid: getKeyFromDeviceInfo('anonymousid'), // no i18n
+        // the id of the SDK build running now, never the stored one: a stored id is the build this
+        // device first registered with, and every later SDK version would go on reporting it
+        frameworkid: _ZAP._frameworkID,
+        mapid: getKeyFromDeviceInfo('mapid'), // no i18n
+        aaid: getKeyFromDeviceInfo('aaid'), // no i18n
+        apid: getKeyFromDeviceInfo('apid'), // no i18n
+        appversionid: getKeyFromDeviceInfo('appversionid'), // no i18n
+        platformid: getKeyFromDeviceInfo('platformid'), // no i18n
+        devicetypeid: getKeyFromDeviceInfo('devicetypeid'), // no i18n
+        osversionid: getKeyFromDeviceInfo('osversionid'), // no i18n
+        timezoneid: getKeyFromDeviceInfo('timezoneid'), // no i18n
+        // metaWebSDKV2 needs both of these on every call: modelid comes from device/add,
+        // appreleaseversionid from app/addversion
+        modelid: getKeyFromDeviceInfo('modelid'), // no i18n
+        appreleaseversionid: getKeyFromDeviceInfo('appreleaseversionid'), // no i18n
+        timezone: getTimeZone()
+    };
+    // the rebuild above starts from browser facts, so the ids app/addversion returned are put
+    // back before anything is stored or compared
+    applyStoredAppVersion();
+    user_defaults.add('device_info', _ZAP._device_info); // no i18n
+    addOrUpdateDeviceID(_ZAP._device_info, previous);
+}
+function addOrUpdateDeviceID(device_info, previous) {
+    var old_device_info = previous !== undefined ? previous : 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) {
+        device_info.frameworkid = _ZAP._frameworkID;
+        Console.log('addOrUpdateDeviceID: Initiated register the device'); // no i18n
+        registerDeviceWithApptics().then(function (result_device_info) {
+            if (isSuccess(result_device_info)) {
+                Console.log('addOrUpdateDeviceID: Success register the device ' + JSON.stringify(result_device_info.data)); // no i18n
+                Console.dir(result_device_info.data);
+            }
+            else {
+                Console.log('addOrUpdateDeviceID: Error registering the device: ' + result_device_info); // no i18n
+            }
+        }).catch(function (err) {
+            Console.log('addOrUpdateDeviceID: Error registering the device: ' + err); // no i18n
+        });
+    }
+    else if (!isEmpty(old_device_info) && !compareTwoObjects(deviceIdentity(device_info), deviceIdentity(old_device_info))) {
+        // the device itself changed — a browser or OS upgrade, a new screen, a different timezone.
+        // The update carries the stored deviceid as a param and the stored uuid as a header, so the
+        // server amends this device rather than creating another one: same device, new details
+        Console.log('addOrUpdateDeviceID: Device info changed, so updating new changes'); // no i18n
+        Console.dir(deviceIdentity(device_info));
+        updateDeviceWithApptics(device_info).catch(function (err) {
+            Console.log('addOrUpdateDeviceID: Error updating the device: ' + err); // no i18n
+        });
+    }
+}
+/**
+ * The ids device/add is allowed to set. Each is taken only when the answer actually carries it.
+ *
+ * device/add is not the only source of these: app/addversion runs first and is the *only* source
+ * of aaid, mapid, appversionid and appreleaseversionid. Its answer is already on _device_info by
+ * the time registration replies, and v2's device/add does not repeat all of it - it answers about
+ * the device, not the build. Assigning every key unconditionally therefore overwrote ids we had
+ * with undefined, which is how aaid and appversionid reached metaWebSDKV2 as null and mapid went
+ * 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. */
+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:
+        // either way what is on _device_info is better than undefined
+        if (!isEmpty(data[key])) {
+            _ZAP._device_info[key] = data[key];
+        }
+    });
+    // apid and mapid are also read straight off state for the request headers
+    if (!isEmpty(data.apid)) {
+        _ZAP._apid = data.apid;
+    }
+    if (!isEmpty(data.mapid)) {
+        _ZAP._mapid = data.mapid;
+    }
+    // Update the new device info into the localstorage
+    user_defaults.add('device_info', _ZAP._device_info); // no i18n
+}
+/** True while the device has no server ids, so nothing can be sent yet. */
+function needsDevice() {
+    return isEmpty(getHeaderParams('apid')) && isEmpty(getHeaderParams('mapid')); // no i18n
+}
+/**
+ * Resolves once a registration that is in flight has settled, succeeded or not, and right away
+ * when none is running. Callers use it to wait for the ids rather than poll for them.
+ */
+function deviceReady() {
+    if (!_ZAP._regDeviceSending) {
+        return Promise.resolve();
+    }
+    return new Promise(function (resolve) {
+        _ZAP._regDeviceResolve.push(function () { resolve(); });
+        _ZAP._regDeviceReject.push(function () { resolve(); });
+    });
+}
+/** Ends an in-flight registration: clears the flag and settles every caller that waited on it. */
+function settleRegistration(ok, value) {
+    var waiters = ok ? _ZAP._regDeviceResolve : _ZAP._regDeviceReject;
+    _ZAP._regDeviceSending = false;
+    _ZAP._regDeviceResolve = [];
+    _ZAP._regDeviceReject = [];
+    waiters.forEach(function (fn) {
+        fn(value);
+    });
+}
+// Function to register the device
+function registerDeviceWithApptics() {
+    var label = 'registerDeviceWithApptics'; // no i18n
+    var blocked = rejectIfDisabled(label);
+    if (blocked) {
+        return blocked;
+    }
+    if (!_ZAP._token) {
+        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 = rejectIfOffline(label);
+    if (offline) {
+        return offline;
+    }
+    if (_ZAP._device_info.deviceid && _ZAP._device_info.anonymousid) {
+        return Promise.resolve(_ZAP._device_info);
+    }
+    return new Promise((resolve, reject) => {
+        if (_ZAP._regDeviceSending) {
+            // a registration is already in flight; settle together with it
+            _ZAP._regDeviceResolve.push(resolve);
+            _ZAP._regDeviceReject.push(reject);
+            return;
+        }
+        _ZAP._regDeviceSending = true;
+        var payload = deviceBody(_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: getHeaderParams('zak'), uuid: getHeaderParams('uuid'), ...apiHeaders() }; // no i18n
+        postToApptics('regdevice', payload, headers, label).then(function (result) {
+            applyDeviceResponse(result.data || {});
+            settleRegistration(true, result);
+            resolve(result);
+            // first visit: the ids exist now, so fetch the server settings right away
+            refreshServerSettings();
+        }).catch(function (err) {
+            settleRegistration(false, err);
+            reject(err);
+        });
+    });
+}
+// Function to update the device
+function updateDeviceWithApptics(device_info) {
+    var label = 'updateDeviceWithApptics'; // no i18n
+    var blocked = rejectIfDisabled(label) || rejectIfOffline(label);
+    if (blocked) {
+        return blocked;
+    }
+    var payload = deviceBody(device_info);
+    var headers = { zak: getHeaderParams('zak'), uuid: getHeaderParams('uuid'), ...apiHeaders() }; // no i18n
+    return postToApptics('regdevice', payload, headers, label).then(function (result) {
+        applyDeviceResponse(result.data || {});
+        return result;
+    });
+}
+// Function to get updates from the server
+function getUpdatesFromServer() {
+    var label = 'getUpdatesFromServer'; // no i18n
+    var blocked = rejectIfOffline(label) || rejectIfNoDeviceIds(label);
+    if (blocked) {
+        return blocked;
+    }
+    // getsdkconfig takes no body: the ids it needs are parameters
+    return postToApptics('sdkconfig', '', apiHeaders(), label).then(function (result) {
+        var data = result.data || {};
+        applyServerFlags(data);
+        user_defaults.add('trackinfo', _ZAP._trackinfo); // no i18n
+        Console.log('getUpdatesFromServer: ' + JSON.stringify(_ZAP._trackinfo)); // no i18n
+        return data;
+    });
+}
+/**
+ * Whether getsdkconfig says a module is on.
+ *
+ * Absent means on: a server that does not report a module has not turned it off, and an SDK that
+ * went quiet because of a key it had never heard of would be impossible to diagnose.
+ */
+function moduleEnabled(status, id) {
+    var entry = status[id];
+    if (!entry || typeof entry !== 'object') {
+        return true;
+    }
+    return entry.enabled !== false;
+}
+/**
+ * Applies the server's tracking flags, from a getsdkconfig response or the saved trackinfo.
+ *
+ * v2 reports a flag per module, keyed by a numeric id, rather than the loose booleans getupdates
+ * answered with. Both shapes are read: the stored trackinfo from a previous version of this SDK
+ * is in the old shape, and discarding it would mean a visit tracking things the server had
+ * already said to stop.
+ */
+function applyServerFlags(data) {
+    var status = (data.tracking_status && typeof data.tracking_status === 'object'
+        ? data.tracking_status : {});
+    var hasModules = Object.keys(status).length > 0;
+    if (data.hasOwnProperty('tracking_enabled')) { // no i18n
+        _ZAP._shouldTrack = data.tracking_enabled !== false;
+    }
+    else {
+        // the old shape: archived versions and untracked customer groups
+        var versionArchived = !data.hasOwnProperty('versionarchivestatus') || isEmpty(data.versionarchivestatus)
+            ? true : data.versionarchivestatus;
+        var customerGroupTracking = !data.hasOwnProperty('customergrouptracking') || isEmpty(data.customergrouptracking)
+            ? true : data.customergrouptracking;
+        _ZAP._shouldTrack = versionArchived || !customerGroupTracking;
+    }
+    if (hasModules) {
+        // sessions carry screens, events and api calls, so module 11 gates all of engagement
+        _ZAP._engagementTracking = moduleEnabled(status, SDK_MODULE.SESSION);
+        _ZAP._errorTracking = moduleEnabled(status, SDK_MODULE.CRASH);
+        _ZAP._heatmapTracking = moduleEnabled(status, SDK_MODULE.HEATMAP);
+        _ZAP._remoteLoggerEnabled = moduleEnabled(status, SDK_MODULE.REMOTE_LOGGER);
+        _ZAP._feedbackEnabled = moduleEnabled(status, SDK_MODULE.FEEDBACK);
+        // getsdkconfig is the authority on this one: getupdates reports it too and the two can
+        // disagree while both are in flight, so what is read here wins
+        _ZAP._remoteConfigEnabled = moduleEnabled(status, SDK_MODULE.REMOTE_CONFIG);
+    }
+    else {
+        _ZAP._engagementTracking = data.engagementtracking !== false;
+        _ZAP._errorTracking = data.errortracking !== false;
+        _ZAP._heatmapTracking = data.heatmaptracking !== false;
+        _ZAP._remoteLoggerEnabled = data.remoteloggerenabled !== false;
+        _ZAP._feedbackEnabled = data.feedbackenabled !== false;
+    }
+    var quartz = (data.quartz && typeof data.quartz === 'object' ? data.quartz : {});
+    _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) {
+        _ZAP._nextConfigCheck = data.next_check_after;
+    }
+    _ZAP._trackinfo = {
+        engagementtracking: _ZAP._engagementTracking,
+        errortracking: _ZAP._errorTracking,
+        heatmaptracking: _ZAP._heatmapTracking,
+        remoteloggerenabled: _ZAP._remoteLoggerEnabled,
+        feedbackenabled: _ZAP._feedbackEnabled,
+        quartzenabled: _ZAP._quartzEnabled,
+        shouldtrack: _ZAP._shouldTrack,
+        next_check_after: _ZAP._nextConfigCheck
+    };
+}
+/**
+ * Start-up: applies the server settings saved by the last getupdates, so a "stop tracking"
+ * answer holds across page loads instead of resetting to "on" until the next check.
+ */
+function restoreServerSettings() {
+    var saved = user_defaults.item('trackinfo'); // no i18n
+    if (saved && typeof saved === 'object') { // no i18n
+        applyServerFlags(saved);
+        Console.log('restoreServerSettings: ' + JSON.stringify(_ZAP._trackinfo)); // 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.
+ */
+function refreshServerSettings() {
+    if (isEmpty(getHeaderParams('apid')) && isEmpty(getHeaderParams('mapid'))) { // no i18n
+        return;
+    }
+    getUpdatesFromServer().catch(function (err) {
+        Console.log(err);
+    });
+}
+hooks.updateDevice = updateDeviceWithApptics;
+hooks.refreshDeviceInfo = checkAndUpdateDeviceInfo;
+
+export { addOrUpdateDeviceID, checkAndUpdateDeviceInfo, deviceReady, getUpdatesFromServer, needsDevice, refreshServerSettings, registerDeviceWithApptics, restoreServerSettings, updateDeviceWithApptics };

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

@@ -0,0 +1,84 @@
+/**
+ * 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;
+}
+/** Builds the rules for configureApiTracking, with AppticsApiTracker.configure's names. */
+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;
+    build(): ApiTrackingConfig;
+}
+/**
+ * Applies the rules, replacing any given before. Takes what build() returned, or the builder
+ * itself. Call it once, before the requests it should cover; it works before init().
+ */
+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.
+ */
+export declare function normalizeApiPath(path: string): string;

package/dist/esm/engagement/api-rules.js

@@ -0,0 +1,211 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+/**
+ * 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.
+ */
+function emptyConfig() {
+    return {
+        ignoreDomains: [], allowOnlyDomains: [], allowOnlyTLDs: [], ignoreTLDs: [],
+        ignoreDomainPrefixes: [], ignoreDomainSuffixes: [], groupDomains: [], ignoreEndpoints: [],
+        patterns: [], preserveSegments: [], autoDetection: true,
+    };
+}
+/** Lower-cased, trimmed, non-empty strings: a host list is compared case-insensitively. */
+function cleanList(values, lower) {
+    var out = [];
+    values.forEach(function (value) {
+        if (typeof value !== 'string') { // no i18n
+            return;
+        }
+        var one = value.trim();
+        if (one !== '') { // no i18n
+            out.push(lower ? one.toLowerCase() : one);
+        }
+    });
+    return out;
+}
+/** A TLD as `.com`, whether it was given as `.com` or `com`. */
+function asTld(value) {
+    return value.charAt(0) === '.' ? value : '.' + value; // no i18n
+}
+/** Builds the rules for configureApiTracking, with AppticsApiTracker.configure's names. */
+class ApiTrackingBuilder {
+    constructor() {
+        this.rules = emptyConfig();
+    }
+    /** Never records these hosts. */
+    ignoreDomains(...domains) { this.rules.ignoreDomains.push(...cleanList(domains, true)); return this; }
+    /** Records only these hosts; every other is skipped. */
+    allowOnlyDomains(...domains) { this.rules.allowOnlyDomains.push(...cleanList(domains, true)); return this; }
+    /** Records only hosts ending in these TLDs, e.g. `.com`. */
+    allowOnlyTLDs(...tlds) { this.rules.allowOnlyTLDs.push(...cleanList(tlds, true).map(asTld)); return this; }
+    /** Never records hosts ending in these TLDs, e.g. `.local`. */
+    ignoreTLDs(...tlds) { this.rules.ignoreTLDs.push(...cleanList(tlds, true).map(asTld)); return this; }
+    /** Never records hosts starting with these, e.g. `dev.`. */
+    ignoreDomainPrefixes(...prefixes) { this.rules.ignoreDomainPrefixes.push(...cleanList(prefixes, true)); return this; }
+    /** Never records hosts ending with these, e.g. `.cdn.net`. */
+    ignoreDomainSuffixes(...suffixes) { this.rules.ignoreDomainSuffixes.push(...cleanList(suffixes, true)); return this; }
+    /** Records the hosts a pattern such as `api.myapp.*` matches under that one name. */
+    groupDomains(...patterns) { this.rules.groupDomains.push(...cleanList(patterns, true)); return this; }
+    /** Never records these paths: exact, `*` or `{name}` for one segment, `**` at the end for a prefix. */
+    ignoreEndpoint(...paths) { this.rules.ignoreEndpoints.push(...cleanList(paths, false)); return this; }
+    /** Records a path this pattern matches as the pattern, with each `{name}` as `*`. Tried before auto-detection. */
+    addPattern(...patterns) { this.rules.patterns.push(...cleanList(patterns, false)); return this; }
+    /** Segments never turned into `*`, e.g. `v1` or `404`. */
+    preserveSegments(...segments) { this.rules.preserveSegments.push(...cleanList(segments, false)); return this; }
+    /** `false`: only addPattern paths are normalized; every other path is recorded as it is. */
+    autoDetection(enabled) { this.rules.autoDetection = enabled !== false; return this; }
+    build() {
+        var built = emptyConfig();
+        Object.keys(built).forEach((key) => {
+            var value = this.rules[key];
+            built[key] = Array.isArray(value) ? value.slice() : value;
+        });
+        return built;
+    }
+}
+var current = emptyConfig();
+/**
+ * Applies the rules, replacing any given before. Takes what build() returned, or the builder
+ * itself. Call it once, before the requests it should cover; it works before init().
+ */
+function configureApiTracking(config) {
+    var built = config instanceof ApiTrackingBuilder ? config.build() : config;
+    var next = emptyConfig();
+    if (built && typeof built === 'object') { // no i18n
+        Object.keys(next).forEach(function (key) {
+            var value = built[key];
+            if (key === 'autoDetection') { // no i18n
+                next.autoDetection = value !== false;
+            }
+            else if (Array.isArray(value)) {
+                next[key] = value.slice();
+            }
+        });
+    }
+    current = next;
+}
+/* ---------------- hosts ---------------- */
+function endsWithAny(host, list) {
+    return list.some(function (one) { return host.length >= one.length && host.slice(host.length - one.length) === one; });
+}
+/** Whether calls to this host are recorded. Ignore rules are checked first and always win. */
+function hostAllowed(hostname) {
+    var host = String(hostname || '').toLowerCase(); // no i18n
+    if (current.ignoreDomains.indexOf(host) !== -1
+        || endsWithAny(host, current.ignoreTLDs)
+        || endsWithAny(host, current.ignoreDomainSuffixes)
+        || current.ignoreDomainPrefixes.some(function (prefix) { return host.indexOf(prefix) === 0; })) {
+        return false;
+    }
+    if (current.allowOnlyDomains.length > 0 && current.allowOnlyDomains.indexOf(host) === -1) {
+        return false;
+    }
+    if (current.allowOnlyTLDs.length > 0 && !endsWithAny(host, current.allowOnlyTLDs)) {
+        return false;
+    }
+    return true;
+}
+function wildcardHost(pattern) {
+    var source = pattern.split('*').map(function (part) {
+        return part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'); // no i18n
+    }).join('[a-z0-9.-]+'); // no i18n
+    return new RegExp('^' + source + '$'); // no i18n
+}
+/** The name a host is recorded under: the first groupDomains pattern it matches, or itself. */
+function groupedHost(hostname) {
+    var host = String(hostname || '').toLowerCase(); // no i18n
+    for (var i = 0; i < current.groupDomains.length; i++) {
+        var pattern = current.groupDomains[i];
+        if (pattern.indexOf('*') !== -1 && wildcardHost(pattern).test(host)) { // no i18n
+            return pattern;
+        }
+    }
+    return hostname;
+}
+/* ---------------- paths ---------------- */
+/** The path without its query string or fragment, which is where ids and tokens travel. */
+function withoutQuery(path) {
+    var cut = String(path || '').split(/[?#]/)[0]; // no i18n
+    return cut === '' ? '/' : cut; // no i18n
+}
+function segmentsOf(path) {
+    var trimmed = path.length > 1 ? path.replace(/\/+$/, '') : path; // no i18n
+    return trimmed.split('/').slice(1); // no i18n
+}
+const ONE_SEGMENT = /^(\*|\{[^/{}]*\})$/;
+/** Whether a path matches a pattern: `*` and `{name}` are one segment, a final `**` is the rest. */
+function matches(pattern, path) {
+    var want = segmentsOf(pattern);
+    var have = segmentsOf(path);
+    for (var i = 0; i < want.length; i++) {
+        var part = want[i];
+        if (part === '**' && i === want.length - 1) { // no i18n
+            return true;
+        }
+        if (i >= have.length) {
+            return false;
+        }
+        if (ONE_SEGMENT.test(part)) {
+            if (have[i] === '') { // no i18n
+                return false;
+            }
+            continue;
+        }
+        if (part !== have[i]) {
+            return false;
+        }
+    }
+    return want.length === have.length;
+}
+/** Whether ignoreEndpoint leaves this path out. Matched on the path as called, query removed. */
+function endpointIgnored(path) {
+    var bare = withoutQuery(path);
+    return current.ignoreEndpoints.some(function (pattern) { return matches(pattern, bare); });
+}
+const NUMERIC = /^\d+$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// three base64url parts, the first starting eyJ — the encoding of '{"' every JWT header opens
+// with. Without that start, a file name such as jquery.min.js would pass for a token
+const JWT = /^eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/**
+ * 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.
+ */
+function normalizeApiPath(path) {
+    var bare = withoutQuery(path);
+    for (var i = 0; i < current.patterns.length; i++) {
+        var pattern = current.patterns[i];
+        if (matches(pattern, bare)) {
+            return pattern.replace(/\{[^/{}]*\}/g, '*'); // no i18n
+        }
+    }
+    if (!current.autoDetection) {
+        return bare;
+    }
+    return bare.split('/').map(function (segment) {
+        if (segment === '' || current.preserveSegments.indexOf(segment) !== -1) { // no i18n
+            return segment;
+        }
+        return NUMERIC.test(segment) || UUID.test(segment) || JWT.test(segment) ? '*' : segment; // no i18n
+    }).join('/'); // no i18n
+}
+
+export { ApiTrackingBuilder, configureApiTracking, endpointIgnored, groupedHost, hostAllowed, normalizeApiPath, withoutQuery };

package/dist/esm/engagement/auto-api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Starts or stops automatic tracking. Safe to call repeatedly: installing twice would report each
+ * call twice, so the second call is a no-op.
+ */
+export declare function enableApiTracking(enabled?: boolean): void;
+/** Whether the wrappers are currently in place. */
+export declare function isApiTrackingEnabled(): boolean;