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

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

@@ -0,0 +1,199 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { warnAlways } from '../core/logger.js';
+
+/**
+ * Which API calls are recorded, and under what name: Android's AppticsApiTracker.configure, built
+ * with ApiTrackingBuilder the way user properties are built with UserBuilder:
+ *
+ *   configureApiTracking(new ApiTrackingBuilder()
+ *       .allowRegex(/^https:\/\/api\.zylker\.(com|in)\//)
+ *       .ignoreEquals('https://api.zylker.com/health')
+ *       .ignoreRegex(/\/internal\//)
+ *       .build());
+ *
+ * Four rules, two kinds by two: an exact URL (equals) or a regular expression (regex), to allow or
+ * to ignore. Each is tried on the call's URL as `scheme://host[:port]/path`, with its query and
+ * fragment removed, so one rule can name a host, a path or a single endpoint. Ignore rules are
+ * tried first and always win; then, when there are allow rules, a call must match one of them.
+ *
+ * The name a call is recorded under is not configured: the query goes, and numeric ids, UUIDs and
+ * JWTs in its path become `*`, so `/users/42/orders` and `/users/43/orders` are one endpoint.
+ *
+ * Both apply to every call, the ones the fetch/XHR wrappers catch and the ones the app reports
+ * with startTrackApi(), so one set of rules decides what the API page shows.
+ */
+function emptyConfig() {
+    return { allowEquals: [], ignoreEquals: [], allowRegex: [], ignoreRegex: [] };
+}
+/**
+ * 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.
+ */
+function ruleUrl(raw) {
+    try {
+        var url = new URL(String(raw).trim());
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') { // no i18n
+            return ''; // no i18n
+        }
+        var path = url.pathname.length > 1 ? url.pathname.replace(/\/+$/, '') : url.pathname; // no i18n
+        return url.protocol + '//' + url.host.toLowerCase() + path; // no i18n
+    }
+    catch (err) {
+        return ''; // no i18n
+    }
+}
+/** The exact URLs given, as rules compare them; anything that is not an absolute URL is refused, and said. */
+function cleanUrls(method, values) {
+    var out = [];
+    values.forEach(function (value) {
+        var url = typeof value === 'string' ? ruleUrl(value) : ''; // no i18n
+        if (url === '') { // no i18n
+            warnAlways('ApiTrackingBuilder.' + method + ': ' + JSON.stringify(value) + ' is not a full http(s) URL, as https://api.example.com/health, and is left out'); // no i18n
+            return;
+        }
+        if (out.indexOf(url) === -1) {
+            out.push(url);
+        }
+    });
+    return out;
+}
+/** The regular expressions given, a RegExp or its source as a string; an invalid one is refused, and said. */
+function cleanRegexes(method, values) {
+    var out = [];
+    values.forEach(function (value) {
+        if (value instanceof RegExp) {
+            out.push(value);
+            return;
+        }
+        if (typeof value === 'string' && value !== '') { // no i18n
+            try {
+                out.push(new RegExp(value));
+                return;
+            }
+            catch (err) {
+                // falls through to the warning
+            }
+        }
+        warnAlways('ApiTrackingBuilder.' + method + ': ' + String(value) + ' is not a regular expression, and is left out'); // no i18n
+    });
+    return out;
+}
+/**
+ * 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()`.
+ */
+class ApiTrackingBuilder {
+    constructor() {
+        this.rules = emptyConfig();
+    }
+    /** Records only these URLs (and those any allowRegex matches): `https://api.example.com/orders`. */
+    allowEquals(...urls) { this.rules.allowEquals.push(...cleanUrls('allowEquals', urls)); return this; }
+    /** Never records these URLs: `https://api.example.com/health`. */
+    ignoreEquals(...urls) { this.rules.ignoreEquals.push(...cleanUrls('ignoreEquals', urls)); return this; }
+    /** Records only URLs these match (and those any allowEquals names): `/^https:\/\/api\.example\.com\//`. */
+    allowRegex(...patterns) { this.rules.allowRegex.push(...cleanRegexes('allowRegex', patterns)); return this; }
+    /** Never records URLs these match: `/\/internal\//`. */
+    ignoreRegex(...patterns) { this.rules.ignoreRegex.push(...cleanRegexes('ignoreRegex', patterns)); return this; }
+    build() {
+        return {
+            allowEquals: this.rules.allowEquals.slice(),
+            ignoreEquals: this.rules.ignoreEquals.slice(),
+            allowRegex: this.rules.allowRegex.slice(),
+            ignoreRegex: this.rules.ignoreRegex.slice(),
+        };
+    }
+}
+/**
+ * 2.0.0-beta's builder methods, now gone. Called, each throws a TypeError that names what to use
+ * instead: a rule silently missing would record what the app meant to leave out.
+ */
+const RETIRED_METHODS = Object.freeze({
+    ignoreDomains: 'ignoreRegex', // no i18n
+    allowOnlyDomains: 'allowRegex', // no i18n
+    allowOnlyTLDs: 'allowRegex', // no i18n
+    ignoreTLDs: 'ignoreRegex', // no i18n
+    ignoreDomainPrefixes: 'ignoreRegex', // no i18n
+    ignoreDomainSuffixes: 'ignoreRegex', // no i18n
+    groupDomains: '', // no i18n
+    ignoreEndpoint: 'ignoreEquals or ignoreRegex', // no i18n
+    addPattern: '', // no i18n
+    preserveSegments: '', // no i18n
+    autoDetection: '', // no i18n
+});
+Object.keys(RETIRED_METHODS).forEach(function (name) {
+    Object.defineProperty(ApiTrackingBuilder.prototype, name, {
+        configurable: true,
+        value: function () {
+            var instead = RETIRED_METHODS[name];
+            throw new TypeError('ApiTrackingBuilder.' + name + '() is no longer supported: ' // no i18n
+                + (instead ? 'use ' + instead + ', which match the URL without its query' : 'ids, UUIDs and tokens in a path become * on their own')); // no i18n
+        },
+    });
+});
+var current = emptyConfig();
+/** The values of `list` that are of the kind `keep` accepts. */
+function listOf(value, keep) {
+    return Array.isArray(value) ? value.filter(keep) : [];
+}
+/**
+ * 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);
+    if (!built || typeof built !== 'object') { // no i18n
+        current = emptyConfig();
+        return;
+    }
+    var isString = function (one) { return typeof one === 'string'; }; // no i18n
+    var isRegExp = function (one) { return one instanceof RegExp; };
+    current = {
+        // a hand-written object gets the same clean-up the builder gives
+        allowEquals: cleanUrls('allowEquals', listOf(built.allowEquals, isString)), // no i18n
+        ignoreEquals: cleanUrls('ignoreEquals', listOf(built.ignoreEquals, isString)), // no i18n
+        allowRegex: listOf(built.allowRegex, isRegExp).concat(cleanRegexes('allowRegex', listOf(built.allowRegex, isString))), // no i18n
+        ignoreRegex: listOf(built.ignoreRegex, isRegExp).concat(cleanRegexes('ignoreRegex', listOf(built.ignoreRegex, isString))), // no i18n
+    };
+}
+/** Whether a regular expression matches, whatever its flags: a /g one keeps a position between tests. */
+function regexMatches(re, url) {
+    re.lastIndex = 0;
+    return re.test(url);
+}
+/**
+ * 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.
+ */
+function urlTracked(url) {
+    var target = ruleUrl(url);
+    if (target === '') { // no i18n
+        return false;
+    }
+    if (current.ignoreEquals.indexOf(target) !== -1 || current.ignoreRegex.some(function (re) { return regexMatches(re, target); })) {
+        return false;
+    }
+    if (current.allowEquals.length === 0 && current.allowRegex.length === 0) {
+        return true;
+    }
+    return current.allowEquals.indexOf(target) !== -1 || current.allowRegex.some(function (re) { return regexMatches(re, target); });
+}
+/* ---------------- the name a call is recorded under ---------------- */
+/** 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
+}
+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, and numeric ids, UUIDs and JWTs become `*`. */
+function normalizeApiPath(path) {
+    return withoutQuery(path).split('/').map(function (segment) {
+        return segment !== '' && (NUMERIC.test(segment) || UUID.test(segment) || JWT.test(segment)) ? '*' : segment; // no i18n
+    }).join('/'); // no i18n
+}
+
+export { ApiTrackingBuilder, configureApiTracking, normalizeApiPath, ruleUrl, urlTracked, 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;

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

@@ -0,0 +1,198 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { _ZAP, getConfig } from '../core/state.js';
+import { Console } from '../core/logger.js';
+import { nowMs, isEmpty } from '../core/utils.js';
+import { trackApi } from './track.js';
+import { urlTracked } from './api-rules.js';
+
+/**
+ * Automatic API tracking: wraps XMLHttpRequest and fetch so calls the app makes are recorded
+ * without it calling startTrackApi() / endTrackApi() itself.
+ *
+ * Two rules shape everything here. The wrappers must be invisible — return values, `this`, thrown
+ * errors and argument forms all pass straight through, because a mistake in this file breaks the
+ * host app's networking rather than just losing a metric. And the SDK's own traffic must never be
+ * recorded: engagement/add reports API calls, so tracking it would have each batch produce the
+ * items for the next one.
+ *
+ * Off unless `track_api` is set. Hostnames and paths of every request an app makes is a wider
+ * grant than events and screens, so it is the app's decision, not a default.
+ */
+var installed = false;
+var originalOpen = null;
+var originalSend = null;
+var originalFetch = null;
+/**
+ * Whether a request is the SDK's own, which is never reported: engagement/add carries API items, so
+ * recording it would have every batch produce the items for the next one, forever.
+ *
+ * Two checks, because one is not enough to bet a loop on. The host comparison is a prefix match, so
+ * it misses if the host is spelled differently in the request than in serviceUrl — a trailing
+ * slash is enough. The path check catches those, since every SDK call sits under the configured
+ * endpoint whatever host it goes to, including through a same-origin proxy.
+ */
+function isOwnRequest(url, pathname) {
+    var own = [_ZAP._defaultoptions.base_domain, _ZAP._defaultoptions.serviceUrl];
+    for (var i = 0; i < own.length; i++) {
+        if (!isEmpty(own[i]) && url.indexOf(own[i]) === 0) {
+            return true;
+        }
+    }
+    var endpoint = getConfig('endpoint');
+    return !isEmpty(endpoint) && pathname.indexOf(endpoint) === 0;
+}
+/**
+ * Whether one URL is ours to report: an http(s) call, not the SDK's own, and one the
+ * configureApiTracking rules let through. Anything unparseable is skipped rather than guessed at.
+ */
+function shouldTrack(rawUrl) {
+    if (isEmpty(rawUrl)) {
+        return false;
+    }
+    var absolute;
+    try {
+        absolute = new URL(rawUrl, window.location.href);
+    }
+    catch (err) {
+        return false;
+    }
+    if (absolute.protocol !== 'https:' && absolute.protocol !== 'http:') { // no i18n
+        return false; // data:, blob:, chrome-extension: and friends
+    }
+    if (isOwnRequest(absolute.href, absolute.pathname)) {
+        return false;
+    }
+    // configureApiTracking's rules: checked here too so a call left out is not even timed. trackApi checks them again, for the
+    // calls an app reports itself
+    return urlTracked(absolute.href);
+}
+/** One finished call. Never throws: a tracking failure must not surface in the app's call. */
+function record(method, url, starttime, responsecode, responsemessage) {
+    try {
+        trackApi({
+            url: url,
+            method: method,
+            responsecode: responsecode,
+            responsemessage: responsemessage,
+            starttime: starttime,
+            endtime: nowMs(),
+        });
+    }
+    catch (err) {
+        Console.log('auto api tracking: ' + String(err)); // no i18n
+    }
+}
+/** The url of any of fetch's three first-argument forms. */
+function fetchUrl(input) {
+    if (typeof input === 'string') { // no i18n
+        return input;
+    }
+    if (typeof Request !== 'undefined' && input instanceof Request) { // no i18n
+        return input.url;
+    }
+    return String(input);
+}
+function fetchMethod(input, init) {
+    if (init && init.method) {
+        return init.method;
+    }
+    if (typeof Request !== 'undefined' && input instanceof Request) { // no i18n
+        return input.method;
+    }
+    return 'GET'; // no i18n
+}
+function installXhr() {
+    if (typeof XMLHttpRequest !== 'function') { // no i18n
+        return;
+    }
+    originalOpen = XMLHttpRequest.prototype.open;
+    originalSend = XMLHttpRequest.prototype.send;
+    XMLHttpRequest.prototype.open = function (method, url) {
+        try {
+            var href = String(url);
+            if (shouldTrack(href)) {
+                // starttime is set in send(): open() may happen long before the call goes out
+                this._ap_api = { method: String(method || 'GET'), url: href, starttime: 0 }; // no i18n
+            }
+            else {
+                this._ap_api = undefined;
+            }
+        }
+        catch (err) {
+            this._ap_api = undefined;
+        }
+        return originalOpen.apply(this, arguments);
+    };
+    XMLHttpRequest.prototype.send = function () {
+        const tracked = this._ap_api;
+        if (tracked) {
+            tracked.starttime = nowMs();
+            // loadend fires for success, error, abort and timeout alike, so one listener covers
+            // every ending; status 0 is how a network failure arrives here
+            this.addEventListener('loadend', function () {
+                var message = this.status === 0 ? 'Network Error' : (this.statusText || '-'); // no i18n
+                record(tracked.method, tracked.url, tracked.starttime, this.status, message);
+            });
+        }
+        return originalSend.apply(this, arguments);
+    };
+}
+function installFetch() {
+    if (typeof fetch !== 'function') { // no i18n
+        return;
+    }
+    originalFetch = fetch;
+    window.fetch = function (input, init) {
+        var url, method, starttime;
+        try {
+            url = fetchUrl(input);
+            method = fetchMethod(input, init);
+            starttime = nowMs();
+        }
+        catch (err) {
+            return originalFetch(input, init);
+        }
+        if (!shouldTrack(url)) {
+            return originalFetch(input, init);
+        }
+        return originalFetch(input, init).then(function (response) {
+            record(method, url, starttime, response.status, response.statusText || '-'); // no i18n
+            return response;
+        }, function (err) {
+            // a rejected fetch never reached a status; the rejection is re-thrown untouched
+            record(method, url, starttime, 0, String(err && err.message ? err.message : err) || 'Network Error'); // no i18n
+            throw err;
+        });
+    };
+}
+/**
+ * Starts or stops automatic tracking. Safe to call repeatedly: installing twice would report each
+ * call twice, so the second call is a no-op.
+ */
+function enableApiTracking(enabled) {
+    var on = typeof enabled === 'boolean' ? enabled : true; // no i18n
+    if (on === installed) {
+        return;
+    }
+    if (on) {
+        installXhr();
+        installFetch();
+        installed = true;
+        Console.log('automatic api tracking: on'); // no i18n
+        return;
+    }
+    if (originalOpen) {
+        XMLHttpRequest.prototype.open = originalOpen;
+    }
+    if (originalSend) {
+        XMLHttpRequest.prototype.send = originalSend;
+    }
+    if (originalFetch) {
+        window.fetch = originalFetch;
+    }
+    originalOpen = originalSend = originalFetch = null;
+    installed = false;
+    Console.log('automatic api tracking: off'); // no i18n
+}
+
+export { enableApiTracking };

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

@@ -0,0 +1,18 @@
+/** A path as screen_routes compares it: no query or fragment, no trailing slash but on the root. */
+export declare function routePath(path: string): string;
+/**
+ * Starts or stops automatic screen tracking. Starting records the screen the page is on, unless
+ * the app has already called inScreen() for it. Safe to call repeatedly: wrapping history twice
+ * would check every navigation twice, so a second start does nothing. `wait` replaces SETTLE_MS,
+ * for tests.
+ */
+export declare function enableScreenTracking(enabled?: boolean, wait?: number): void;
+/**
+ * The name automatic tracking gives the page as it is now: the cleaned path. For records that
+ * need a screen when none has been
+ * tracked — heatmaps with `track_screen: false` and no inScreen() call, say. '' when the page
+ * has no name.
+ */
+export declare function automaticScreenName(): string;
+/** Whether history is being watched right now. */
+export declare function isScreenTrackingEnabled(): boolean;