@glassanalytics/browser 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+import { Value, FlagDefinition } from '@glassanalytics/core';
+
+type FlagValue = string | boolean | undefined;
+/** Options for flag reads (`SDK.md` §8). */
+interface FlagOptions {
+    /** Suppress the `$exposure` event for this read (e.g. internal checks). */
+    trackExposure?: boolean;
+    /** Value to return when the flag is unknown. */
+    fallback?: FlagValue;
+}
+/** `glass.init()` config (`SDK.md` §2). */
+interface GlassConfig {
+    /** Required. Publishable client key, scoped to one project (write-only). */
+    projectKey: string;
+    /** Where batches POST. */
+    ingestHost?: string;
+    /** Control-plane host for flag bootstrap / SDK config. */
+    apiHost?: string;
+    replay?: boolean;
+    autocapture?: boolean;
+    errors?: boolean;
+    /** Opt-in: capture `console.error`/`console.warn` as breadcrumbs/errors (§5). Default off. */
+    captureConsole?: boolean;
+    /** Fraction of sessions recorded (client-side). */
+    sampleRate?: number;
+    consent?: 'implied' | 'opt-in' | 'opt-out';
+    maskAllInputs?: boolean;
+    maskTextSelector?: string;
+    blockSelector?: string;
+    respectDoNotTrack?: boolean;
+    flushIntervalMs?: number;
+    flushAt?: number;
+    /** Last chance to mutate/drop before transmit (§9). */
+    beforeSend?: (event: GlassEvent) => GlassEvent | null;
+    /** Server-rendered resolved flag values for this user (no flicker, §8). */
+    bootstrapFlags?: Record<string, FlagValue>;
+    /**
+     * Optional flag DEFINITIONS for local (offline / property-aware) bucketing via
+     * `@glassanalytics/core` evaluateFlag. The hosted server intentionally does NOT leak the
+     * rule set, so this is for self-host / advanced setups that ship definitions.
+     */
+    flagDefinitions?: FlagDefinition[];
+}
+interface GlassEvent {
+    type: 'track' | 'identify' | 'group' | 'error' | 'exposure';
+    event?: string;
+    seq: number;
+    t_client: string;
+    props?: Record<string, Value>;
+}
+
+/**
+ * The Glass browser client (`SDK.md` §3). One small object: identity, events,
+ * errors, replay and flags. Non-blocking by construction; nothing here should
+ * ever be on the app's critical path.
+ */
+declare class Glass {
+    private cfg;
+    private transport;
+    private replay;
+    private deviceId;
+    private sessionId;
+    private userId;
+    private traits;
+    private groupCtx;
+    private superProps;
+    private seq;
+    private lastActivity;
+    private flags;
+    private flagsLoaded;
+    private flagListeners;
+    private optedOut;
+    private started;
+    /** Calls made before init() are queued and replayed once started (`SDK.md` §2). */
+    private preInitQueue;
+    /** Removers for every listener/patch we install, so shutdown() leaves no trace. */
+    private teardowns;
+    init(config: GlassConfig): void;
+    private afterConsent;
+    /** Register a DOM listener and remember how to remove it on shutdown(). */
+    private addListener;
+    /**
+     * Flush on tab hide (`SDK.md` §10). `visibilitychange`→hidden is the most
+     * reliable "user is leaving" signal on mobile (where `pagehide`/`unload` are
+     * unreliable), so we drain the buffer with a beacon while we still can.
+     */
+    private installVisibilityFlush;
+    private loadDeviceId;
+    private loadSession;
+    private persistSession;
+    private touchSession;
+    /** Queue a call made before init() so nothing is lost; returns true if deferred. */
+    private deferred;
+    identify(userId: string, traits?: Record<string, Value>): void;
+    reset(): void;
+    getDeviceId(): string;
+    getSessionId(): string;
+    getSessionReplayUrl(): string;
+    groupIdentify(type: string, key: string, traits?: Record<string, Value>): void;
+    /** Alias for `groupIdentify` (`SDK.md` API parity). */
+    group(type: string, key: string, traits?: Record<string, Value>): void;
+    register(props: Record<string, Value>): void;
+    unregister(key: string): void;
+    track(event: string, props?: Record<string, Value>): void;
+    private emit;
+    /** Device/screen context attached to EVERY event (`SDK.md` §4). */
+    private contextProps;
+    private pageProps;
+    captureException(error: unknown, context?: Record<string, Value>): void;
+    /** Breadcrumb with optional category (`SDK.md` API parity). */
+    addBreadcrumb(arg: string | {
+        category?: string;
+        message: string;
+        data?: Record<string, Value>;
+    }, data?: Record<string, Value>): void;
+    private installErrorHandlers;
+    /**
+     * Opt-in console capture (`SDK.md` §5): mirror `console.error`/`console.warn`
+     * into Glass (errors as exceptions, warnings as breadcrumbs) while ALWAYS
+     * calling through to the original console, so we never swallow the developer's
+     * own logs. Restored verbatim on shutdown().
+     */
+    private installConsoleCapture;
+    private rageWindow;
+    private installAutocapture;
+    /** Stable, value-free descriptor of a clicked element. */
+    private elementProps;
+    /** Three+ clicks within 1s at roughly one spot = a rage click (frustration signal). */
+    private detectRageClick;
+    /** SPA route changes: patch History + listen to popstate, de-duping same-URL. */
+    private lastPath;
+    private installSpaPageviews;
+    startSessionRecording(): void;
+    stopSessionRecording(): void;
+    reloadFeatureFlags(): Promise<void>;
+    onFlagsLoaded(fn: (flags: Record<string, FlagValue>) => void): void;
+    /**
+     * Resolve a flag value with precedence: locally-evaluated definition (if the
+     * app shipped one, so targeting reflects CURRENT properties) → server/bootstrap
+     * resolved value → fallback.
+     */
+    private resolve;
+    /** Local bucketing via @glassanalytics/core when definitions were provided to init(). */
+    private evaluateLocal;
+    isFeatureEnabledSync(key: string, opts?: FlagOptions): boolean;
+    isFeatureEnabled(key: string, opts?: FlagOptions): Promise<boolean>;
+    getFeatureFlagSync(key: string, opts?: FlagOptions): FlagValue;
+    getFeatureFlag(key: string, opts?: FlagOptions): Promise<FlagValue>;
+    getVariantSync(key: string, opts?: FlagOptions): FlagValue;
+    getVariant(key: string, opts?: FlagOptions): Promise<FlagValue>;
+    /** Fire a `$exposure` once per (flag, value) so experiment analysis is honest (§8). */
+    private exposedKeys;
+    private exposure;
+    optIn(): void;
+    optOut(): void;
+    hasConsent(): boolean;
+    flush(): Promise<void>;
+    shutdown(): void;
+}
+/** Default singleton, mirroring the ergonomic `glass.init(...)` usage in `SDK.md`. */
+declare const glass: Glass;
+
+export { type FlagOptions, type FlagValue, Glass, type GlassConfig, type GlassEvent, glass as default, glass };