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

package/dist/esm/index.d.ts

@@ -1,68 +1,22 @@
-import { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS } from './core/constants.js';
-import { init as initImpl, ready as readyImpl, reset as resetImpl } from './lifecycle.js';
-import { enableApiTracking as enableApiTrackingImpl } from './engagement/auto-api.js';
-import { DefinedEvents } from './engagement/defined-events.js';
-import { ApiTrackingBuilder } from './engagement/api-rules.js';
-import { enableGlobalErrorHandler as enableGlobalErrorHandlerImpl } from './errors/track.js';
-import { getUser as getUserImpl, UserBuilder, users } from './user/index.js';
-import { getTrackingStatus as getTrackingStatusImpl, setTrackingStatus as setTrackingStatusImpl } from './core/consent.js';
-import { flush as flushImpl } from './scheduler.js';
-import { addDiagnosticsInfo as addDiagnosticsInfoImpl, addFeedbackLog as addFeedbackLogImpl } from './feedback/logs.js';
-import type { AppticsApi } from './types.js';
-import { disableDebug as disableDebugImpl, enableDebug as enableDebugImpl } from './core/debug.js';
-import { AppticsLogger } from './remotelog/logger.js';
-export type { AppticsLogger as AppticsLoggerApi } from './remotelog/logger.js';
-export type { AppticsApi, AppticsConfig, ErrorLike, FeedbackType, Properties, TrackingStatus, UserInfo, UserValidationResult, } from './types.js';
-/** Android's Apptics: `Apptics.init(config)` starts the SDK. */
-export declare const Apptics: {
-    /** Starts the SDK. The config object is required; the console snippet supplies it via auto-init. */
-    init: typeof initImpl;
-};
-export declare const ready: typeof readyImpl;
-/** Android's AppticsEvents: `addEvent(name, group?, properties?)`, or `addEvent(DefinedEvents.X, properties?)`. */
-export declare const AppticsEvents: {
-    addEvent: AppticsApi["AppticsEvents"]["addEvent"];
-};
-/** Apptics' defined events, as Android's DefinedEvents, to log with AppticsEvents.addEvent. */
-export { DefinedEvents };
+import './heatmap/send.js';
+import type { AppticsSdk } from './types.js';
+export type { AppticsSdk, AppticsConfig, ErrorLike, FeedbackType, Properties, TrackingStatus, UserInfo, UserValidationResult, } from './types.js';
+/** Android's Apptics: starting the SDK, and what applies to all of it. */
+export declare const Apptics: AppticsSdk['Apptics'];
+export declare const AppticsEvent: AppticsSdk['AppticsEvent'];
 export type { DefinedEvent } from './engagement/defined-events.js';
 /** Android's AppticsScreenTracker: inScreen(name) returns the view's id, outScreen(id) ends it. */
-export declare const AppticsScreenTracker: AppticsApi['AppticsScreenTracker'];
+export declare const AppticsScreen: AppticsSdk['AppticsScreen'];
 /** Android's AppticsApiTracker: startTrackApi / endTrackApi, and configure for the rules. */
-export declare const AppticsApiTracker: AppticsApi['AppticsApiTracker'];
-export { ApiTrackingBuilder };
+export declare const AppticsApi: AppticsSdk['AppticsApi'];
 export type { ApiTrackingConfig } from './engagement/api-rules.js';
-/** Turns automatic API tracking on or off; the `track_api` config flag is the usual way to set it. */
-export declare const enableApiTracking: typeof enableApiTrackingImpl;
-/** Reports an error the app caught, or an `error` / `unhandledrejection` event. */
-export declare const AppticsTrackError: AppticsApi["AppticsTrackError"];
-export declare const enableGlobalErrorHandler: typeof enableGlobalErrorHandlerImpl;
-/** Registers the signed-in user; properties may be a plain object or UserBuilder.build(). */
-export declare const AppticsSetUser: AppticsApi["AppticsSetUser"];
-export declare const getUser: typeof getUserImpl;
-export declare const setTrackingStatus: typeof setTrackingStatusImpl;
-export declare const getTrackingStatus: typeof getTrackingStatusImpl;
-export declare const flush: typeof flushImpl;
-/** Records a line for the next feedback submission. Costs nothing until feedback is sent. */
-export declare const addFeedbackLog: typeof addFeedbackLogImpl;
-/** Records a diagnostics key/value, grouped under `heading`, for the next feedback submission. */
-export declare const addDiagnosticsInfo: typeof addDiagnosticsInfoImpl;
-/**
- * Turns debug mode on; works before init(), and wins over `debug` in init().
- *
- * On, engagement, exception and log go to their `debug/` twins and the answers carry a request id
- * and a link into the server's own logs. It switches itself off after an hour with nothing
- * tracked, so a forgotten tab stops tracing on its own.
- */
-export declare const enableDebug: typeof enableDebugImpl;
-/** Turns debug mode off; works before init(), and wins over `debug` in init(). */
-export declare const disableDebug: typeof disableDebugImpl;
-export declare const reset: typeof resetImpl;
-/**
- * Android's AppticsLogger, shown on the console's Remote Logger page. Off until
- * `AppticsLogger.enable()`; then `AppticsLogger.v / d / i / w / e(tag, message, ...details)`.
- */
-export { AppticsLogger };
-export { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS, UserBuilder, users };
-declare const apptics: AppticsApi;
+/** Errors: the ones the app caught, and the switch for the uncaught ones tracked on their own. */
+export declare const AppticsError: AppticsSdk['AppticsError'];
+/** Android's AppticsUser: the signed-in user, and the builder for their properties. */
+export declare const AppticsUser: AppticsSdk['AppticsUser'];
+/** Heatmap capture: AppticsHeatmap.trackHeatmap() starts or stops recording clicks and scrolls. */
+export declare const AppticsHeatmap: AppticsSdk['AppticsHeatmap'];
+/** Android's AppticsSettings: what the SDK may track for this visitor. */
+export declare const AppticsSettings: AppticsSdk['AppticsSettings'];
+declare const apptics: AppticsSdk;
 export default apptics;

package/dist/esm/index.js

@@ -1,42 +1,72 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
-import { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS } from './core/constants.js';
-import { guard } from './core/guard.js';
-import { init, reset as reset$1, ready as ready$1 } from './lifecycle.js';
-import { enableApiTracking as enableApiTracking$1 } from './engagement/auto-api.js';
-import { startTrackApi, trackEvent, endTrackApiAt, outScreenAt, inScreenAt } from './engagement/track.js';
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_TRACKING_STATUS } from './core/constants.js';
+import { forward, guard } from './core/guard.js';
+import { reset, ready, init } from './lifecycle.js';
+import { enableApiTracking } from './engagement/auto-api.js';
+import { endTrackApiAt, outScreenAt, inScreenAt, startTrackApi, trackEvent } from './engagement/track.js';
 import { DefinedEvents } from './engagement/defined-events.js';
 import { nowMs, getNewUUID } from './core/utils.js';
 import { validateScreenName } from './core/validate.js';
 import { ApiTrackingBuilder, configureApiTracking } from './engagement/api-rules.js';
-import { trackError, enableGlobalErrorHandler as enableGlobalErrorHandler$1 } from './errors/track.js';
-import { users, setUser, getUser as getUser$1 } from './user/index.js';
-export { UserBuilder } from './user/index.js';
-import { getTrackingStatus as getTrackingStatus$1, setTrackingStatus as setTrackingStatus$1 } from './core/consent.js';
-import { flush as flush$1 } from './scheduler.js';
-import { addDiagnosticsInfo as addDiagnosticsInfo$1, addFeedbackLog as addFeedbackLog$1 } from './feedback/logs.js';
+import { trackGlobalErrorHandler, trackError } from './errors/track.js';
+import { UserBuilder, getUser, setUser } from './user/index.js';
+import { getTrackingStatus, setTrackingStatus } from './core/consent.js';
+import { flush } from './scheduler.js';
+import { trackHeatmap } from './heatmap/track.js';
+import './heatmap/send.js';
 import { scheduleAutoInit } from './auto-init.js';
-import { disableDebug as disableDebug$1, enableDebug as enableDebug$1 } from './core/debug.js';
-import { AppticsLogger } from './remotelog/logger.js';
+import { disableDebug, enableDebug } from './core/debug.js';
 
-/** Android's Apptics: `Apptics.init(config)` starts the SDK. */
+/*
+ * Every public call below is a function of its own, with the parameter names the console shows
+ * on hover, forwarding to its guard()ed implementation (see forward).
+ */
+const initGuarded = guard('Apptics.init', init); // no i18n
+const readyGuarded = guard('Apptics.ready', ready); // no i18n
+const flushGuarded = guard('Apptics.flush', flush); // no i18n
+const resetGuarded = guard('Apptics.reset', reset); // no i18n
+/**
+ * Debug mode, on or off; works before init(), and wins over `debug` in init(). On, engagement,
+ * exception and log go to their `debug/` twins and the answers carry a request id and a link into
+ * the server's own logs. It switches itself off after an hour with nothing tracked, so a forgotten
+ * tab stops tracing on its own.
+ */
+const enableDebugGuarded = guard('Apptics.enableDebug', enableDebug); // no i18n
+const disableDebugGuarded = guard('Apptics.disableDebug', disableDebug); // no i18n
+/** Android's Apptics: starting the SDK, and what applies to all of it. */
 const Apptics = {
     /** Starts the SDK. The config object is required; the console snippet supplies it via auto-init. */
-    init: guard('Apptics.init', init), // no i18n
+    init: function init(config) { return forward(initGuarded, arguments); },
+    /** Resolves true once the SDK is running, false if it can't start. */
+    ready: function ready() { return forward(readyGuarded, arguments); },
+    /** Sends stored engagements, errors and heatmap records now. */
+    flush: function flush() { return forward(flushGuarded, arguments); },
+    /** Clears stored identity, queued data and remote config values, then starts again. */
+    reset: function reset() { return forward(resetGuarded, arguments); },
+    enableDebug: function enableDebug() { return forward(enableDebugGuarded, arguments); },
+    disableDebug: function disableDebug() { return forward(disableDebugGuarded, arguments); },
 };
-const ready = guard('ready', ready$1); // no i18n
-/** Android's AppticsEvents: `addEvent(name, group?, properties?)`, or `addEvent(DefinedEvents.X, properties?)`. */
-const AppticsEvents = {
-    addEvent: guard('AppticsEvents.addEvent', trackEvent), // no i18n
+/**
+ * Android's AppticsEvents: `addEvent(name, group?, properties?)`, or
+ * `addEvent(AppticsEvent.DefinedEvents.X, properties?)`.
+ */
+const addEventGuarded = guard('AppticsEvent.addEvent', trackEvent); // no i18n
+const AppticsEvent = {
+    /** Apptics' defined events, as Android's DefinedEvents, to log with addEvent. */
+    DefinedEvents: DefinedEvents,
+    addEvent: function addEvent(eventName, groupName, properties) {
+        return forward(addEventGuarded, arguments);
+    },
 };
-const inScreenGuarded = guard('AppticsScreenTracker.inScreen', inScreenAt); // no i18n
-const outScreenGuarded = guard('AppticsScreenTracker.outScreen', outScreenAt); // no i18n
+const inScreenGuarded = guard('AppticsScreen.inScreen', inScreenAt); // no i18n
+const outScreenGuarded = guard('AppticsScreen.outScreen', outScreenAt); // no i18n
 /** Android's AppticsScreenTracker: inScreen(name) returns the view's id, outScreen(id) ends it. */
-const AppticsScreenTracker = {
+const AppticsScreen = {
     /**
      * Records a screen view and returns its id. The view ends at the next screen, when the page is
      * hidden or its session ends, or when the id is handed to outScreen. '' for an invalid name.
      */
-    inScreen: function (screenName, properties) {
+    inScreen: function inScreen(screenName, properties) {
         if (!validateScreenName(screenName)) {
             // inScreenAt reports it; the caller still needs an answer now
             inScreenGuarded(screenName, properties, '', nowMs()); // no i18n
@@ -48,75 +78,73 @@ const AppticsScreenTracker = {
         return id;
     },
     /** Ends the screen view inScreen began, before the next screen would. */
-    outScreen: function (id) {
+    outScreen: function outScreen(id) {
         outScreenGuarded(id, nowMs());
     },
 };
-const endTrackApiGuarded = guard('AppticsApiTracker.endTrackApi', endTrackApiAt); // no i18n
+const endTrackApiGuarded = guard('AppticsApi.endTrackApi', endTrackApiAt); // no i18n
+const startTrackApiGuarded = guard('AppticsApi.startTrackApi', startTrackApi); // no i18n
+const configureGuarded = guard('AppticsApi.configure', configureApiTracking); // no i18n
+const enableApiTrackingGuarded = guard('AppticsApi.enableApiTracking', enableApiTracking); // no i18n
 /** Android's AppticsApiTracker: startTrackApi / endTrackApi, and configure for the rules. */
-const AppticsApiTracker = {
+const AppticsApi = {
     /** Begins timing one call: returns the id endTrackApi takes. */
-    startTrackApi: guard('AppticsApiTracker.startTrackApi', startTrackApi), // no i18n
+    startTrackApi: function startTrackApi(url, method) { return forward(startTrackApiGuarded, arguments); },
     /** Finishes a call startTrackApi began and records it. */
-    endTrackApi: function (id, responseCode, responseMessage) {
+    endTrackApi: function endTrackApi(id, responseCode, responseMessage) {
         // the end time now, not when a call made during start-up is replayed
         endTrackApiGuarded(id, responseCode, responseMessage, nowMs());
     },
+    /** Builds the rules configure takes: `new AppticsApi.ApiTrackingBuilder()…build()`. */
+    ApiTrackingBuilder: ApiTrackingBuilder,
     /** The rules API tracking records by, from ApiTrackingBuilder. Works before Apptics.init(). */
-    configure: guard('AppticsApiTracker.configure', configureApiTracking), // no i18n
+    configure: function configure(config) { return forward(configureGuarded, arguments); },
+    /** Turns automatic API tracking on or off; the `track_api` config flag is the usual way to set it. */
+    enableApiTracking: function enableApiTracking(enabled) { return forward(enableApiTrackingGuarded, arguments); },
+};
+const trackErrorGuarded = guard('AppticsError.trackError', trackError); // no i18n
+const trackGlobalErrorHandlerGuarded = guard('AppticsError.trackGlobalErrorHandler', trackGlobalErrorHandler); // no i18n
+/** Errors: the ones the app caught, and the switch for the uncaught ones tracked on their own. */
+const AppticsError = {
+    /** Reports an error the app caught, or an `error` / `unhandledrejection` event. */
+    trackError: function trackError(error, properties) { return forward(trackErrorGuarded, arguments); },
+    /** Turns the automatic tracking of uncaught errors and unhandled rejections on or off. */
+    trackGlobalErrorHandler: function trackGlobalErrorHandler(enabled) { return forward(trackGlobalErrorHandlerGuarded, arguments); },
+};
+const setUserGuarded = guard('AppticsUser.setUser', setUser); // no i18n
+const getUserGuarded = guard('AppticsUser.getUser', getUser); // no i18n
+/** Android's AppticsUser: the signed-in user, and the builder for their properties. */
+const AppticsUser = {
+    /** Registers the signed-in user; properties may be a plain object or UserBuilder.build(). */
+    setUser: function setUser(userid, groupid, properties) { return forward(setUserGuarded, arguments); },
+    /** The registered user, or {} when there is none. */
+    getUser: function getUser() { return forward(getUserGuarded, arguments); },
+    UserBuilder: UserBuilder,
+};
+const trackHeatmapGuarded = guard('AppticsHeatmap.trackHeatmap', trackHeatmap); // no i18n
+/** Heatmap capture: AppticsHeatmap.trackHeatmap() starts or stops recording clicks and scrolls. */
+const AppticsHeatmap = {
+    trackHeatmap: function trackHeatmap(on) { return forward(trackHeatmapGuarded, arguments); },
+};
+const setTrackingStatusGuarded = guard('AppticsSettings.setTrackingStatus', setTrackingStatus); // no i18n
+const getTrackingStatusGuarded = guard('AppticsSettings.getTrackingStatus', getTrackingStatus); // no i18n
+/** Android's AppticsSettings: what the SDK may track for this visitor. */
+const AppticsSettings = {
+    /** The states setTrackingStatus takes: USAGE_TRACKING_WITH_PII, USAGE_TRACKING_WITHOUT_PII, NO_TRACKING. */
+    AP_TRACKING_STATUS: AP_TRACKING_STATUS,
+    setTrackingStatus: function setTrackingStatus(status) { return forward(setTrackingStatusGuarded, arguments); },
+    getTrackingStatus: function getTrackingStatus() { return forward(getTrackingStatusGuarded, arguments); },
 };
-/** Turns automatic API tracking on or off; the `track_api` config flag is the usual way to set it. */
-const enableApiTracking = guard('enableApiTracking', enableApiTracking$1); // no i18n
-/** Reports an error the app caught, or an `error` / `unhandledrejection` event. */
-const AppticsTrackError = guard('AppticsTrackError', trackError); // no i18n
-const enableGlobalErrorHandler = guard('enableGlobalErrorHandler', enableGlobalErrorHandler$1); // no i18n
-/** Registers the signed-in user; properties may be a plain object or UserBuilder.build(). */
-const AppticsSetUser = guard('AppticsSetUser', setUser); // no i18n
-const getUser = guard('getUser', getUser$1); // no i18n
-const setTrackingStatus = guard('setTrackingStatus', setTrackingStatus$1); // no i18n
-const getTrackingStatus = guard('getTrackingStatus', getTrackingStatus$1); // no i18n
-const flush = guard('flush', flush$1); // no i18n
-/** Records a line for the next feedback submission. Costs nothing until feedback is sent. */
-const addFeedbackLog = guard('addFeedbackLog', addFeedbackLog$1); // no i18n
-/** Records a diagnostics key/value, grouped under `heading`, for the next feedback submission. */
-const addDiagnosticsInfo = guard('addDiagnosticsInfo', addDiagnosticsInfo$1); // no i18n
-/**
- * Turns debug mode on; works before init(), and wins over `debug` in init().
- *
- * On, engagement, exception and log go to their `debug/` twins and the answers carry a request id
- * and a link into the server's own logs. It switches itself off after an hour with nothing
- * tracked, so a forgotten tab stops tracing on its own.
- */
-const enableDebug = guard('enableDebug', enableDebug$1); // no i18n
-/** Turns debug mode off; works before init(), and wins over `debug` in init(). */
-const disableDebug = guard('disableDebug', disableDebug$1); // no i18n
-const reset = guard('reset', reset$1); // no i18n
 const apptics = {
     Apptics,
-    AppticsEvents,
-    AppticsScreenTracker,
-    AppticsApiTracker,
-    AppticsLogger,
-    DefinedEvents,
-    ApiTrackingBuilder,
-    ready,
-    enableDebug,
-    disableDebug,
-    enableApiTracking,
-    AppticsTrackError,
-    enableGlobalErrorHandler,
-    AppticsSetUser,
-    getUser,
-    users,
-    setTrackingStatus,
-    getTrackingStatus,
-    flush,
-    addFeedbackLog,
-    addDiagnosticsInfo,
-    reset,
-    AP_TRACKING_STATUS,
-    AP_FEEDBACK_TYPE,
+    AppticsEvent,
+    AppticsScreen,
+    AppticsApi,
+    AppticsError,
+    AppticsUser,
+    AppticsSettings,
+    AppticsHeatmap,
 };
 scheduleAutoInit(Apptics);
 
-export { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS, ApiTrackingBuilder, Apptics, AppticsApiTracker, AppticsEvents, AppticsLogger, AppticsScreenTracker, AppticsSetUser, AppticsTrackError, DefinedEvents, addDiagnosticsInfo, addFeedbackLog, apptics as default, disableDebug, enableApiTracking, enableDebug, enableGlobalErrorHandler, flush, getTrackingStatus, getUser, ready, reset, setTrackingStatus, users };
+export { Apptics, AppticsApi, AppticsError, AppticsEvent, AppticsHeatmap, AppticsScreen, AppticsSettings, AppticsUser, apptics as default };

package/dist/esm/lifecycle.d.ts

@@ -1,13 +1,20 @@
+import { type ScreenRouteRule } from './core/constants.js';
 import type { AppticsConfig } from './types.js';
 /**
  * Starts the SDK. The config object is required: pass it directly, or let the console snippet
  * supply it (auto-init reads window.appticssettings._defaultoptions and calls init with it).
- * Returns true when the config has serviceUrl, zak, identifier and appversion and start-up has
+ * Returns true when the config has base_url, auth_key, app_domain and appversion and start-up has
  * begun (see ready()), false when it was already running, the config is missing or incomplete, or
  * there is no browser. Start-up calls app/addversion with those four, which answers with aaid, the
  * portal and project ids and the rest; then device/add registers the browser, as in 1.x.
  */
 export declare function init(config: AppticsConfig): boolean;
+/**
+ * screen_routes as init() keeps it: each entry checked, an exact path cleaned up, a regex given as
+ * a string compiled. An entry that cannot be used is left out, and said, rather than matching
+ * something its author did not mean.
+ */
+export declare function screenRouteRules(routes: unknown): ScreenRouteRule[];
 /** Resolves true once start-up has finished, false if init() refused or storage is unusable. */
 export declare function ready(): Promise<boolean>;
 /** Clears stored identity and queues, then starts again from the snippet. */