@incodetech/tri-sdk 0.1.0 → 0.1.2-dev-20260528

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type CollectorKey = 'fingerprint' | 'pointer' | 'pointermove' | 'focus' | 'input' | 'keystroke' | 'clipboard' | 'form' | 'change' | 'selection' | 'visibility' | 'navigation' | 'viewportresize' | 'viewport' | 'scroll' | 'devicemotion' | 'networkrequest' | 'networkconnection' | 'permissionchange' | 'environmental';
+type CollectorKey = 'fingerprint' | 'pointer' | 'pointermove' | 'focus' | 'input' | 'keystroke' | 'clipboard' | 'form' | 'change' | 'selection' | 'visibility' | 'navigation' | 'viewportresize' | 'viewport' | 'scroll' | 'devicemotion' | 'network-request' | 'networkconnection' | 'permissionchange' | 'environmental';
 type CollectorEventMap = {
     pointer: 'pointerdown' | 'pointerup' | 'click' | 'dblclick' | 'contextmenu' | 'dragend';
     focus: 'focusin' | 'focusout';
@@ -16,7 +16,7 @@ type CollectorEventMap = {
     viewportresize: never;
     scroll: never;
     devicemotion: never;
-    networkrequest: never;
+    'network-request': never;
     networkconnection: never;
     permissionchange: never;
     environmental: never;
@@ -24,44 +24,119 @@ type CollectorEventMap = {
 type Layer = 'session' | 'behavioral' | 'device-fingerprinting' | 'environmental-integrity' | 'network-intelligence' | 'persistent-identity';
 
 /**
- * Global PII capture level for the SDK.
+ * Hook that allows the host application to extend or replace the SDK's default
+ * URL sanitiser. Called for every URL before it is placed on the wire.
  *
- * - `'all'`    — all fields emitted; PII identifiers and labels included.
+ * Receives the raw URL and the SDK's `defaultSanitize` implementation.
+ * The host may call `defaultSanitize(url)` to obtain the already-sanitised
+ * string and further transform it (e.g. remove additional path segments it
+ * knows are PII), or may bypass the default entirely for full control.
+ *
+ * If this function throws, the SDK falls back to `defaultSanitize(url)`.
+ *
+ * @example
+ * ```ts
+ * sanitizeUrl: (url, defaultSanitize) => {
+ *   const sanitised = defaultSanitize(url)
+ *   return sanitised.replace(/\/internal\/[^/]+/, '/internal/:id')
+ * }
+ * ```
+ */
+type SanitizeUrlHook = (url: string, defaultSanitize: (url: string) => string) => string;
+/**
+ * Global PII capture level for element context.
+ *
+ * - `'all'`    — all element fields emitted; PII identifiers and labels included.
  *                Consumers should annotate sensitive elements with `data-tri-redact`.
  * - `'redact'` — PII identifiers (`id`, `name`, label, classes) set to `null`.
- *                Default. Per-element overrides via `data-tri-redact` / `data-tri-ignore`.
+ *                **Default.** Per-element overrides via `data-tri-redact` / `data-tri-ignore`.
  * - `'off'`    — Element Context Processor is skipped entirely; `element` is always `null`.
  */
 type CaptureElementLevel = 'all' | 'redact' | 'off';
+/**
+ * Controls whether text content is captured from interacted elements.
+ *
+ * - `'on'`  — text content emitted (default).
+ * - `'off'` — text content field is always `null`.
+ */
 type CaptureContentLevel = 'on' | 'off';
 /**
  * Public SDK configuration. Both `layers` and `collectors` are optional; pass at
  * most one. When neither is provided, every collector defaults to enabled (same
  * behaviour as calling `start()` with no config).
  */
-type TriSDKConfig = TriSDKConfigBase & (LayerBasedConfig | CollectorBasedConfig | NoCollectorSelectionConfig);
-type TriSDKConfigBase = {
+type TRIConfig = TRIConfigBase & (LayerBasedConfig | CollectorBasedConfig | NoCollectorSelectionConfig);
+/**
+ * Supported backend deployment environments.
+ *
+ * Currently provisioned (have a base URL):
+ *  - `'STAGE_K8S'` — Kubernetes staging cluster.
+ *
+ * Known but **not yet provisioned** (will produce a fatal error at start):
+ *  - `'SAAS'`, `'STAGE'`, `'DEMO'`, `'DEMO_K8S'`
+ *
+ * Prefer `apiURL` when targeting a self-hosted or custom deployment.
+ */
+type TriEnv = 'STAGE_K8S' | 'SAAS' | 'STAGE' | 'DEMO' | 'DEMO_K8S';
+/** Shared config fields present regardless of which selector variant is used. */
+type TRIConfigShared = {
     capture?: {
         element?: CaptureElementLevel;
         content?: CaptureContentLevel;
     };
     profileId?: string;
-    api: {
-        key: string;
-        version: string;
-        url: string;
-    };
+    apiKey: string;
+    apiVersion?: string;
+    /**
+     * Optional URL sanitiser hook. When omitted, the SDK applies its built-in
+     * default (strip credentials + fragment, redact query values, tokenise
+     * identifier path segments). Supply this to apply additional redaction
+     * on top of the default or to replace it entirely.
+     */
+    sanitizeUrl?: SanitizeUrlHook;
+    /**
+     * When `true`, the SDK emits diagnostic messages via `logger.warn`,
+     * `logger.error`, and `logger.info`. Defaults to `false`. Has no effect on
+     * `logger.fatal`, which always emits regardless of this flag.
+     */
+    debug?: boolean;
 };
+/**
+ * Exactly one of `env` or `apiURL` must be supplied; both may be supplied
+ * (in which case `apiURL` takes precedence). Omitting both is a type error.
+ */
+type TRIConfigBase = TRIConfigShared & ({
+    env: TriEnv;
+    apiURL?: string;
+} | {
+    apiURL: string;
+    env?: TriEnv;
+});
+/**
+ * Optional per-event configuration inside a collector's `events` map.
+ * Omitted fields take their documented defaults (enabled = true, exclude = []).
+ */
 type EventConfig = {
+    /** When `false` the event type is never emitted. Defaults to `true`. */
     enabled?: boolean;
+    /** DOM selector strings whose targets are excluded from this event type. */
     exclude?: string[];
 };
+/**
+ * Per-collector event configuration exposed in the public `CollectorsConfig`.
+ * Provides a collector-wide exclude list plus per-event `EventConfig` overrides.
+ */
 type CollectorEventsConfig<C extends CollectorKey> = {
     /** Applied to every event emitted by this collector. */
     exclude?: string[];
 } & {
     [E in CollectorEventMap[C]]?: EventConfig;
 };
+/**
+ * Per-collector configuration. Eventless collectors (whose `CollectorEventMap`
+ * entry is `never`) only accept `enabled`; event-bearing collectors additionally
+ * accept an `events` map.
+ */
 type CollectorConfig<C extends CollectorKey> = [CollectorEventMap[C]] extends [
     never
 ] ? {
@@ -70,59 +145,113 @@ type CollectorConfig<C extends CollectorKey> = [CollectorEventMap[C]] extends [
     enabled?: boolean;
     events?: CollectorEventsConfig<C>;
 };
+/**
+ * Host-supplied collector configuration map. Every key is optional — omitted
+ * collectors default to `disabled` when this field is present on `TRIConfig`.
+ */
 type CollectorsConfig = {
     [C in CollectorKey]?: CollectorConfig<C>;
 };
+/** Enables all collectors whose `layer` matches one of the provided keys. Omitted layers default to disabled. */
 type LayerBasedConfig = {
     layers: Partial<Record<Layer, boolean>>;
     collectors?: never;
 };
+/** Enables only the collectors explicitly listed, each with optional per-event overrides. */
 type CollectorBasedConfig = {
     layers?: never;
     collectors: CollectorsConfig;
 };
+/** No collector filtering — all collectors are enabled by default. */
 type NoCollectorSelectionConfig = {
     layers?: never;
     collectors?: never;
 };
-interface TriSDKInterface {
-    start(config?: TriSDKConfig): void;
+/**
+ * Contract for the singleton `TRI` instance exposed to the host application.
+ * All methods are fire-and-forget — none throw, none return values the host must
+ * handle.
+ */
+interface TRIInterface {
+    /** Starts the SDK with the supplied config. Idempotent while running. */
+    start(config?: TRIConfig): void;
+    /** Stops all collectors and tears down every manager. Idempotent. */
+    stop(): void;
+    /** Reports a host-defined event. Drops silently (with a dev warn) if not yet started. */
     reportEvent(name: string, metadata: Record<string, unknown>): void;
 }
 
-declare class TriSDK$1 implements TriSDKInterface {
+/**
+ * Singleton entry-point for the TRI SDK.
+ *
+ * Obtain the instance via `TRI.instance`; the constructor is private.
+ *
+ * ### Life-cycle states
+ * The instance moves through three states:
+ *  - `'idle'`     — not started, or fully stopped.
+ *  - `'starting'` — `start()` has been called; preflight and lazy bundle load in progress.
+ *  - `'started'`  — all managers are running and `reportEvent()` is active.
+ *
+ * ### Never throws
+ * All public methods are fire-and-forget. Errors are logged via `logger` and
+ * swallowed so the host application is never disrupted.
+ *
+ * ### Bundle split
+ * Only the preflight config validator and collection-status check live in the
+ * static bundle. The full manager wiring (`internal/start.ts`) is dynamically
+ * imported only when the backend confirms collection is enabled, keeping the
+ * initial page-load cost minimal.
+ */
+declare class TRI$1 implements TRIInterface {
     private static _instance;
-    private initialized;
+    /**
+     * Monotonically-increasing counter incremented by every `start()` and
+     * `stop()` call. Each in-flight `runStart` captures its own generation value
+     * and bails out after every `await` if the counter has moved on, preventing
+     * orphaned manager instances from being installed after a concurrent stop.
+     */
+    private startGeneration;
+    private startState;
+    private falconServiceManager;
     private activityManager;
     private transportManager;
     private tabManager;
+    private lifecycleManager;
     private collectorManager;
-    private falconServiceManager;
-    constructor();
-    static get instance(): TriSDK$1;
+    private eventReportManager;
+    private constructor();
+    static get instance(): TRI$1;
     /**
-     * Initialises the TRI SDK. Synchronous and idempotent — a second call is a
-     * no-op. Safe to call in SSR environments; if `document` is unavailable the
-     * function logs an error and returns without throwing.
+     * @description Starts the TRI SDK. Fire-and-forget and idempotent — a second
+     * call while the SDK is starting or already started is a no-op. Checks the
+     * backend `/collection-status` endpoint and only loads the full manager bundle
+     * when collection is enabled. Safe to call in SSR environments; if `document`
+     * is unavailable the function logs a fatal and returns without throwing.
      */
-    start(config?: TriSDKConfig): void;
-    private _start;
+    start(config?: TRIConfig): void;
     /**
-     * Reports a host-defined event to the TRI backend. Fire-and-forget — never
-     * throws and never returns a promise the host must handle. Drops the event
-     * silently (with a dev warning) if called before `init`.
+     * @description Stops all collectors, flushes pending events, and tears down
+     * every manager. Safe to call more than once. After `stop()`, `start()` may be
+     * called again with a fresh config. Any in-flight `start()` is cancelled at
+     * the next async checkpoint.
+     */
+    stop(): void;
+    /**
+     * @description Reports a host-defined event to the TRI backend. Fire-and-forget —
+     * never throws and never returns a promise the host must handle. Drops the
+     * event silently (with a dev warning) if called before `start` completes.
      */
     reportEvent(name: string, metadata: Record<string, unknown>): void;
-    private _shouldEarlyEscapeInit;
-    private _shouldEarlyEscapeReportEvent;
-    private _createFalconServiceManagerContext;
-    private _createActivityManagerContext;
-    private _createTransportManagerContext;
-    private _createTabManagerContext;
-    private _createLifecycleManagerContext;
-    private _createCollectorsManagerContext;
+    private _start;
+    /**
+     * Returns `true` (and logs a dev warning) when `reportEvent()` should be a
+     * no-op.  Guards against calling before the SDK is fully started, or when
+     * the `eventReportManager` is unexpectedly absent.
+     */
+    private _shouldEarlyEscapeReport;
 }
 
-declare const TriSDK: TriSDK$1;
+declare const TRI: TRI$1;
 
-export { TriSDK as default };
+export { TRI as default };
+export type { SanitizeUrlHook, TRIConfig, TriEnv as TRIEnv, TRIInterface as TRIInstance };