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

package/dist/esm/core/validate.js

@@ -0,0 +1,226 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { Console } from './logger.js';
+import { isEmpty, isEmptyObj } from './utils.js';
+
+/**
+ * `ap_` / `AP_` begins the names of Apptics' own defined events and properties (DefinedEvents), so
+ * an app's event, group or property key may not, as on Android: one that does is not logged.
+ */
+const RESERVED_PREFIX = /^ap_/i;
+function validateEventOrGroup(str) {
+    if (!str || str === '') { // no i18n
+        Console.warn('validateEventOrGroup: Invalid event or group name'); // no i18n
+        return false;
+    }
+    // a letter, then up to 99 letters, digits or _, and not the reserved ap_ prefix
+    const pattern = /^[a-zA-Z][a-zA-Z0-9_]{0,99}$/;
+    if (RESERVED_PREFIX.test(str)) {
+        Console.warn('validateEventOrGroup: "' + str + '" starts with ap_, which is reserved for defined events'); // no i18n
+        return false;
+    }
+    return pattern.test(str);
+}
+/** A property key: a letter, then up to 49 letters, digits or _, and not the reserved ap_ prefix. */
+const PROPERTY_KEY = /^[a-zA-Z][a-zA-Z0-9_]{0,49}$/;
+/** At most this many properties on one event, screen or error. */
+const MAX_PROPERTIES = 24;
+/** At most this many characters of properties in all, as the payload carries them. */
+const MAX_PROPERTIES_LENGTH = 7666;
+/** At most this many characters in one value. */
+const MAX_VALUE_LENGTH = 250;
+/**
+ * A value as the payload carries it, with its type. Numbers are Number and booleans Boolean, sent
+ * as 1 and 0 — the form the server has always received a Boolean in. Anything else (an object, an
+ * array, null) is turned into text, as on Android, rather than dropped.
+ */
+function typedValue(value) {
+    if (typeof value === 'number' && isFinite(value)) { // no i18n
+        return { value: value, type: 'Number' }; // no i18n
+    }
+    if (typeof value === 'boolean') { // no i18n
+        return { value: value ? 1 : 0, type: 'Boolean' }; // no i18n
+    }
+    if (typeof value === 'string') { // no i18n
+        return { value: value, type: 'String' }; // no i18n
+    }
+    var text;
+    try {
+        text = value === undefined ? 'undefined' : JSON.stringify(value); // no i18n
+    }
+    catch (err) {
+        text = String(value);
+    }
+    return { value: text === undefined ? String(value) : text, type: 'String' }; // no i18n
+}
+/**
+ * Event, screen and error properties as the payload carries them: `{ data, datatype, isvalid }`.
+ *
+ * Each property is judged on its own, as on Android: a bad key (wrong characters, too long, the
+ * reserved ap_ prefix) or a value over 250 characters drops that property, and the rest are kept
+ * and the event is still logged. Past 24 properties, or 7,666 characters in all, the later ones are
+ * dropped. When nothing valid is left the result says why, in the shape the server has always taken
+ * for a refused set: `{ isvalid: false, message: { code, keys, valuekeys } }`.
+ */
+function validateJSON(jsonObj) {
+    if (isEmpty(jsonObj) || isEmptyObj(jsonObj)) {
+        return {};
+    }
+    var obj = jsonObj;
+    var data = {};
+    var datatype = {};
+    var codes = [];
+    var badKeys = [];
+    var longKeys = [];
+    function note(code) {
+        if (codes.indexOf(code) === -1) {
+            codes.push(code);
+        }
+    }
+    Object.keys(obj).forEach(function (key) {
+        if (!PROPERTY_KEY.test(key) || RESERVED_PREFIX.test(key)) {
+            Console.warn('validateJSON: dropped the property \'' + key + '\': a key is a letter, then up to 49 letters, digits or _, and not ap_'); // no i18n
+            badKeys.push(key.substring(0, 50));
+            note(103);
+            return;
+        }
+        var typed = typedValue(obj[key]);
+        if (String(typed.value).length > MAX_VALUE_LENGTH) {
+            Console.warn('validateJSON: dropped the property \'' + key + '\': its value is longer than ' + MAX_VALUE_LENGTH + ' characters'); // no i18n
+            longKeys.push(key);
+            note(104);
+            return;
+        }
+        if (Object.keys(data).length >= MAX_PROPERTIES) {
+            Console.warn('validateJSON: dropped the property \'' + key + '\': at most ' + MAX_PROPERTIES + ' properties'); // no i18n
+            note(102);
+            return;
+        }
+        var withIt = Object.assign({}, data);
+        withIt[key] = typed.value;
+        if (JSON.stringify(withIt).length > MAX_PROPERTIES_LENGTH) {
+            Console.warn('validateJSON: dropped the property \'' + key + '\': properties are at most ' + MAX_PROPERTIES_LENGTH + ' characters in all'); // no i18n
+            note(101);
+            return;
+        }
+        data[key] = typed.value;
+        datatype[key] = typed.type;
+    });
+    if (Object.keys(data).length > 0) {
+        return { data: data, datatype: datatype, isvalid: true };
+    }
+    if (codes.length === 0) {
+        return {};
+    }
+    return { isvalid: false, message: { code: codes, keys: badKeys, valuekeys: longKeys } };
+}
+/** user/register accepts at most 10000 characters of body (max-len on its inputstream). */
+const USER_PROPERTIES_MAX_LENGTH = 10000;
+/** user/register accepts at most this many user properties. */
+const USER_PROPERTIES_MAX_COUNT = 45;
+function userValidateJSON(obj) {
+    const data = {};
+    const datatype = {};
+    const message = [];
+    const errorMap = { 101: [], 102: [], 103: [], 104: [] };
+    const keyRegex = /^[a-zA-Z][a-zA-Z0-9_]{0,49}$/;
+    const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+    let propCount = 0;
+    // Main fields and their validation
+    const stringFields = [
+        'first_name', 'last_name', 'company_name', 'contact_number', 'country', 'region', 'city', 'geo_location', 'gender', 'plan_type', 'timezone', 'language'
+    ]; // no i18n
+    const emailField = 'email_address'; // no i18n
+    const numberFields = ['engagement_score', 'date_of_birth']; // no i18n
+    for (const [key, value] of Object.entries(obj)) {
+        propCount++;
+        // Key validation
+        if (typeof key !== 'string' || key.length > 50 || !keyRegex.test(key)) { // no i18n
+            errorMap[103].push(key);
+            continue;
+        }
+        // String fields
+        if (stringFields.includes(key)) {
+            if (typeof value !== 'string' || value.length > 255) { // no i18n
+                errorMap[103].push(key);
+                continue;
+            }
+            data[key] = value;
+            datatype[key] = 'String'; // no i18n
+            continue;
+        }
+        // Email field
+        if (key === emailField) {
+            if (typeof value !== 'string' || value.length > 255 || !emailRegex.test(value)) { // no i18n
+                errorMap[103].push(key);
+                continue;
+            }
+            data[key] = value;
+            datatype[key] = 'String'; // no i18n
+            continue;
+        }
+        // Number fields (engagement_score)
+        if (numberFields.includes(key)) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) { // no i18n
+                errorMap[103].push(key);
+                continue;
+            }
+            data[key] = value;
+            datatype[key] = 'Number'; // no i18n
+            continue;
+        }
+        // Custom properties: key must be string, value must be Boolean, String (≤255), or Number (finite)
+        if (typeof value === 'boolean') { // no i18n
+            data[key] = value;
+            datatype[key] = 'Boolean'; // no i18n
+        }
+        else if (typeof value === 'string') { // no i18n
+            if (value.length > 255) {
+                errorMap[103].push(key);
+                continue;
+            }
+            data[key] = value;
+            datatype[key] = 'String'; // no i18n
+        }
+        else if (typeof value === 'number') { // no i18n
+            if (!Number.isFinite(value)) {
+                errorMap[104].push(key);
+                continue;
+            }
+            data[key] = value;
+            datatype[key] = 'Number'; // no i18n
+        }
+        else {
+            errorMap[104].push(key);
+            continue;
+        }
+    }
+    // Property count validation
+    if (propCount > USER_PROPERTIES_MAX_COUNT) {
+        errorMap[102] = Object.keys(obj);
+    }
+    // Total length validation: the payload carries data and datatype, so both are counted
+    const jsonLength = JSON.stringify(data).length + JSON.stringify(datatype).length;
+    if (jsonLength > USER_PROPERTIES_MAX_LENGTH) {
+        errorMap[101] = Object.keys(obj);
+    }
+    // Prepare message array with error_type
+    for (const code of [101, 102, 103, 104]) {
+        if (errorMap[code].length > 0) {
+            message.push({ code, keys: errorMap[code] });
+        }
+    }
+    return { data, datatype, message };
+}
+function validateScreenName(str) {
+    if (!str || str === '') { // no i18n
+        Console.warn('validateScreenName: Invalid screenName'); // no i18n
+        return false;
+    }
+    // Define the regular expression pattern
+    //^[a-zA-Z][\\w\\s]{1,100}$
+    const pattern = /^[\w\s.\-_&/:*]{0,99}$/;
+    // Test if the string matches the pattern
+    return pattern.test(str);
+}
+
+export { USER_PROPERTIES_MAX_COUNT, USER_PROPERTIES_MAX_LENGTH, userValidateJSON, validateEventOrGroup, validateJSON, validateScreenName };

package/dist/esm/device/appversion.d.ts

@@ -0,0 +1,15 @@
+/** Whether we already hold usable ids for the app and version running now. */
+export declare function hasAppVersion(): boolean;
+export declare function appVersionFailedForNetwork(): boolean;
+export declare function registerAppVersion(): Promise<boolean>;
+/**
+ * Puts the stored ids back on `_ZAP._device_info`.
+ *
+ * checkAndUpdateDeviceInfo rebuilds that object from scratch on every start, which would drop
+ * what registration put there. Called from inside that rebuild, so the ids survive it.
+ */
+export declare function applyStoredAppVersion(): void;
+/** Forgets the stored ids. reset() calls it, so the next start registers from scratch. */
+export declare function clearAppVersion(): void;
+/** The url this call goes to, for logging and tests. */
+export declare function appVersionUrl(): string;

package/dist/esm/device/appversion.js

@@ -0,0 +1,164 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { _ZAP } from '../core/state.js';
+import { Console, warnAlways } from '../core/logger.js';
+import { isEmpty, isSuccess } from '../core/utils.js';
+import { user_defaults } from '../core/storage.js';
+import { postToApptics, getHeaderParams } from '../core/transport.js';
+
+/**
+ * app/addversion — the first call the SDK makes, and the one everything else waits for.
+ *
+ * It is called with only what init() was given — zak, identifier and appversion — and registers
+ * this build with the platform. It answers with the ids every later call needs: aaid, the portal
+ * and project ids that form every other url, apid and mapid that authenticate the requests, and
+ * appversionid and appreleaseversionid that go in every payload's `meta`. metaWebSDKV2 declares all ten of its fields mandatory, so without this
+ * call v2 engagement, exception and log requests are refused outright.
+ *
+ * It is throttled at ten calls a minute per identifier+platform+version, so the answer is stored
+ * and reused: a returning visitor on the same build does not call it again. A changed appversion
+ * is a different build and does call it again, which is the point of the endpoint.
+ */
+const LABEL = 'registerAppVersion'; // no i18n
+/** Where the answer is kept between visits. */
+const STORE_KEY = 'app_version_info'; // no i18n
+/** The ids this call is the only source of. Everything else flows from them. */
+const RESULT_KEYS = ['apid', 'mapid', 'aaid', 'appversionid', 'appreleaseversionid', 'platformid', 'projectid', 'portalid']; // no i18n
+var inFlight = null;
+/** The stored answer, if this exact build already registered. */
+function stored() {
+    var saved = user_defaults.item(STORE_KEY);
+    return saved && typeof saved === 'object' ? saved : {};
+}
+/**
+ * The ids without which no later url can be built or authenticated. portalid and projectid are
+ * the two path segments of every v2 url but this one; aaid names the app.
+ */
+const REQUIRED_KEYS = ['aaid', 'portalid', 'projectid', 'apid', 'mapid', 'appversionid']; // no i18n
+function missingKeys(data) {
+    return REQUIRED_KEYS.filter(function (key) { return isEmpty(data[key]); });
+}
+/** Whether we already hold usable ids for the app and version running now. */
+function hasAppVersion() {
+    var saved = stored();
+    return missingKeys(saved).length === 0
+        && saved.appversion === _ZAP._defaultoptions.appversion
+        && saved.identifier === _ZAP._defaultoptions.identifier
+        && saved.serviceUrl === _ZAP._defaultoptions.serviceUrl;
+}
+/** Puts the ids where the rest of the SDK reads them from. */
+function apply(data) {
+    RESULT_KEYS.forEach(function (key) {
+        if (!isEmpty(data[key])) {
+            _ZAP._device_info[key] = data[key];
+        }
+    });
+    // the app and the org/project segments of every url come from here, not from init().
+    // The server sends portalid as a string and projectid as a number; both become url text
+    if (!isEmpty(data.aaid)) {
+        _ZAP._defaultoptions.aaid = data.aaid;
+    }
+    if (!isEmpty(data.portalid)) {
+        _ZAP._defaultoptions.zsoid = String(data.portalid);
+    }
+    if (!isEmpty(data.projectid)) {
+        _ZAP._defaultoptions.projectID = String(data.projectid);
+    }
+    // apid and mapid are also read straight off state for the request headers. The server
+    // answers with numbers, and a header value is a string
+    if (!isEmpty(data.apid)) {
+        _ZAP._apid = String(data.apid);
+    }
+    if (!isEmpty(data.mapid)) {
+        _ZAP._mapid = String(data.mapid);
+    }
+}
+/**
+ * Registers this build, or reuses the stored answer.
+ *
+ * Resolves true when the ids are in place, false when they are not — the caller stops there
+ * rather than carrying on to calls that would be refused for missing them.
+ */
+/**
+ * Whether the last registration failed for want of a network (offline, a dropped connection, a
+ * timeout) rather than because the server answered no. Only the first is worth trying again.
+ */
+var failedForNetwork = false;
+function appVersionFailedForNetwork() {
+    return failedForNetwork;
+}
+function registerAppVersion() {
+    failedForNetwork = false;
+    if (hasAppVersion()) {
+        apply(stored());
+        Console.log(LABEL + ': reusing the ids stored for ' + _ZAP._defaultoptions.appversion); // no i18n
+        return Promise.resolve(true);
+    }
+    // a second caller joins the first rather than spending another of the ten calls a minute
+    if (inFlight !== null) {
+        return inFlight;
+    }
+    var frameworkid = !isEmpty(_ZAP._device_info.frameworkid) ? _ZAP._device_info.frameworkid : _ZAP._frameworkID;
+    if (frameworkid === 0) {
+        // a build made without npm pack: it still runs, but the server has no record of this SDK
+        warnAlways(LABEL + ': this build has no registered framework id; build the package with npm pack'); // no i18n
+    }
+    if (isEmpty(frameworkid) || isEmpty(_ZAP._defaultoptions.identifier) || isEmpty(_ZAP._defaultoptions.zak)) {
+        warnAlways(LABEL + ': need zak, an identifier and a frameworkid to register this app version'); // no i18n
+        return Promise.resolve(false);
+    }
+    inFlight = postToApptics('addversion', '', { zak: getHeaderParams('zak') }, LABEL) // no i18n
+        .then(function (result) {
+        if (!isSuccess(result) || !result.data) {
+            warnAlways(LABEL + ': the server did not return the app ids'); // no i18n
+            return false;
+        }
+        var data = result.data;
+        var missing = missingKeys(data);
+        if (missing.length > 0) {
+            warnAlways(LABEL + ': the answer has no ' + missing.join(', ')); // no i18n
+            return false;
+        }
+        apply(data);
+        // stored against the app and version it describes, so a new build registers again
+        var keep = {
+            appversion: _ZAP._defaultoptions.appversion,
+            identifier: _ZAP._defaultoptions.identifier,
+            serviceUrl: _ZAP._defaultoptions.serviceUrl,
+        };
+        RESULT_KEYS.forEach(function (key) {
+            if (!isEmpty(data[key])) {
+                keep[key] = data[key];
+            }
+        });
+        user_defaults.add(STORE_KEY, keep);
+        Console.log(LABEL + ': registered ' + _ZAP._defaultoptions.appversion + ' as apid ' + data.apid); // no i18n
+        return true;
+    })
+        .catch(function (err) {
+        // a server answer carries serverResult; a request that never got one does not
+        failedForNetwork = !(err && err.serverResult) || navigator.onLine === false;
+        warnAlways(LABEL + ': could not register this app version: ' + String(err && err.message ? err.message : err)); // no i18n
+        return false;
+    })
+        .then(function (ok) {
+        inFlight = null;
+        return ok;
+    });
+    return inFlight;
+}
+/**
+ * Puts the stored ids back on `_ZAP._device_info`.
+ *
+ * checkAndUpdateDeviceInfo rebuilds that object from scratch on every start, which would drop
+ * what registration put there. Called from inside that rebuild, so the ids survive it.
+ */
+function applyStoredAppVersion() {
+    apply(stored());
+}
+/** Forgets the stored ids. reset() calls it, so the next start registers from scratch. */
+function clearAppVersion() {
+    inFlight = null;
+    user_defaults.add(STORE_KEY, undefined);
+}
+
+export { appVersionFailedForNetwork, applyStoredAppVersion, clearAppVersion, hasAppVersion, registerAppVersion };

package/dist/esm/device/index.d.ts

@@ -0,0 +1,34 @@
+import type { DeviceInfo, Dict, ServerResult } from '../types.js';
+export declare function checkAndUpdateDeviceInfo(): void;
+export declare function addOrUpdateDeviceID(device_info: DeviceInfo, previous?: DeviceInfo): void;
+/**
+ * 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.
+ */
+export declare function prepareDevice(): Promise<void>;
+/** True while the device has no server ids, so nothing can be sent yet. */
+export declare function needsDevice(): boolean;
+/**
+ * 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.
+ */
+export declare function deviceReady(): Promise<void>;
+export declare function registerDeviceWithApptics(): Promise<ServerResult | DeviceInfo>;
+export declare function updateDeviceWithApptics(device_info: DeviceInfo): Promise<ServerResult>;
+export declare function getUpdatesFromServer(): Promise<Dict>;
+/**
+ * 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.
+ */
+export declare function restoreServerSettings(): void;
+/**
+ * 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.
+ */
+export declare function refreshServerSettings(): void;