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

package/dist/esm/remoteconfig/fetch.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 */
 import { SDK_MODULE } from '../core/constants.js';
 import { hooks } from '../core/hooks.js';
 import { _ZAP } from '../core/state.js';
@@ -7,8 +7,8 @@ import { nowMs } from '../core/utils.js';
 import { rejectIfOffline, rejectIfNoDeviceIds, postToApptics, apiHeaders } from '../core/transport.js';
 import { deviceReady } from '../device/index.js';
 import { ready } from '../lifecycle.js';
-import { reresolve, clearRemoteConfig, store, storeUnchanged, flagtime } from './store.js';
 import { clearCustomConditionValues } from './custom.js';
+import { store, merge, storeUnchanged, flagtime, reresolve, clearRemoteConfig } from './store.js';
 
 /**
  * The getupdates call.
@@ -28,20 +28,28 @@ const LABEL = 'AppticsRemoteConfig'; // no i18n
 /** getupdatesobj caps moduleids at nine entries; this SDK asks about one. */
 const MODULES = [Number(SDK_MODULE.REMOTE_CONFIG)];
 var inFlight = null;
+/** Whether the request in flight asked with flagtime 0, which a cold fetch can join. */
+var inFlightWhole = false;
 /** Bumped by reset(); an answer to a request made before it is not stored. */
 var generation = 0;
 /**
- * How long a fetch that succeeded on this page answers for later ones, as on Android: a value
- * read on every render must not be a request on every render. coldFetch skips it.
+ * When getupdates is asked again, after the first of a page load: every POLL_MS. Coming back to
+ * the tab asks nothing; the poll's timer carries on. fetchValue() and fetchValues() never ask
+ * themselves once a fetch has succeeded: a value read on every render must not be a request on
+ * every render.
+ */
+const POLL_MS = 3 * 60 * 1000;
+/**
+ * coldFetch goes to the network every time, so it is limited: three in any minute, as on Android.
+ * One past that is answered from the values this page already has.
  */
-const CACHE_MS = 5 * 60 * 1000;
-/** coldFetch goes to the network every time, so it is limited: three in any minute, as on Android. */
 const COLD_LIMIT = 3;
 const COLD_WINDOW_MS = 60 * 1000;
-/** When a fetch on this page last succeeded; 0 until one has. */
+/** When a fetch on this page last succeeded; 0 until one has, and the next one sends flagtime 0. */
 var fetchedAt = 0;
 /** When the coldFetch calls of the last minute went out. */
 var coldCalls = [];
+var pollTimer = null;
 /**
  * Whether remote config is still worth asking about.
  *
@@ -61,11 +69,11 @@ function wanted() {
  * id for "macOS 15", not the small int this template types. languagecode is sent when there is
  * one, since safe_string cannot match an empty string.
  */
-function body() {
+function body(since) {
     var payload = {
         appversionid: String(_ZAP._device_info.appversionid || ''), // no i18n
         moduleids: MODULES,
-        flagtime: flagtime(),
+        flagtime: since,
     };
     var language = String(navigator.language || '').slice(0, 10); // no i18n
     if (language !== '') {
@@ -78,6 +86,9 @@ function body() {
  *
  * Only to stop asking: getsdkconfig decides whether the feature is on. A module reported off
  * here is dropped from the next request, which is what the API asks for.
+ *
+ * A report that differs from the last one (on until one says otherwise) means the server's
+ * settings changed, so getsdkconfig, which decides, is asked now rather than at its next check.
  */
 function applyReportedModules(data) {
     var status = data.tracking_status;
@@ -86,20 +97,35 @@ function applyReportedModules(data) {
     }
     var entry = status[SDK_MODULE.REMOTE_CONFIG];
     if (entry && typeof entry === 'object') {
-        _ZAP._remoteConfigReported = entry.enabled !== false;
+        var reported = entry.enabled !== false;
+        var changed = reported !== _ZAP._remoteConfigReported;
+        _ZAP._remoteConfigReported = reported;
+        if (changed) {
+            Console.log(LABEL + ': getupdates reported the module ' + (reported ? 'on' : 'off') + ', asking getsdkconfig'); // no i18n
+            hooks.askServerSettings();
+        }
     }
 }
 /**
- * Asks for the rule set, if anything has changed since the last one.
+ * Asks for the rule set: the whole of it with flagtime 0 on the first fetch of a page load, then
+ * only what changed since the last answered request, which is merged into what is stored.
+ *
+ * Resolves with the answer, whether or not it carried a rule set — a later answer with no
+ * `remoteconfig` block means nothing has changed, which is the normal case and not a failure.
  *
- * Resolves with the parameters as they stand afterwards, whether or not the answer carried a new
- * rule set — an answer with no `remoteconfig` block means nothing has changed, which is the
- * normal case and not a failure.
+ * With `whole`, a cold fetch: flagtime 0 whatever this page has fetched already, and the answer
+ * replaces the stored set as the first fetch of a page load does.
  *
- * A second caller joins the first rather than making another request.
+ * A second caller joins the first rather than making another request. A cold fetch joins one
+ * only when it asked with flagtime 0 too, and otherwise asks once it has answered.
  */
-function fetchRemoteConfig() {
+function fetchRemoteConfig(whole) {
     if (inFlight !== null) {
+        if (whole === true && !inFlightWhole) {
+            return inFlight.catch(function () { return {}; }).then(function () {
+                return fetchRemoteConfig(true);
+            });
+        }
         return inFlight;
     }
     if (!wanted()) {
@@ -111,7 +137,11 @@ function fetchRemoteConfig() {
         return blocked;
     }
     var asked = generation;
-    var request = postToApptics('getupdates', body(), apiHeaders(), LABEL).then(function (result) {
+    // the first fetch of the page asks for everything; the stored set is a previous visit's
+    var askWhole = whole === true || fetchedAt === 0;
+    var since = askWhole ? 0 : flagtime();
+    var askedAt = nowMs();
+    var request = postToApptics('getupdates', body(since), apiHeaders(), LABEL).then(function (result) {
         var data = (result.data || {});
         if (asked !== generation) {
             // asked before a reset(): the answer is about the device and app that were just forgotten
@@ -119,15 +149,18 @@ function fetchRemoteConfig() {
         }
         applyReportedModules(data);
         var rules = data.remoteconfig;
-        var at = nowMs();
-        fetchedAt = at;
-        if (rules && typeof rules === 'object') {
-            store(rules, at);
+        fetchedAt = nowMs();
+        if (askWhole) {
+            // with flagtime 0 the answer is the whole set, and no block means there is nothing in it
+            store(rules && typeof rules === 'object' ? rules : {}, askedAt);
+        }
+        else if (rules && typeof rules === 'object') {
+            merge(rules, askedAt);
         }
         else {
             // nothing has changed since our flagtime, which is the answer most of the time
-            storeUnchanged(at);
-            Console.log(LABEL + ': no changes since ' + flagtime()); // no i18n
+            storeUnchanged(askedAt);
+            Console.log(LABEL + ': no changes since ' + since); // no i18n
         }
         return data;
     }).then(function (data) {
@@ -137,13 +170,19 @@ function fetchRemoteConfig() {
         settle();
         return Promise.reject(err);
     });
-    // a request reset() has disowned must not clear the in-flight slot of one made after it
+    // a request reset() has disowned must not clear the in-flight slot of one made after it, nor
+    // start the polling again
     function settle() {
         if (inFlight === request) {
             inFlight = null;
+            inFlightWhole = false;
+        }
+        if (asked === generation) {
+            schedulePoll();
         }
     }
     inFlight = request;
+    inFlightWhole = askWhole;
     return inFlight;
 }
 /**
@@ -153,16 +192,24 @@ function fetchRemoteConfig() {
 function resetRemoteConfig() {
     generation++;
     inFlight = null;
+    inFlightWhole = false;
     fetchedAt = 0;
     coldCalls = [];
+    if (pollTimer !== null) {
+        clearTimeout(pollTimer);
+        pollTimer = null;
+    }
     _ZAP._remoteConfigReported = true;
     clearCustomConditionValues();
     clearRemoteConfig();
 }
 /**
- * Makes sure the values are this page's own: from a fetch that just succeeded, or one within
- * CACHE_MS. Resolves true when they are, false when the fetch failed, could not be made, or was
- * past the coldFetch limit — the caller then decides whether stored values will do. Never rejects.
+ * Makes sure the values are this page's own: from a fetch on this page that succeeded, kept up to
+ * date by the polling after it. With `coldFetch`, a fetch with flagtime 0 now, whatever this page
+ * already has, whose answer replaces what is stored: at most COLD_LIMIT a minute, and one past
+ * that answers from what this page has. Resolves true when they are, false when the
+ * fetch failed or could not be made — the caller then decides whether stored values will do.
+ * Never rejects.
  *
  * Waits for start-up and for the device to be registered, which a first visit is still doing
  * when ready() resolves: getupdates is refused without the device ids.
@@ -172,20 +219,23 @@ function obtain(coldFetch) {
         if (!running) {
             return false;
         }
-        var now = nowMs();
-        if (coldFetch !== true && fetchedAt > 0 && now - fetchedAt < CACHE_MS) {
-            return true;
-        }
-        if (coldFetch === true) {
+        var cold = coldFetch === true;
+        if (cold) {
+            var now = nowMs();
             coldCalls = coldCalls.filter(function (at) { return now - at < COLD_WINDOW_MS; });
             if (coldCalls.length >= COLD_LIMIT) {
-                Console.warn(LABEL + ': coldFetch is limited to ' + COLD_LIMIT + ' a minute; this one is not sent'); // no i18n
-                return false;
+                Console.warn(LABEL + ': coldFetch is limited to ' + COLD_LIMIT + ' a minute; this one is answered from the values this page has'); // no i18n
+                cold = false;
+            }
+            else {
+                coldCalls.push(now);
             }
-            coldCalls.push(now);
+        }
+        if (fetchedAt > 0 && !cold) {
+            return true;
         }
         return deviceReady().then(function () {
-            return fetchRemoteConfig();
+            return fetchRemoteConfig(cold);
         }).then(function () {
             return true;
         }, function (err) {
@@ -194,13 +244,44 @@ function obtain(coldFetch) {
         });
     });
 }
-/** Start-up's own fetch, so values are this session's without the app asking. */
+/** A fetch for the polling: failures are logged, and the next tick tries again. */
+function refresh(reason) {
+    if (!_ZAP._ready) {
+        return;
+    }
+    Console.log(LABEL + ': asking for changes (' + reason + ')'); // no i18n
+    deviceReady().then(function () {
+        return fetchRemoteConfig();
+    }).catch(function (err) {
+        Console.log(LABEL + ': fetch failed: ' + String(err)); // no i18n
+    }).then(keepPolling);
+}
+/**
+ * A fetch that never went out (offline, the device not registered yet, the server switched it
+ * off) schedules nothing itself: the polling carries on regardless, so it picks up again.
+ */
+function keepPolling() {
+    if (_ZAP._ready && pollTimer === null && inFlight === null) {
+        schedulePoll();
+    }
+}
+/** The next poll, POLL_MS after the last fetch settled, answered or not. */
+function schedulePoll() {
+    if (pollTimer !== null) {
+        clearTimeout(pollTimer);
+    }
+    pollTimer = setTimeout(function () {
+        pollTimer = null;
+        refresh('every ' + POLL_MS + ' ms'); // no i18n
+    }, POLL_MS);
+}
+/** Start-up's own fetch, so values are this session's without the app asking, then the polling. */
 function fetchOnStart() {
-    obtain(false);
+    obtain().then(keepPolling);
 }
 hooks.resetRemoteConfig = resetRemoteConfig;
 hooks.remoteConfigStarted = fetchOnStart;
-// a condition on the customer group answers differently once AppticsSetUser has named one
+// a condition on the customer group answers differently once AppticsUser.setUser has named one
 hooks.remoteConfigUserChanged = reresolve;
 // imported after start-up has already finished (a lazy import, say): fetch now, as start-up would have
 if (_ZAP._ready) {

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

@@ -1,13 +1,24 @@
-/** Android's AppticsRemoteConfig: fetchValue, fetchValues, setCustomConditionValue, setFallbackWithOfflineValue. */
+/** AppticsRemoteConfig: fetchValue, fetchValues and setCustomConditionValue, each with the parameter names the console shows. */
 export declare const AppticsRemoteConfig: {
-    fetchValue: (name: string, callback?: (value: string | null) => void, coldFetch?: boolean) => Promise<string | null>;
-    fetchValues: (defaults: Record<string, string | null>, callback?: (values: Record<string, string | null>) => void, coldFetch?: boolean) => Promise<Record<string, string | null>>;
-    /** Whether a failed fetch answers with the values fetched before (the default) or with null. */
-    setFallbackWithOfflineValue: (enabled?: boolean) => void;
+    /** One parameter's value, null when there is none. coldFetch (false by default) asks the server for the whole set now. */
+    fetchValue: {
+        (name: string, callback?: (value: string | null) => void, coldFetch?: boolean): Promise<string | null>;
+        (name: string, coldFetch: boolean): Promise<string | null>;
+    };
     /**
-     * What this device is for a custom criteria the console defines, as Android's
-     * setCustomConditionValue; an empty value removes it. Kept across visits.
+     * The parameters named, or every parameter when none are: name -> value, null when there is
+     * none. coldFetch (false by default) asks the server for the whole set now.
      */
-    setCustomConditionValue: (key: string, value: string | number | boolean | null) => void;
+    fetchValues: {
+        (names?: string[], callback?: (values: Record<string, string | null>) => void, coldFetch?: boolean): Promise<Record<string, string | null>>;
+        (names: string[], coldFetch: boolean): Promise<Record<string, string | null>>;
+        (callback: (values: Record<string, string | null>) => void, coldFetch?: boolean): Promise<Record<string, string | null>>;
+        (coldFetch: boolean): Promise<Record<string, string | null>>;
+    };
+    /**
+     * What this device is for a custom condition, by the condition's name, as comma separated
+     * values: it matches when one of them is listed. An empty value removes it.
+     */
+    setCustomConditionValue: (conditionname: string, value: string | number | boolean | null) => void;
 };
 export default AppticsRemoteConfig;

package/dist/esm/remoteconfig/index.js

@@ -1,5 +1,5 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
-import { guard } from '../core/guard.js';
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { forward, guard } from '../core/guard.js';
 import { Console } from '../core/logger.js';
 import { obtain } from './fetch.js';
 import { setCustomConditionValue } from './custom.js';
@@ -9,30 +9,23 @@ import { all } from './store.js';
  * Remote config, shipped as its own entry point:
  *   import { AppticsRemoteConfig } from '@zoho_apptics/apptics-js-sdk/remote-config';
  *
- * Four calls, as on Android: fetchValue(name) and fetchValues({ name: default }) read parameters,
- * setCustomConditionValue says what this device is for a custom criteria, and
- * setFallbackWithOfflineValue chooses what a failed fetch answers with. The rule set is stored and
- * resolved on the device, so a fetch within five minutes, or a failed one with the offline fallback
- * on, answers without waiting on the network. The SDK fetches on start-up, and re-applies the rules
- * on its own when AppticsSetUser or setCustomConditionValue changes what this device is.
+ * fetchValue(name) reads one parameter, fetchValues(['a', 'b']) several, and fetchValues() every
+ * parameter the console has. Each parameter's value is the console's: the value of the first
+ * condition, in the console's order, that this device matches, else the parameter's default value.
+ * setCustomConditionValue(conditionname, 'a,b') answers the custom conditions.
+ * The rule set is stored and resolved on the device, so a read answers without waiting on the
+ * network, and a failed fetch answers with the values fetched before. The SDK fetches the whole set
+ * on start-up, then what changed every 3 minutes; coldFetch (true as
+ * the last argument) asks for the whole set now. It re-applies the rules on its own when
+ * AppticsUser.setUser changes the user.
  *
- * A parameter the console does not have is null from fetchValue and the caller's default from
- * fetchValues, never undefined: a config system whose failure mode is `undefined` moves the
- * problem into the app's rendering code.
+ * A name the console does not have is null, never undefined: a config system whose failure mode
+ * is `undefined` moves the problem into the app's rendering code.
  */
 function raw(name) {
     var values = all();
     return Object.prototype.hasOwnProperty.call(values, name) ? values[name] : undefined;
 }
-/**
- * Whether a fetch that failed still answers with what was fetched before. On by default, as
- * `fallbackWithOfflineValue` is on Android: a page offline for a moment keeps its config.
- */
-var fallbackWithOfflineValue = true;
-/** Off: a failed fetch answers with null, or the caller's defaults, rather than stored values. */
-function setFallbackWithOfflineValue(enabled) {
-    fallbackWithOfflineValue = typeof enabled === 'boolean' ? enabled : true; // no i18n
-}
 /** Hands a result to the app's callback, which must not be able to break the Promise. */
 function answer(value, callback) {
     if (typeof callback === 'function') { // no i18n
@@ -47,39 +40,88 @@ function answer(value, callback) {
 }
 /**
  * One parameter, fetched for this page, as Android's fetchValue: resolves with its value, or null
- * when the console has no such parameter or the fetch failed with the offline fallback off.
+ * when the console has no such parameter. A failed fetch answers with the value fetched before.
+ *
+ * `coldFetch` (false by default) asks the server now with flagtime 0, for the whole set, and
+ * answers from that instead of what this page already has. It may come in place of the callback.
  */
 function fetchValue(name, callback, coldFetch) {
-    return obtain(coldFetch).then(function (fresh) {
-        var value = fresh || fallbackWithOfflineValue ? raw(name) : undefined;
-        return answer(value === undefined ? null : value, callback);
+    if (typeof callback === 'boolean') { // no i18n
+        // fetchValue(name, coldFetch)
+        coldFetch = callback;
+        callback = undefined;
+    }
+    var done = typeof callback === 'function' ? callback : undefined; // no i18n
+    return obtain(coldFetch === true).then(function () {
+        var value = raw(name);
+        return answer(value === undefined ? null : value, done);
     });
 }
 /**
- * Several parameters at once, as Android's fetchValues: `defaults` maps each name to the value to
- * use when there is none, and the result has exactly those names.
+ * Several parameters at once: `names` lists the ones wanted, and the result has exactly those
+ * names, null for one the console does not have. With no names (or an empty list), every
+ * parameter the console has. A callback may come first when there are no names, and `coldFetch`
+ * (false by default, as for fetchValue) last, in place of either.
  */
-function fetchValues(defaults, callback, coldFetch) {
-    return obtain(coldFetch).then(function (fresh) {
+function fetchValues(names, callback, coldFetch) {
+    var args = [names, callback, coldFetch];
+    // the first boolean is coldFetch, wherever it comes: fetchValues(true), fetchValues(names, true),
+    // fetchValues(callback, true)
+    var flag = args.filter(function (one) { return typeof one === 'boolean'; })[0]; // no i18n
+    var fn = args.filter(function (one) { return typeof one === 'function'; })[0]; // no i18n
+    var wanted = wantedNames(typeof names === 'boolean' || typeof names === 'function' ? undefined : names); // no i18n
+    var done = fn;
+    return obtain(flag === true).then(function () {
+        var values = all();
         var out = {};
-        Object.keys(defaults || {}).forEach(function (name) {
-            var value = fresh || fallbackWithOfflineValue ? raw(name) : undefined;
-            out[name] = value === undefined ? defaults[name] : value;
+        (wanted === null ? Object.keys(values) : wanted).forEach(function (name) {
+            var value = raw(name);
+            out[name] = value === undefined ? null : value;
         });
-        return answer(out, callback);
+        return answer(out, done);
+    });
+}
+/** The names asked for, or null for every parameter. Anything but a list of names counts as none. */
+function wantedNames(names) {
+    if (names === undefined || names === null) {
+        return null;
+    }
+    if (!Array.isArray(names)) {
+        Console.warn('AppticsRemoteConfig.fetchValues: takes a list of parameter names, as fetchValues([\'a\', \'b\']); answering with every parameter'); // no i18n
+        return null;
+    }
+    var out = [];
+    names.forEach(function (name) {
+        var one = typeof name === 'string' ? name.trim() : ''; // no i18n
+        if (one !== '' && out.indexOf(one) === -1) { // no i18n
+            out.push(one);
+        }
     });
+    return out.length === 0 ? null : out;
 }
-/** Android's AppticsRemoteConfig: fetchValue, fetchValues, setCustomConditionValue, setFallbackWithOfflineValue. */
+const fetchValueGuarded = guard('AppticsRemoteConfig.fetchValue', fetchValue); // no i18n
+const fetchValuesGuarded = guard('AppticsRemoteConfig.fetchValues', fetchValues); // no i18n
+const setCustomConditionValueGuarded = guard('AppticsRemoteConfig.setCustomConditionValue', setCustomConditionValue); // no i18n
+/** AppticsRemoteConfig: fetchValue, fetchValues and setCustomConditionValue, each with the parameter names the console shows. */
 const AppticsRemoteConfig = {
-    fetchValue: guard('AppticsRemoteConfig.fetchValue', fetchValue), // no i18n
-    fetchValues: guard('AppticsRemoteConfig.fetchValues', fetchValues), // no i18n
-    /** Whether a failed fetch answers with the values fetched before (the default) or with null. */
-    setFallbackWithOfflineValue: guard('AppticsRemoteConfig.setFallbackWithOfflineValue', setFallbackWithOfflineValue), // no i18n
+    /** One parameter's value, null when there is none. coldFetch (false by default) asks the server for the whole set now. */
+    fetchValue: function fetchValue(name, callback, coldFetch) {
+        return forward(fetchValueGuarded, arguments);
+    },
+    /**
+     * The parameters named, or every parameter when none are: name -> value, null when there is
+     * none. coldFetch (false by default) asks the server for the whole set now.
+     */
+    fetchValues: function fetchValues(names, callback, coldFetch) {
+        return forward(fetchValuesGuarded, arguments);
+    }, // no i18n
     /**
-     * What this device is for a custom criteria the console defines, as Android's
-     * setCustomConditionValue; an empty value removes it. Kept across visits.
+     * What this device is for a custom condition, by the condition's name, as comma separated
+     * values: it matches when one of them is listed. An empty value removes it.
      */
-    setCustomConditionValue: guard('AppticsRemoteConfig.setCustomConditionValue', setCustomConditionValue), // no i18n
+    setCustomConditionValue: function setCustomConditionValue(conditionname, value) {
+        forward(setCustomConditionValueGuarded, arguments);
+    },
 };
 
 export { AppticsRemoteConfig, AppticsRemoteConfig as default };

package/dist/esm/remoteconfig/store.d.ts

@@ -1,17 +1,25 @@
 import type { Dict } from '../types.js';
-/** The flagtime to send: 0 until we hold a rule set, which asks the server for everything. */
+/** When the last answered getupdates went out; 0 when nothing is stored. */
 export declare function flagtime(): number;
 /** Re-resolves the stored rules against this device, without fetching. */
 export declare function reresolve(): void;
-/** Stores a rule set the server just sent, and resolves it. */
-export declare function store(rules: Dict, at: number): void;
 /**
- * Records a fetch that brought no rule set.
+ * Stores a whole rule set, the answer to flagtime 0, in place of what was stored, and resolves
+ * it. `askedAt` is when the request went out: the next one asks for what changed since then.
+ */
+export declare function store(rules: Dict, askedAt: number): void;
+/**
+ * Merges what a later getupdates sent, everything added or changed since its flagtime, into the
+ * stored rule set, and resolves the result. With nothing stored, it is the whole set.
+ */
+export declare function merge(changes: Dict, askedAt: number): void;
+/**
+ * Records a later fetch that brought no changes.
  *
- * That is the normal answer when nothing has changed, and it is not a failure: what is stored
- * stays, and only the fetch time moves.
+ * That is the normal answer, and it is not a failure: what is stored stays, and the next request
+ * asks for what changed since this one went out.
  */
-export declare function storeUnchanged(at: number): void;
+export declare function storeUnchanged(askedAt: number): void;
 /** Forgets the rule set and its values, so the next fetch asks with flagtime 0. */
 export declare function clearRemoteConfig(): void;
 /** Every parameter resolved for this device. Loads from storage on the first read. */