@watchupltd/browser 0.1.9 → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,254 @@
+interface WatchupUser {
+    /** Your app's internal user ID — the only required field. */
+    id: string | number;
+    email?: string;
+    name?: string;
+    /** Any extra key/value pairs you want attached to events. */
+    [key: string]: unknown;
+}
+interface WatchupOptions {
+    /**
+     * Your project's **public** API key from the Watchup dashboard.
+     * Format: `wup_pub_xxxxxxxxxxxx`
+     * This key is safe to include in client-side code.
+     */
+    apiKey: string;
+    /** Defaults to `https://api.watchup.site`. Override for self-hosted. */
+    baseUrl?: string;
+    /** Flush interval in ms. Default: `5000`. */
+    flushInterval?: number;
+    /** Max items before forcing a flush. Default: `100`. */
+    maxBatchSize?: number;
+    /** Log SDK warnings to `console.warn`. Default: `false`. */
+    debug?: boolean;
+    /** Environment label on every payload. Default: `'production'`. */
+    environment?: string;
+    /** Git SHA / release tag for deploy correlation. */
+    release?: string;
+    /**
+     * Fraction of navigations/fetches captured as traces (0–1).
+     * Default: `1` (100 %).
+     */
+    sampleRate?: number;
+    /** Fine-grained control over what gets captured automatically. */
+    autoCapture?: {
+        /** Capture `window.onerror` and `unhandledrejection`. Default: `true`. */
+        errors?: boolean;
+        /** Capture FCP, LCP, and page-load timing. Default: `true`. */
+        performance?: boolean;
+        /**
+         * Track the initial page view and SPA navigations (History API).
+         * Default: `true`.
+         * Set to `false` when a framework SDK (React, Next.js, Svelte) handles
+         * page view tracking via the router.
+         */
+        pageViews?: boolean;
+    };
+}
+interface TracePayload {
+    span: string;
+    ms: number;
+    status_code: number;
+    status: 'ok' | 'warn' | 'err';
+    timestamp: string;
+    environment?: string;
+    release?: string;
+    meta?: Record<string, unknown>;
+    user?: WatchupUser;
+}
+interface ErrorPayload {
+    message: string;
+    level: 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+    route?: string;
+    stack?: string;
+    context?: Record<string, unknown>;
+    timestamp: string;
+    environment?: string;
+    release?: string;
+    user?: WatchupUser;
+}
+interface EventPayload {
+    name: string;
+    properties?: Record<string, unknown>;
+    occurred_at: string;
+}
+interface IngestBatch {
+    traces?: TracePayload[];
+    errors?: ErrorPayload[];
+    events?: EventPayload[];
+}
+interface WebAnalyticsPayload {
+    /** URL path, e.g. "/pricing". */
+    path: string;
+    /** Hostname of the tracked site, e.g. "example.com". */
+    hostname: string;
+    /** Full referrer URL (document.referrer). */
+    referrer?: string;
+    /** document.title at tracking time. */
+    title?: string;
+    /** Screen width in CSS pixels. */
+    screen_w?: number;
+    /** Screen height in CSS pixels. */
+    screen_h?: number;
+    /** navigator.language, e.g. "en-GB". */
+    lang?: string;
+    /** Intl.DateTimeFormat().resolvedOptions().timeZone */
+    timezone?: string;
+    /** UTM parameters parsed from the current URL's query string. */
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /**
+     * Persistent visitor UUID (stored in localStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    visitor_id: string;
+    /**
+     * Per-session UUID (stored in sessionStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    session_id: string;
+    /** Event type — defaults to "pageview". Use for custom web events. */
+    event_name?: string;
+    /** ISO-8601 timestamp when the event occurred. */
+    occurred_at: string;
+}
+interface FlagVariant {
+    key: string;
+    weight: number;
+}
+interface FlagTargetingRule {
+    attribute: string;
+    operator: 'in' | 'not_in' | 'contains' | 'equals';
+    values: string[];
+}
+interface FeatureFlag {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    rollout_percentage: number;
+    variants: FlagVariant[];
+    targeting_rules: FlagTargetingRule[];
+}
+interface FlagContext {
+    userId?: string | number;
+    email?: string;
+    plan?: string;
+    [key: string]: unknown;
+}
+
+declare class Watchup {
+    private readonly cfg;
+    private readonly batcher;
+    private readonly cleanup;
+    private _user;
+    /**
+     * A random UUID generated on init.  Stable for the lifetime of the page —
+     * useful for correlating all events from one user session.
+     */
+    readonly sessionId: string;
+    /**
+     * Persistent visitor ID.  Stored in localStorage so it survives browser
+     * sessions.  Falls back to a per-session UUID when localStorage is blocked.
+     * The server hashes this value with SHA-256 before persisting.
+     */
+    private readonly visitorId;
+    /**
+     * Per-session ID stored in sessionStorage.  Resets on tab close.
+     * The server hashes this value before persisting.
+     */
+    private readonly webSessionId;
+    private _flags;
+    private _flagTimer;
+    constructor(options: WatchupOptions);
+    private _fetchFlags;
+    private _getOrCreateVisitorId;
+    private _getOrCreateSessionId;
+    /**
+     * Attach a user to all subsequent errors, traces, and events.
+     * Call this after login; the context persists until `clearUser()` or page reload.
+     *
+     * @example
+     * watchup.setUser({ id: '42', email: 'ada@example.com', name: 'Ada Lovelace' });
+     */
+    setUser(user: WatchupUser): void;
+    /**
+     * Remove the current user context (e.g. after logout).
+     */
+    clearUser(): void;
+    /**
+     * Track a custom analytics event.
+     *
+     * @example
+     * watchup.track('button.clicked', { label: 'Sign Up', variant: 'A' });
+     */
+    track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a web analytics page view (or custom web event).
+     * Enriches the payload with visitor context, UTM params, and device info.
+     *
+     * Normally called automatically. Call manually when you need custom event_name.
+     *
+     * @example
+     * watchup.trackWebView({ event_name: 'conversion', path: '/checkout/success' });
+     */
+    trackWebView(overrides?: Partial<WebAnalyticsPayload>): void;
+    /**
+     * Manually capture an error.
+     *
+     * @example
+     * try { ... } catch (err) {
+     *   watchup.captureError(err, { component: 'CheckoutForm' });
+     * }
+     */
+    captureError(error: Error | string | unknown, context?: Record<string, unknown> & {
+        route?: string;
+        level?: ErrorPayload['level'];
+    }): void;
+    /**
+     * Time any async operation and record it as a trace.
+     * Returns an `end()` function — call it when the operation finishes.
+     *
+     * @example
+     * const end = watchup.startTrace('fetch /api/cart');
+     * const cart = await fetch('/api/cart');
+     * end({ status: cart.ok ? 'ok' : 'err' });
+     */
+    startTrace(span: string): (opts?: {
+        status?: TracePayload['status'];
+        meta?: Record<string, unknown>;
+    }) => void;
+    /**
+     * Check whether a feature flag is enabled. Evaluated locally — zero
+     * network latency. Flag rules refresh every 30 seconds in the background.
+     * Falls back to the identified user (via `setUser`) when no context is given.
+     *
+     * @example
+     * if (watchup.isEnabled('new-checkout')) {
+     *   renderNewCheckout();
+     * }
+     */
+    isEnabled(key: string, ctx?: FlagContext): boolean;
+    /**
+     * Get the variant key for a multivariate (A/B) flag.
+     * Returns `"control"` if the flag is off or the visitor isn't in the rollout.
+     *
+     * @example
+     * const variant = watchup.getVariant('pricing-layout');
+     * // → "control" | "variant-a" | "variant-b"
+     */
+    getVariant(key: string, ctx?: FlagContext): string;
+    /** Immediately flush all queued items (both telemetry and web analytics). */
+    flush(): void;
+    /** Stop the flush timer and release all listeners. */
+    shutdown(): void;
+    private _setupAutoCapture;
+    private _setupPageViewTracking;
+    private _timezone;
+}
+
+export { type ErrorPayload, type EventPayload, type FeatureFlag, type FlagContext, type FlagTargetingRule, type FlagVariant, type IngestBatch, type TracePayload, Watchup, type WatchupOptions, type WatchupUser };

package/dist/index.d.ts

@@ -1,10 +1,254 @@
-import { WatchUpClient, WatchUpClientOptions } from "@watchup/core";
-export * from "@watchup/core";
-export interface BrowserWatchUpOptions extends WatchUpClientOptions {
-    autoCaptureErrors?: boolean;
-    autoCaptureUnhandledRejections?: boolean;
-}
-export declare function initBrowserWatchUp(options: BrowserWatchUpOptions): WatchUpClient;
-export declare function getWatchUpClient(): WatchUpClient;
-export declare function shutdownBrowserWatchUp(): void;
-//# sourceMappingURL=index.d.ts.map
+interface WatchupUser {
+    /** Your app's internal user ID — the only required field. */
+    id: string | number;
+    email?: string;
+    name?: string;
+    /** Any extra key/value pairs you want attached to events. */
+    [key: string]: unknown;
+}
+interface WatchupOptions {
+    /**
+     * Your project's **public** API key from the Watchup dashboard.
+     * Format: `wup_pub_xxxxxxxxxxxx`
+     * This key is safe to include in client-side code.
+     */
+    apiKey: string;
+    /** Defaults to `https://api.watchup.site`. Override for self-hosted. */
+    baseUrl?: string;
+    /** Flush interval in ms. Default: `5000`. */
+    flushInterval?: number;
+    /** Max items before forcing a flush. Default: `100`. */
+    maxBatchSize?: number;
+    /** Log SDK warnings to `console.warn`. Default: `false`. */
+    debug?: boolean;
+    /** Environment label on every payload. Default: `'production'`. */
+    environment?: string;
+    /** Git SHA / release tag for deploy correlation. */
+    release?: string;
+    /**
+     * Fraction of navigations/fetches captured as traces (0–1).
+     * Default: `1` (100 %).
+     */
+    sampleRate?: number;
+    /** Fine-grained control over what gets captured automatically. */
+    autoCapture?: {
+        /** Capture `window.onerror` and `unhandledrejection`. Default: `true`. */
+        errors?: boolean;
+        /** Capture FCP, LCP, and page-load timing. Default: `true`. */
+        performance?: boolean;
+        /**
+         * Track the initial page view and SPA navigations (History API).
+         * Default: `true`.
+         * Set to `false` when a framework SDK (React, Next.js, Svelte) handles
+         * page view tracking via the router.
+         */
+        pageViews?: boolean;
+    };
+}
+interface TracePayload {
+    span: string;
+    ms: number;
+    status_code: number;
+    status: 'ok' | 'warn' | 'err';
+    timestamp: string;
+    environment?: string;
+    release?: string;
+    meta?: Record<string, unknown>;
+    user?: WatchupUser;
+}
+interface ErrorPayload {
+    message: string;
+    level: 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+    route?: string;
+    stack?: string;
+    context?: Record<string, unknown>;
+    timestamp: string;
+    environment?: string;
+    release?: string;
+    user?: WatchupUser;
+}
+interface EventPayload {
+    name: string;
+    properties?: Record<string, unknown>;
+    occurred_at: string;
+}
+interface IngestBatch {
+    traces?: TracePayload[];
+    errors?: ErrorPayload[];
+    events?: EventPayload[];
+}
+interface WebAnalyticsPayload {
+    /** URL path, e.g. "/pricing". */
+    path: string;
+    /** Hostname of the tracked site, e.g. "example.com". */
+    hostname: string;
+    /** Full referrer URL (document.referrer). */
+    referrer?: string;
+    /** document.title at tracking time. */
+    title?: string;
+    /** Screen width in CSS pixels. */
+    screen_w?: number;
+    /** Screen height in CSS pixels. */
+    screen_h?: number;
+    /** navigator.language, e.g. "en-GB". */
+    lang?: string;
+    /** Intl.DateTimeFormat().resolvedOptions().timeZone */
+    timezone?: string;
+    /** UTM parameters parsed from the current URL's query string. */
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /**
+     * Persistent visitor UUID (stored in localStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    visitor_id: string;
+    /**
+     * Per-session UUID (stored in sessionStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    session_id: string;
+    /** Event type — defaults to "pageview". Use for custom web events. */
+    event_name?: string;
+    /** ISO-8601 timestamp when the event occurred. */
+    occurred_at: string;
+}
+interface FlagVariant {
+    key: string;
+    weight: number;
+}
+interface FlagTargetingRule {
+    attribute: string;
+    operator: 'in' | 'not_in' | 'contains' | 'equals';
+    values: string[];
+}
+interface FeatureFlag {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    rollout_percentage: number;
+    variants: FlagVariant[];
+    targeting_rules: FlagTargetingRule[];
+}
+interface FlagContext {
+    userId?: string | number;
+    email?: string;
+    plan?: string;
+    [key: string]: unknown;
+}
+
+declare class Watchup {
+    private readonly cfg;
+    private readonly batcher;
+    private readonly cleanup;
+    private _user;
+    /**
+     * A random UUID generated on init.  Stable for the lifetime of the page —
+     * useful for correlating all events from one user session.
+     */
+    readonly sessionId: string;
+    /**
+     * Persistent visitor ID.  Stored in localStorage so it survives browser
+     * sessions.  Falls back to a per-session UUID when localStorage is blocked.
+     * The server hashes this value with SHA-256 before persisting.
+     */
+    private readonly visitorId;
+    /**
+     * Per-session ID stored in sessionStorage.  Resets on tab close.
+     * The server hashes this value before persisting.
+     */
+    private readonly webSessionId;
+    private _flags;
+    private _flagTimer;
+    constructor(options: WatchupOptions);
+    private _fetchFlags;
+    private _getOrCreateVisitorId;
+    private _getOrCreateSessionId;
+    /**
+     * Attach a user to all subsequent errors, traces, and events.
+     * Call this after login; the context persists until `clearUser()` or page reload.
+     *
+     * @example
+     * watchup.setUser({ id: '42', email: 'ada@example.com', name: 'Ada Lovelace' });
+     */
+    setUser(user: WatchupUser): void;
+    /**
+     * Remove the current user context (e.g. after logout).
+     */
+    clearUser(): void;
+    /**
+     * Track a custom analytics event.
+     *
+     * @example
+     * watchup.track('button.clicked', { label: 'Sign Up', variant: 'A' });
+     */
+    track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a web analytics page view (or custom web event).
+     * Enriches the payload with visitor context, UTM params, and device info.
+     *
+     * Normally called automatically. Call manually when you need custom event_name.
+     *
+     * @example
+     * watchup.trackWebView({ event_name: 'conversion', path: '/checkout/success' });
+     */
+    trackWebView(overrides?: Partial<WebAnalyticsPayload>): void;
+    /**
+     * Manually capture an error.
+     *
+     * @example
+     * try { ... } catch (err) {
+     *   watchup.captureError(err, { component: 'CheckoutForm' });
+     * }
+     */
+    captureError(error: Error | string | unknown, context?: Record<string, unknown> & {
+        route?: string;
+        level?: ErrorPayload['level'];
+    }): void;
+    /**
+     * Time any async operation and record it as a trace.
+     * Returns an `end()` function — call it when the operation finishes.
+     *
+     * @example
+     * const end = watchup.startTrace('fetch /api/cart');
+     * const cart = await fetch('/api/cart');
+     * end({ status: cart.ok ? 'ok' : 'err' });
+     */
+    startTrace(span: string): (opts?: {
+        status?: TracePayload['status'];
+        meta?: Record<string, unknown>;
+    }) => void;
+    /**
+     * Check whether a feature flag is enabled. Evaluated locally — zero
+     * network latency. Flag rules refresh every 30 seconds in the background.
+     * Falls back to the identified user (via `setUser`) when no context is given.
+     *
+     * @example
+     * if (watchup.isEnabled('new-checkout')) {
+     *   renderNewCheckout();
+     * }
+     */
+    isEnabled(key: string, ctx?: FlagContext): boolean;
+    /**
+     * Get the variant key for a multivariate (A/B) flag.
+     * Returns `"control"` if the flag is off or the visitor isn't in the rollout.
+     *
+     * @example
+     * const variant = watchup.getVariant('pricing-layout');
+     * // → "control" | "variant-a" | "variant-b"
+     */
+    getVariant(key: string, ctx?: FlagContext): string;
+    /** Immediately flush all queued items (both telemetry and web analytics). */
+    flush(): void;
+    /** Stop the flush timer and release all listeners. */
+    shutdown(): void;
+    private _setupAutoCapture;
+    private _setupPageViewTracking;
+    private _timezone;
+}
+
+export { type ErrorPayload, type EventPayload, type FeatureFlag, type FlagContext, type FlagTargetingRule, type FlagVariant, type IngestBatch, type TracePayload, Watchup, type WatchupOptions, type WatchupUser };