@naturalcycles/internal-web-lib 1.0.0

package/dist/analytics/analyticsClient.d.ts

@@ -0,0 +1,356 @@
+import type { FirstTouchUtms, SetOnceUserProperties } from '@naturalcycles/js-lib/analytics';
+import { AppError } from '@naturalcycles/js-lib/error';
+import type { ErrorData } from '@naturalcycles/js-lib/error';
+import type { CommonLogger } from '@naturalcycles/js-lib/log';
+import type { AnyObject, NumberOfMilliseconds, PositiveInteger, UnixTimestampMillis } from '@naturalcycles/js-lib/types';
+import type { AnalyticsEventListener, ClientId, MixpanelDistinctId } from '@naturalcycles/shared';
+export type { AnalyticsEventListener } from '@naturalcycles/shared';
+/**
+ * Self-hosted analytics event client.
+ *
+ * Captures client-side analytics events, adds browser page properties, batches them, retries
+ * transient failures and delivers them to our own Backend via a single REST endpoint.
+ */
+export declare class AnalyticsClient implements AnalyticsClientApi {
+    constructor(cfg: AnalyticsClientCfg);
+    private cfg;
+    private firstTouchFetcher;
+    /**
+     * The built-in identity, constructed from `cfg.identity`. Also readable by application code,
+     * e.g to feed the distinctId or acquisition props to other integrations.
+     */
+    readonly identity: AnalyticsIdentity;
+    /**
+     * Random id of this AnalyticsClient instance (in practice - of this tab/pageload),
+     * used to namespace the localStorage queue snapshot.
+     */
+    private tabId;
+    private queue;
+    private flushTimer?;
+    private isFlushing;
+    private consecutiveFailures;
+    /**
+     * Requested by the server via `Retry-After` header (already converted to ms).
+     */
+    private retryAfter;
+    private hasUpdatedAcquisitionProps;
+    private readonly eventListeners;
+    private handlePageHide;
+    private handleVisibilityChange;
+    /**
+     * Optional eager bootstrapping, to call once at app boot: registers the acquisition props
+     * into the identity entry while the landing url/referrer are still current - the moment
+     * an SPA navigation can strip the utm params off the url before the first event fires. Gated by cfg.isEnabled, like the events themselves.
+     * Without it the registration happens lazily before the first enabled event.
+     */
+    init(): void;
+    track(name: string, props?: AnyObject): void;
+    /**
+     * Replays the calls a stub recorded on the page before this client loaded, under the timestamps
+     * they were made at. Tracked in order, so calls made before the stub's `identify()` keep the
+     * anonymous identity.
+     */
+    private replayFromStub;
+    /**
+     * Registers a listener called synchronously for every delivered event, past the gates in
+     * `track()`. Returns an unsubscribe function. Listeners receive a snapshot and cannot affect
+     * delivery, and a throwing listener never breaks tracking.
+     */
+    onEvent(listener: AnalyticsEventListener): () => void;
+    private notifyEventListeners;
+    /**
+     * Sets the distinctId going forward (persisted), e.g after a successful signup.
+     * Pending events are kept, each under the identity it was tracked with.
+     */
+    identify(userId: string): void;
+    private enqueue;
+    private canTrack;
+    /**
+     * Clears pending events and the persisted identity entry, including its acquisition
+     * properties. A new identity is generated on next use.
+     */
+    reset(): void;
+    /**
+     * Drains the queue, one batch per request.
+     * Called automatically (flush interval / batch size / pagehide) - public for manual flushing.
+     */
+    flush(): Promise<void>;
+    /**
+     * Immediate flush: hands queued events over to the browser via keepalive fetch.
+     * Runs automatically on pagehide / visibilitychange:hidden. Public so that app code can
+     * hand events over right away: events tracked in its own page-lifecycle handlers (which
+     * run after this client's own), and events tracked right before a navigation (e.g a
+     * cta click) - unload-time delivery is best-effort and can be lost, while a
+     * keepalive request from a still-alive page survives the navigation.
+     * The persisted queue remains untouched because keepalive requests cannot reliably process
+     * their response; a later regular flush re-sends and deduplicates the events.
+     */
+    flushNow(): void;
+    /**
+     * Removes listeners and pending timers. Only needed when an instance is discarded
+     * (e.g in tests or HMR) - the app-wide singleton never needs it.
+     */
+    destroy(): void;
+    /**
+     * Registers the acquisition props into the identity entry once per pageload, like
+     * eagerly from init(), or lazily before the first
+     * enabled event. Either path is gated by cfg.isEnabled, so bot/e2e/consent gating
+     * applies to the persistence write too.
+     */
+    private ensureAcquisitionProps;
+    /**
+     * Posts the first-touch props to their own endpoint, once per pageload. Fire-and-forget:
+     * `$set_once` ignores every write after the first, so a lost or repeated call costs nothing.
+     */
+    private sendFirstTouch;
+    private getDefaultProps;
+    private clearPendingEvents;
+    private sendBatch;
+    private postBatch;
+    /**
+     * Splits the whole queue into request-ready batches of at most maxBatchSize events
+     * and maxBatchBytes serialized bytes each.
+     */
+    private prepareBatches;
+    private createPendingBatch;
+    private finalizeBatch;
+    /**
+     * Adopts queue snapshots persisted by previous pageloads (crashed/killed tabs) and re-sends them.
+     * A snapshot of a still-alive tab may be adopted too - the resulting duplicate delivery
+     * is deduped by the Backend via event ids.
+     */
+    private restoreOrphanedQueues;
+    private scheduleFlush;
+    private clearFlushTimer;
+    private removeFromQueue;
+    private persistQueue;
+    private get queueKey();
+}
+/**
+ * Distinct-id generation and persistence:
+ *
+ * - a new identity is a UUID v4 device id, stored as `$device_id`,
+ *   with `distinct_id` derived from it by `generateDistinctId`
+ * - `identify(userId)` sets `distinct_id` and `user_id`, keeping `$device_id` (same person)
+ * - `reset()` clears the whole entry and generates a fresh anonymous identity (unrelated person)
+ * - the identity is stored as a JSON object under a single cookie / localStorage name
+ *
+ * Apps sharing a persistenceName and cookie domain read and write the same identity:
+ * whichever writes first, the others adopt it. Properties they keep in the same entry
+ * are preserved on write, never interpreted.
+ *
+ * Storage failures (SSR, blocked cookies/localStorage) degrade to an in-memory session-scoped
+ * identity - analytics must never break the app.
+ */
+export declare class AnalyticsIdentity {
+    constructor(cfg: AnalyticsIdentityCfg);
+    private cfg;
+    /**
+     * Fallback identity for when storage is unavailable, and the last-known-good copy
+     * if storage becomes unreadable later.
+     */
+    private memoryEntry;
+    private hasRefreshedExpiry;
+    getDistinctId(): MixpanelDistinctId;
+    /**
+     * The bare (unprefixed) device UUID. Undefined for legacy identities persisted before
+     * a device id was stored (their `distinct_id` has no device prefix either).
+     */
+    getDeviceId(): string | undefined;
+    /**
+     * Reads any property of the persisted entry: the acquisition props maintained by
+     * updateAcquisitionProps(), or props written by another app sharing the entry.
+     */
+    getProperty(key: string): unknown;
+    /**
+     * The acquisition props that can't be derived from event payloads, and are stored separately.
+     */
+    getAcquisitionProps(): AnyObject;
+    /** The captured first touch, as the props to `$set_once` on the profile. */
+    getFirstTouchProps(): SetOnceUserProperties | undefined;
+    /**
+     * Sets the identity going forward, e.g after a successful signup/login.
+     * `$device_id` is kept, so the destination can merge the pre-identify
+     * anonymous events into the same user.
+     */
+    identify(userId: string): void;
+    /**
+     * Clears the whole persisted entry and generates a fresh anonymous identity.
+     * Call only when switching to an UNRELATED identity (e.g logout): everything else stored
+     * in the entry may belong to the previous user, so it goes too.
+     */
+    reset(): void;
+    /** Collects properties of the user that can be used to attribute traffic. */
+    updateAcquisitionProps(): void;
+    private ensureIdentity;
+    /**
+     * The cookie expiration window slides: expireDays counts from the LAST visit, not the
+     * first. Re-saved once per instance (in practice - once per pageload).
+     */
+    private refreshExpiry;
+    private loadEntry;
+    private saveEntry;
+    private cookieLength;
+    private reportError;
+}
+/** The first visible value under this name, or null. */
+export declare function getCookie(name: string): string | null;
+/**
+ * Writes the cookie and returns what was written, which the tests assert on.
+ * `domain` is explicit, e.g `.example.com` to share it across subdomains.
+ */
+export declare function setCookie(name: string, value: string, days: PositiveInteger, domain: string, isSecure: boolean): string;
+export declare class AnalyticsClientError extends AppError {
+    constructor(message: string, data?: ErrorData);
+}
+/** Listener called for every delivered event. */
+/**
+ * A call recorded by an inline stub before the client loaded, e.g
+ * `{ method: 'track', args: ['Click', { element: 'cta' }], ts: Date.now() }`.
+ */
+declare global {
+    var analyticsClient: AnalyticsClient | AnalyticsClientStub | undefined;
+}
+/** The stub a page assigns to `globalThis.analyticsClient` before the client loads. */
+export interface AnalyticsClientStub extends AnalyticsClientApi {
+    q: StubbedCall[];
+}
+/** What a page can call, on the loaded client or on a stub standing in for it. */
+export interface AnalyticsClientApi {
+    init: () => void;
+    track: (name: string, props?: AnyObject) => void;
+    identify: (userId: string) => void;
+    onEvent: (listener: AnalyticsEventListener) => () => void;
+    reset: () => void;
+    flushNow: () => void;
+    destroy: () => void;
+}
+export type StubbedCall = {
+    method: 'track';
+    args: [name: string, props?: AnyObject];
+    ts: UnixTimestampMillis;
+} | {
+    method: 'identify';
+    args: [userId: string];
+    ts: UnixTimestampMillis;
+};
+export interface AnalyticsClientCfg {
+    /**
+     * Full url of the ingestion endpoint, e.g `https://api.example.com/web/e`.
+     */
+    url: string;
+    /**
+     * Full url of the first-touch endpoint, e.g `https://api.example.com/web/ft`.
+     * Omit to not send first-touch profile props at all.
+     */
+    firstTouchUrl?: string;
+    clientId: ClientId;
+    /**
+     * Evaluated on every init(), track() and identify() call; return false to gate them all.
+     * Use it for bot/e2e/consent gating.
+     * Defaults to always-enabled (tracking is still client-side only).
+     */
+    isEnabled?: () => boolean;
+    /**
+     * Props merged into every event, evaluated at track() time. Per-call props win.
+     */
+    getCommonProps?: () => AnyObject;
+    /**
+     * Cfg of the built-in identity (see AnalyticsIdentity), constructed by the client and
+     * exposed as `client.identity`.
+     * Use cookie persistence to share the identity across subdomains.
+     */
+    identity: AnalyticsIdentityCfg;
+    /**
+     * How often the queue is flushed.
+     * Default 5000.
+     */
+    flushInterval?: NumberOfMilliseconds;
+    /**
+     * Max events per request. The queue also flushes early when it's reached.
+     * Default 50.
+     */
+    maxBatchSize?: PositiveInteger;
+    /**
+     * Max serialized request body size. Default 60_000, leaving headroom below
+     * the browser keepalive request limit of 65_536 bytes.
+     */
+    maxBatchBytes?: PositiveInteger;
+    /**
+     * Max events held in the queue while the endpoint is unreachable.
+     * Oldest events are dropped beyond it. Default 1000.
+     */
+    maxQueueSize?: PositiveInteger;
+    /**
+     * Cap for the exponential retry backoff. Default 10 minutes.
+     */
+    maxRetryBackoff?: NumberOfMilliseconds;
+    /**
+     * Per-request timeout. Default 30_000.
+     */
+    requestTimeout?: NumberOfMilliseconds;
+    /**
+     * Persist unsent events in localStorage and restore them on the next page load,
+     * so events survive crashes/killed tabs. There is no cross-tab locking - dedupe by
+     * event id makes duplicates harmless.
+     * Default true.
+     */
+    persistQueue?: boolean;
+    /**
+     * Max age of persisted events to restore; older ones are discarded. Default 24 hours.
+     */
+    maxPersistedAge?: NumberOfMilliseconds;
+    /**
+     * localStorage key prefix for the queue snapshots. Default 'nca'.
+     */
+    localStorageKeyPrefix?: string;
+    /**
+     * Default `console`.
+     */
+    logger?: CommonLogger;
+    /**
+     * Log every tracked event. Default false.
+     */
+    debug?: boolean;
+    /** Called on errors related to tracking events. */
+    onError?: (err: unknown) => void;
+}
+export interface AnalyticsIdentityCfg {
+    /**
+     * Where the identity is persisted:
+     * 'cookie' - shareable across subdomains via `cookieDomain`,
+     * 'localStorage' - per-origin, for when cross-(sub)domain sharing is not needed.
+     */
+    persistence: 'cookie' | 'localStorage';
+    /**
+     * Cookie name / localStorage key. Apps sharing an identity must use the same one,
+     * and must rename in lockstep, otherwise their identities diverge on the next
+     * identify()/reset().
+     */
+    persistenceKey: string;
+    /**
+     * Explicit cookie domain, e.g `.example.com` to share the identity across subdomains.
+     * Default '' - a host-only cookie.
+     */
+    cookieDomain?: string;
+    /**
+     * Cookie lifetime in days, sliding: re-saved on first use of each pageload. Default 365.
+     */
+    expireDays?: PositiveInteger;
+    /**
+     * Sets the `secure` cookie attribute. Default false.
+     */
+    secureCookie?: boolean;
+    /**
+     * Builds the distinct id of a new anonymous identity from its generated device id.
+     * Apps sharing an identity must use the same one, otherwise their identities diverge.
+     */
+    generateDistinctId?: (deviceId: string) => string;
+    /** Called on errors related to persisting the identity. */
+    onError?: (err: unknown) => void;
+}
+/** Analytics properties we only persist once and don't set again. */
+export interface FirstTouch {
+    referrer: string | null;
+    utms?: FirstTouchUtms;
+}