@leanbase.com/js 0.1.3 → 0.2.0-alpha.1

package/lib/types.d.ts

@@ -0,0 +1,592 @@
+import { FeatureFlagValue, JsonType, PostHogCoreOptions } from '@posthog/core';
+import { KnownUnsafeEditableEvent } from '@posthog/core';
+import { Leanbase } from './leanbase';
+export declare const COPY_AUTOCAPTURE_EVENT = "$copy_autocapture";
+export type Property = any;
+export type Properties = Record<string, Property>;
+export type AutocaptureCompatibleElement = 'a' | 'button' | 'form' | 'input' | 'select' | 'textarea' | 'label';
+export type DomAutocaptureEvents = 'click' | 'change' | 'submit';
+export interface BootstrapConfig {
+    distinctId?: string;
+    isIdentifiedId?: boolean;
+    featureFlags?: Record<string, FeatureFlagValue>;
+    featureFlagPayloads?: Record<string, JsonType>;
+    /**
+     * Optionally provide a sessionID, this is so that you can provide an existing sessionID here to continue a user's session across a domain or device. It MUST be:
+     * - unique to this user
+     * - a valid UUID v7
+     * - the timestamp part must be <= the timestamp of the first event in the session
+     * - the timestamp of the last event in the session must be < the timestamp part + 24 hours
+     * **/
+    sessionID?: string;
+}
+/**
+ * If an array is passed for an allowlist, autocapture events will only be sent for elements matching
+ * at least one of the elements in the array. Multiple allowlists can be used
+ */
+export interface AutocaptureConfig {
+    /**
+     * List of URLs to allow autocapture on, can be strings to match
+     * or regexes e.g. ['https://example.com', 'test.com/.*']
+     * this is useful when you want to autocapture on specific pages only
+     *
+     * if you set both url_allowlist and url_ignorelist,
+     * we check the allowlist first and then the ignorelist.
+     * the ignorelist can override the allowlist
+     */
+    url_allowlist?: (string | RegExp)[];
+    /**
+     * List of URLs to not allow autocapture on, can be strings to match
+     * or regexes e.g. ['https://example.com', 'test.com/.*']
+     * this is useful when you want to autocapture on most pages but not some specific ones
+     *
+     * if you set both url_allowlist and url_ignorelist,
+     * we check the allowlist first and then the ignorelist.
+     * the ignorelist can override the allowlist
+     */
+    url_ignorelist?: (string | RegExp)[];
+    /**
+     * List of DOM events to allow autocapture on  e.g. ['click', 'change', 'submit']
+     */
+    dom_event_allowlist?: DomAutocaptureEvents[];
+    /**
+     * List of DOM elements to allow autocapture on
+     * e.g. ['a', 'button', 'form', 'input', 'select', 'textarea', 'label']
+     *
+     * We consider the tree of elements from the root to the target element of the click event
+     * so for the tree `div > div > button > svg`
+     * if the allowlist has `button` then we allow the capture when the `button` or the `svg` is the click target
+     * but not if either of the `div`s are detected as the click target
+     */
+    element_allowlist?: AutocaptureCompatibleElement[];
+    /**
+     * List of CSS selectors to allow autocapture on
+     * e.g. ['[ph-capture]']
+     * we consider the tree of elements from the root to the target element of the click event
+     * so for the tree div > div > button > svg
+     * and allow list config `['[id]']`
+     * we will capture the click if the click-target or its parents has any id
+     *
+     * Everything is allowed when there's no allowlist
+     */
+    css_selector_allowlist?: string[];
+    /**
+     * Exclude certain element attributes from autocapture
+     * E.g. ['aria-label'] or [data-attr-pii]
+     */
+    element_attribute_ignorelist?: string[];
+    /**
+     * When set to true, autocapture will capture the text of any element that is cut or copied.
+     */
+    capture_copied_text?: boolean;
+}
+export interface LeanbaseConfig extends Partial<PostHogCoreOptions> {
+    /**
+     * API host for Leanbase
+     * @default 'https://i.leanbase.co'
+     */
+    host?: string;
+    /**
+     * The token for your Leanbase project.
+     * It should NOT be provided manually in the config, but rather passed as the first parameter to `leanbase.init()`.
+     */
+    token: string;
+    /**
+     * Enables debug mode, which provides more verbose logging for development purposes.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Determines whether Leanbase should autocapture events.
+     * This setting does not affect capturing pageview events (see `capture_pageview`).
+     *
+     * by default autocapture is ignored on elements that match a `ph-no-capture` css class on the element or a parent
+     * @default true
+     */
+    autocapture: boolean | AutocaptureConfig;
+    /**
+     * Determines whether Leanbase should capture pageview events automatically.
+     * Can be:
+     * - `true`: Capture regular pageviews (default)
+     * - `false`: Don't capture any pageviews
+     * - `'history_change'`: Only capture pageviews on history API changes (pushState, replaceState, popstate)
+     *
+     * @default true
+     */
+    capture_pageview: boolean | 'history_change';
+    /**
+     * Determines the session idle timeout in seconds.
+     * Any new event that's happened after this timeout will create a new session.
+     *
+     * @default 30 * 60 -- 30 minutes
+     */
+    session_idle_timeout_seconds: number;
+    /**
+     * An object containing the `distinctID`, `isIdentifiedID`, and `featureFlags` keys,
+     * where `distinctID` is a string, and `featureFlags` is an object of key-value pairs.
+     *
+     * Since there is a delay between initializing Leanbase and fetching feature flags,
+     * feature flags are not always available immediately.
+     * This makes them unusable if you want to do something like redirecting a user
+     * to a different page based on a feature flag.
+     *
+     * You can, therefore, fetch the feature flags in your server and pre-fill them here,
+     * allowing Leanbase to know the feature flag values immediately.
+     *
+     * After the SDK fetches feature flags from Leanbase, it will use those flag values instead of bootstrapped ones.
+     *
+     * @default {}
+     */
+    bootstrap: BootstrapConfig;
+    /**
+     * Determines whether Leanbase should capture pageleave events.
+     * If set to `true`, it will capture pageleave events for all pages.
+     * If set to `'if_capture_pageview'`, it will only capture pageleave events if `capture_pageview` is also set to `true` or `'history_change'`.
+     *
+     * @default 'if_capture_pageview'
+     */
+    capture_pageleave: boolean | 'if_capture_pageview';
+    /**
+     * Determines whether Leanbase should capture rage clicks.
+     *
+     * by default rageclicks are ignored on elements that match a `ph-no-capture` or `ph-no-rageclick` css class on the element or a parent
+     * @default true
+     */
+    rageclick: boolean | RageclickConfig;
+    /**
+     * Determines where to store the Leanbase persistence information.
+     */
+    persistence: 'localStorage' | 'cookie' | 'memory' | 'localStorage+cookie' | 'sessionStorage';
+    /**
+     * The name for the super properties persistent store
+     *
+     * @default ''
+     */
+    persistence_name: string;
+    /**
+     * Prevent autocapture from capturing any attribute names on elements.
+     *
+     * @default false
+     */
+    mask_all_element_attributes: boolean;
+    /**
+     * Prevent autocapture from capturing `textContent` on elements.
+     *
+     * @default false
+     */
+    mask_all_text: boolean;
+    /**
+     * Used to extend the list of campaign parameters that are saved by default.
+     *
+     * @see {CAMPAIGN_PARAMS} from './utils/event-utils' - Default campaign parameters like utm_source, utm_medium, etc.
+     * @default []
+     */
+    custom_campaign_params: string[];
+    /**
+     * Mask personal data properties from the current URL.
+     * This will mask personal data properties such as advertising IDs (gclid, fbclid, etc.), and you can also add
+     * custom properties to mask with `custom_personal_data_properties`.
+     * @default false
+     * @see {PERSONAL_DATA_CAMPAIGN_PARAMS} - Default campaign parameters that are masked by default.
+     * @see {LeanbaseConfig.custom_personal_data_properties} - Custom list of personal data properties to mask.
+     */
+    mask_personal_data_properties: boolean;
+    /**
+     * Custom list of personal data properties to mask.
+     *
+     * E.g. if you added `email` to this list, then any `email` property in the URL will be masked.
+     * https://www.example.com/login?email=john.doe%40example.com => https://www.example.com/login?email=<MASKED>
+     *
+     * @default []
+     * @see {LeanbaseConfig.mask_personal_data_properties} - Must be enabled for this to take effect.
+     */
+    custom_personal_data_properties: string[];
+    /**
+     * Determines the number of days to store cookies for.
+     *
+     * @default 365
+     */
+    cookie_expiration: number;
+    /**
+     * Determines whether Leanbase should use secure cookies.
+     * If this is `true`, Leanbase cookies will be marked as secure,
+     * meaning they will only be transmitted over HTTPS.
+     *
+     * @default window.location.protocol === 'https:'
+     */
+    secure_cookie: boolean;
+    /**
+     * Determines if cookie should be set on the top level domain (example.com).
+     * If leanbase-js is loaded on a subdomain (test.example.com), and `cross_subdomain_cookie` is set to false,
+     * it'll set the cookie on the subdomain only (test.example.com).
+     *
+     * NOTE: It will be set to `false` if we detect that the domain is a subdomain of a platform that is excluded from cross-subdomain cookie setting.
+     * The current list of excluded platforms is `herokuapp.com`, `vercel.app`, and `netlify.app`.
+     *
+     * @see `isCrossDomainCookie`
+     * @default true
+     */
+    cross_subdomain_cookie: boolean;
+    /**
+     * Determines whether Leanbase should disable persistence.
+     * If set to `true`, the library will not save any data to the browser. It will also delete any data previously saved to the browser.
+     *
+     * @default false
+     */
+    disable_persistence: boolean;
+    /**
+     * Enables cookieless mode. In this mode, Leanbase will not set any cookies, or use session or local storage. User
+     * identity is handled by generating a privacy-preserving hash on Leanbase's servers.
+     * - 'always' - enable cookieless mode immediately on startup, use this if you do not intend to show a cookie banner
+     * - 'on_reject' - enable cookieless mode only if the user rejects cookies, use this if you want to show a cookie banner. If the user accepts cookies, cookieless mode will not be used, and Leanbase will use cookies and local storage as usual.
+     *
+     * Note that you MUST enable cookieless mode in your Leanbase project's settings, otherwise all your cookieless events will be ignored. We plan to remove this requirement in the future.
+     * */
+    cookieless_mode?: 'always' | 'on_reject';
+    /**
+     * Determines whether Leanbase should save referrer information.
+     *
+     * @default true
+     */
+    save_referrer: boolean;
+    /**
+     * Determines whether Leanbase should save marketing parameters.
+     * These are `utm_*` paramaters and friends.
+     *
+     * @see {CAMPAIGN_PARAMS} from './utils/event-utils' - Default campaign parameters like utm_source, utm_medium, etc.
+     * @default true
+     */
+    save_campaign_params: boolean;
+    /**
+     * Determines whether to disable scroll properties.
+     * These allow you to keep track of how far down someone scrolled in your website.
+     *
+     * @default false
+     */
+    disable_scroll_properties?: boolean;
+    /**
+     * Let the pageview scroll stats use a custom css selector for the root element, e.g. `main`
+     * It will use `window.document.documentElement` if not specified.
+     */
+    scroll_root_selector?: string | string[];
+    /**
+     * Determines if users should be opted out of user agent filtering such as googlebot or other bots.
+     * If this is set to `true`, Leanbase will set `$browser_type` to either `bot` or `browser` for all events,
+     * but will process all events as if they were from a browser.
+     *
+     * @default false
+     */
+    opt_out_useragent_filter: boolean;
+    /**
+     * Determines the maximum length of the properties string that can be sent with capture calls.
+     *
+     * @default 65535
+     */
+    properties_string_max_length: number;
+    /**
+     * Determines whether Leanbase should respect the Do Not Track header when computing
+     * consent in `ConsentManager`.
+     *
+     * @see `ConsentManager`
+     * @default false
+     */
+    respect_dnt: boolean;
+    /**
+     * Determines if users should be opted out of Leanbase tracking by default,
+     * requiring additional logic to opt them into capturing by calling `leanbase.opt_in_capturing()`.
+     *
+     * @default false
+     */
+    opt_out_capturing_by_default: boolean;
+    /**
+     * Determines where we'll save the information about whether users are opted out of capturing.
+     *
+     * @default 'localStorage'
+     */
+    opt_out_capturing_persistence_type: 'localStorage' | 'cookie';
+    /**
+     * Determines if users should be opted out of Leanbase data storage by this Leanbase instance by default,
+     * requiring additional logic to opt them into capturing by calling `leanbase.opt_in_capturing()`.
+     *
+     * @default false
+     */
+    opt_out_persistence_by_default?: boolean;
+    /** @deprecated Use `consent_persistence_name` instead. This will be removed in a future major version. **/
+    opt_out_capturing_cookie_prefix: string | null;
+    /**
+     * Determines the key for the cookie / local storage used to store the information about whether users are opted in/out of capturing.
+     * When `null`, we used a key based on your token.
+     *
+     * @default null
+     * @see `ConsentManager._storageKey`
+     */
+    consent_persistence_name: string | null;
+    /**
+     * Function to get the device ID.
+     * This doesn't usually need to be set, but can be useful if you want to use a custom device ID.
+     *
+     * @param uuid - The UUID we would use for the device ID.
+     * @returns The device ID.
+     *
+     * @default (uuid) => uuid
+     */
+    getDeviceId: (uuid: string) => string;
+    /**
+     * A function to be called once the Leanbase scripts have loaded successfully.
+     *
+     * @param instance - The Leanbase instance that has been loaded.
+     */
+    loaded: (instance: Leanbase) => void;
+}
+export interface RageclickConfig {
+    /**
+     * List of CSS selectors to ignore rageclicks on
+     * e.g. ['.my-calendar-button']
+     * we consider the tree of elements from the root to the target element of the click event
+     * so for the tree div > div > button > svg
+     * and ignore list config `['[id]']`
+     * we will ignore the rageclick if the click-target or its parents has any id
+     *
+     * Nothing is ignored when there's an empty ignorelist, e.g. []
+     * If no ignorelist is set, we default to ignoring .ph-no-rageclick
+     * If an element has .ph-no-capture, it will always be ignored by rageclick and autocapture
+     */
+    css_selector_ignorelist?: string[];
+}
+export type PropertyMatchType = 'regex' | 'not_regex' | 'exact' | 'is_not' | 'icontains' | 'not_icontains';
+export interface ErrorTrackingSuppressionRule {
+    type: 'AND' | 'OR';
+    values: ErrorTrackingSuppressionRuleValue[];
+}
+export interface ErrorTrackingSuppressionRuleValue {
+    key: '$exception_types' | '$exception_values';
+    operator: PropertyMatchType;
+    value: string | string[];
+    type: string;
+}
+export declare enum Compression {
+    GZipJS = "gzip-js",
+    Base64 = "base64"
+}
+export type SupportedWebVitalsMetrics = 'LCP' | 'CLS' | 'FCP' | 'INP';
+export interface PerformanceCaptureConfig {
+    /**
+     *  Works with session replay to use the browser's native performance observer to capture performance metrics
+     */
+    network_timing?: boolean;
+    /**
+     * Use chrome's web vitals library to wrap fetch and capture web vitals
+     */
+    web_vitals?: boolean;
+    /**
+     * We observe very large values reported by the Chrome web vitals library
+     * These outliers are likely not real, useful values, and we exclude them
+     * You can set this to 0 in order to include all values, NB this is not recommended
+     *
+     * @default 15 * 60 * 1000 (15 minutes)
+     */
+    __web_vitals_max_value?: number;
+    /**
+     * By default all 4 metrics are captured
+     * You can set this config to restrict which metrics are captured
+     * e.g. ['CLS', 'FCP'] to only capture those two metrics
+     * NB setting this does not override whether the capture is enabled
+     *
+     * @default ['LCP', 'CLS', 'FCP', 'INP']
+     */
+    web_vitals_allowed_metrics?: SupportedWebVitalsMetrics[];
+    /**
+     * We delay flushing web vitals metrics to reduce the number of events we send
+     * This is the maximum time we will wait before sending the metrics
+     *
+     * @default 5000
+     */
+    web_vitals_delayed_flush_ms?: number;
+}
+/**
+ * Remote configuration for the Leanbase instance
+ *
+ * All of these settings can be configured directly in your Leanbase instance
+ * Any configuration set in the client overrides the information from the server
+ */
+export interface RemoteConfig {
+    /**
+     * Supported compression algorithms
+     */
+    supportedCompression: Compression[];
+    /**
+     * If set, disables autocapture
+     */
+    autocapture_opt_out?: boolean;
+    /**
+     *     originally capturePerformance was replay only and so boolean true
+     *     is equivalent to { network_timing: true }
+     *     now capture performance can be separately enabled within replay
+     *     and as a standalone web vitals tracker
+     *     people can have them enabled separately
+     *     they work standalone but enhance each other
+     *     TODO: deprecate this so we make a new config that doesn't need this explanation
+     */
+    capturePerformance?: boolean | PerformanceCaptureConfig;
+    /**
+     * Whether we should use a custom endpoint for analytics
+     *
+     * @default { endpoint: "/e" }
+     */
+    analytics?: {
+        endpoint?: string;
+    };
+    /**
+     * Whether the `$elements_chain` property should be sent as a string or as an array
+     *
+     * @default false
+     */
+    elementsChainAsString?: boolean;
+    /**
+     * Error tracking configuration options
+     */
+    errorTracking?: {
+        autocaptureExceptions?: boolean;
+        captureExtensionExceptions?: boolean;
+        suppressionRules?: ErrorTrackingSuppressionRule[];
+    };
+    /**
+     * This is currently in development and may have breaking changes without a major version bump
+     */
+    autocaptureExceptions?: boolean | {
+        endpoint?: string;
+    };
+    /**
+     * @deprecated, moved to toolbarParams
+     */
+    toolbarVersion: 'toolbar';
+    /**
+     * Whether the user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * List of site apps with their IDs and URLs
+     */
+    siteApps: {
+        id: string;
+        url: string;
+    }[];
+    /**
+     * Whether heatmaps are enabled
+     */
+    heatmaps?: boolean;
+    /**
+     * Whether to only capture identified users by default
+     */
+    defaultIdentifiedOnly?: boolean;
+    /**
+     * Whether to capture dead clicks
+     */
+    captureDeadClicks?: boolean;
+    /**
+     * Indicates if the team has any flags enabled (if not we don't need to load them)
+     */
+    hasFeatureFlags?: boolean;
+}
+/**
+ * These are known events Leanbase events that can be processed by the `beforeCapture` function
+ * That means Leanbase functionality does not rely on receiving 100% of these for calculations
+ * So, it is safe to sample them to reduce the volume of events sent to Leanbase
+ */
+export type KnownEventName = '$heatmaps_data' | '$opt_in' | '$exception' | '$$heatmap' | '$web_vitals' | '$dead_click' | '$autocapture' | typeof COPY_AUTOCAPTURE_EVENT | '$rageclick';
+export type EventName = KnownUnsafeEditableEvent | KnownEventName | (string & {});
+export interface PersistentStore {
+    _is_supported: () => boolean;
+    _error: (error: any) => void;
+    _parse: (name: string) => any;
+    _get: (name: string) => any;
+    _set: (name: string, value: any, expire_days?: number | null, cross_subdomain?: boolean, secure?: boolean, debug?: boolean) => void;
+    _remove: (name: string, cross_subdomain?: boolean) => void;
+}
+export interface RequestResponse {
+    statusCode: number;
+    text?: string;
+    json?: any;
+}
+export type RequestCallback = (response: RequestResponse) => void;
+type NextOptions = {
+    revalidate: false | 0 | number;
+    tags: string[];
+};
+export interface RequestWithOptions {
+    url: string;
+    data?: Record<string, any> | Record<string, any>[];
+    headers?: Record<string, any>;
+    transport?: 'XHR' | 'fetch' | 'sendBeacon';
+    method?: 'POST' | 'GET';
+    urlQueryArgs?: {
+        compression: Compression;
+    };
+    callback?: RequestCallback;
+    timeout?: number;
+    noRetries?: boolean;
+    disableTransport?: ('XHR' | 'fetch' | 'sendBeacon')[];
+    disableXHRCredentials?: boolean;
+    compression?: Compression | 'best-available';
+    fetchOptions?: {
+        cache?: RequestInit['cache'];
+        next?: NextOptions;
+    };
+}
+export type SessionIdChangedCallback = (sessionId: string, windowId: string | null | undefined, changeReason?: {
+    noSessionId: boolean;
+    activityTimeout: boolean;
+    sessionPastMaximumLength: boolean;
+}) => void;
+export type LeanbasegCaptureOptions = {
+    /** If provided overrides the auto-generated event ID */
+    uuid?: string;
+    disableGeoip?: boolean;
+    /**
+     * Used when `$identify` is called
+     * Will set person properties overriding previous values
+     */
+    $set?: Properties;
+    /**
+     * Used when `$identify` is called
+     * Will set person properties but only once, it will NOT override previous values
+     */
+    $set_once?: Properties;
+    /**
+     * Used to override the desired endpoint for the captured event
+     */
+    _url?: string;
+    /**
+     * key of queue, e.g. 'sessionRecording' vs 'event'
+     */
+    _batchKey?: string;
+    /**
+     * If set, overrides and disables config.properties_string_max_length
+     */
+    _noTruncate?: boolean;
+    /**
+     * If set, skips the batched queue
+     */
+    send_instantly?: boolean;
+    /**
+     * If set, skips the client side rate limiting
+     */
+    skip_client_rate_limiting?: boolean;
+    /**
+     * If set, overrides the desired transport method
+     */
+    transport?: RequestWithOptions['transport'];
+    /**
+     * If set, overrides the current timestamp
+     */
+    timestamp?: Date;
+};
+export interface CaptureResult {
+    uuid: string;
+    event: EventName;
+    properties: Properties;
+    $set?: Properties;
+    $set_once?: Properties;
+    timestamp?: Date;
+}
+export {};

package/lib/types.js

@@ -0,0 +1,7 @@
+export const COPY_AUTOCAPTURE_EVENT = '$copy_autocapture';
+export var Compression;
+(function (Compression) {
+    Compression["GZipJS"] = "gzip-js";
+    Compression["Base64"] = "base64";
+})(Compression || (Compression = {}));
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAA;AA+ZzD,MAAM,CAAN,IAAY,WAGX;AAHD,WAAY,WAAW;IACnB,iCAAkB,CAAA;IAClB,gCAAiB,CAAA;AACrB,CAAC,EAHW,WAAW,KAAX,WAAW,QAGtB"}

package/lib/utils/blocked-uas.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_BLOCKED_UA_STRS: string[];
+/**
+ * Block various web spiders from executing our JS and sending false capturing data
+ */
+export declare const isBlockedUA: (ua: string, customBlockedUserAgents: string[]) => boolean;
+export interface NavigatorUAData {
+    brands?: {
+        brand: string;
+        version: string;
+    }[];
+}
+declare global {
+    interface Navigator {
+        userAgentData?: NavigatorUAData;
+    }
+}
+export declare const isLikelyBot: (navigator: Navigator | undefined, customBlockedUserAgents: string[]) => boolean;