@goatech/sdk-js 0.1.0 → 1.0.0

package/dist/types-CxAq_Cds.d.ts

@@ -1,371 +0,0 @@
-type DiagnosticSeverity = "debug" | "info" | "warn" | "error";
-type DiagnosticCategory = "transport" | "config" | "identity" | "lifecycle" | "flag" | "experiment" | "connectivity";
-interface DiagnosticEvent {
-    timestamp: string;
-    severity: DiagnosticSeverity;
-    category: DiagnosticCategory;
-    /** Machine-readable code, e.g. "transport.flush_failed" */
-    code: string;
-    /** Human-readable description */
-    message: string;
-    /** Structured payload */
-    data?: Record<string, unknown>;
-    /** Correlates with API-side X-Request-ID */
-    requestId?: string;
-}
-type DiagnosticListener = (event: DiagnosticEvent) => void;
-
-interface SubscribeOptions {
-    /** Only receive events at or above this severity. Default: "debug" (all). */
-    minSeverity?: DiagnosticSeverity;
-    /** Only receive events in these categories. Default: all. */
-    categories?: DiagnosticCategory[];
-}
-declare class DiagnosticBus {
-    private readonly listeners;
-    private readonly buffer;
-    private readonly maxSize;
-    private writeIndex;
-    private count;
-    private counts;
-    constructor(bufferSize?: number);
-    emit(event: DiagnosticEvent): void;
-    subscribe(fn: DiagnosticListener, options?: SubscribeOptions): () => void;
-    getRecentDiagnostics(): DiagnosticEvent[];
-    getCounts(): Record<DiagnosticSeverity, number>;
-}
-
-declare class Logger {
-    private readonly debugEnabled;
-    private readonly prefix;
-    private readonly bus;
-    constructor(debug: boolean, bus?: DiagnosticBus);
-    debug(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-    /**
-     * Emit a diagnostic event with explicit category and code.
-     * Use this instead of debug/warn/error when you want fine-grained control.
-     */
-    diagnostic(severity: DiagnosticSeverity, category: DiagnosticCategory, code: string, message: string, data?: Record<string, unknown>, requestId?: string): void;
-    private emitDiagnostic;
-}
-
-type Tracker$1 = (eventName: string, properties?: Record<string, unknown>) => void;
-interface ErrorCaptureConfig {
-    /** Capture uncaught errors via `window.onerror`. Default: true. */
-    errors?: boolean;
-    /** Capture unhandled promise rejections. Default: true. */
-    rejections?: boolean;
-    /** Forward `goatech:auth-event` CustomEvents verbatim as tracked events. Default: true. */
-    authEvents?: boolean;
-    /** Max stack frames length in characters. Default: 4096. */
-    stackLimit?: number;
-    /** De-dup window in ms — identical errors within this window are dropped. Default: 1000. */
-    dedupeWindowMs?: number;
-}
-declare class BrowserErrorCapture {
-    private readonly track;
-    private readonly log;
-    private readonly cfg;
-    private readonly handlers;
-    private lastSignature;
-    private lastSignatureAt;
-    constructor(track: Tracker$1, log: Logger, config?: ErrorCaptureConfig);
-    install(): void;
-    uninstall(): void;
-    private suppress;
-    private safeTrack;
-}
-
-/**
- * HTTP error auto-capture — wraps `window.fetch` and emits a structured
- * `$http_error` event for every 4xx/5xx response or network failure.
- *
- * Why: without this, customers have to hand-instrument every endpoint that
- * might return an error (the 04-22 sign-out debug session is the canonical
- * example — we spent hours theorizing about cookie behavior instead of
- * reading `cookie_keys=[]` off a structured event). With it, every failing
- * request becomes a queryable event on the GoaTech dashboard with enough
- * context to diagnose auth, CORS, CDN, and proxy bugs without touching
- * customer code.
- *
- * Design:
- * - Monkey-patches `window.fetch` with an idempotent install — a second
- *   install() call is a no-op.
- * - Captures CORS-exposed response headers only (Set-Cookie is hidden from
- *   JavaScript per spec, so we capture cookie *names* via `document.cookie`
- *   as a proxy for "did the server's Set-Cookie land").
- * - Dedupe window prevents error loops (identical (url, status) within
- *   `dedupeWindowMs` is dropped).
- * - NEVER captures request or response bodies — those may carry secrets.
- *   If a customer needs bodies they can extend via the `onCapture` hook.
- */
-
-type Tracker = (eventName: string, properties?: Record<string, unknown>) => void;
-interface HttpErrorCaptureConfig {
-    /** Master switch. Default: true. */
-    enabled?: boolean;
-    /**
-     * Status predicate — return true to capture. Default: `s >= 400`.
-     * Network failures (fetch rejections) are ALWAYS captured regardless.
-     */
-    shouldCapture?: (status: number) => boolean;
-    /**
-     * URL patterns to exclude (tested with `.test(url)`). Useful to skip
-     * analytics/monitoring endpoints that would otherwise recurse.
-     * Default: excludes `/v1/ingest` and `/v1/config` on the SDK's own API URL.
-     */
-    excludeUrlPatterns?: RegExp[];
-    /**
-     * CORS-exposed response headers to capture (lowercased). Default:
-     * ["x-request-id", "vary", "content-type", "access-control-allow-origin"].
-     */
-    captureResponseHeaders?: string[];
-    /** Dedupe window in ms — identical (url, status) inside is dropped. Default: 1000. */
-    dedupeWindowMs?: number;
-    /** Called AFTER the event is tracked — hook for custom enrichment or sinks. */
-    onCapture?: (detail: HttpErrorEventDetail) => void;
-}
-interface HttpErrorEventDetail {
-    url: string;
-    method: string;
-    status: number;
-    latency_ms: number;
-    request_id: string | null;
-    response_headers: Record<string, string>;
-    /**
-     * Non-HttpOnly cookie NAMES present on document.cookie at the time of
-     * the error. Values are never captured. This is the client-side proxy
-     * for "did the server's Set-Cookie get accepted" — if an auth endpoint
-     * 401s and there are zero cookies on the origin that *should* have set
-     * one, the cookie was rejected by the browser.
-     */
-    cookie_names: string[];
-    /** "network_failure" | "http_error". */
-    kind: "network_failure" | "http_error";
-    /** Present on kind=network_failure. */
-    error_name?: string;
-    /** Present on kind=network_failure. */
-    error_message?: string;
-    /** True if the fetch was aborted (e.g., timeout). */
-    aborted?: boolean;
-}
-declare class HttpErrorCapture {
-    private readonly track;
-    private readonly log;
-    private readonly cfg;
-    private originalFetch;
-    private installed;
-    private lastSig;
-    private lastSigAt;
-    constructor(track: Tracker, log: Logger, config?: HttpErrorCaptureConfig);
-    install(): void;
-    uninstall(): void;
-    private shouldSkip;
-    private emit;
-    private pluckHeaders;
-    private readCookieNames;
-}
-
-interface ClickFrustrationConfig {
-    /** Detect rage clicks. Default: true. */
-    rage?: boolean;
-    /** Detect dead clicks. Default: true. */
-    dead?: boolean;
-    /** Number of clicks within window+radius that constitute rage. Default: 3. */
-    rageThreshold?: number;
-    /** Time window for rage clustering. Default: 1000ms. */
-    rageWindowMs?: number;
-    /** Pixel radius for rage clustering. Default: 50. */
-    rageRadiusPx?: number;
-    /** Cap the emission rate (combined rage+dead). Default: 5/sec. */
-    maxEmitsPerSec?: number;
-}
-
-interface GoaTechConfig {
-    apiKey: string;
-    environment?: string;
-    apiUrl?: string;
-    flushInterval?: number;
-    flushSize?: number;
-    debug?: boolean;
-    configRefreshInterval?: number;
-    maxQueueSize?: number;
-    retryAttempts?: number;
-    /** Called for every tracked event. Useful for logging, debugging, or
-     *  forwarding events to systems outside the React tree. */
-    onEvent?: (eventName: string, properties?: Record<string, unknown>) => void;
-    /** Subscribe to SDK diagnostic events for monitoring integration. */
-    onDiagnostic?: DiagnosticListener;
-    /** Maximum diagnostic events to retain in memory ring buffer. Default: 100. */
-    diagnosticBufferSize?: number;
-    /**
-     * Automatic error capture in the browser. Registers listeners for
-     * `window.onerror` and `unhandledrejection` and forwards them as `$error`
-     * events. Pass `false` to disable completely, or a partial config to tune
-     * individual channels. Default: enabled with defaults.
-     */
-    autoCaptureErrors?: boolean | ErrorCaptureConfig;
-    /**
-     * Automatic HTTP error capture. Wraps `window.fetch` and emits a
-     * `$http_error` event for every 4xx/5xx response and network failure —
-     * making auth, CORS, CDN, and proxy bugs visible on the dashboard without
-     * customers touching their code. Pass `false` to disable, or a partial
-     * config to tune status predicate, URL exclusions, captured response
-     * headers, and dedupe window. Default: OFF — opt in with `true` or a
-     * partial config after verifying in your specific browser matrix. Monkey-
-     * patching window.fetch has sharp edges (native contract, other libs that
-     * also patch it); leaving this opt-in avoids surprise regressions.
-     */
-    autoCaptureHttpErrors?: boolean | HttpErrorCaptureConfig;
-    /**
-     * Automatic click-frustration capture. Listens for global clicks and
-     * emits `$rage_click` (≥3 clicks within 1s in a 50px radius) and
-     * `$dead_click` (click on a non-interactive target) so the dashboard
-     * can surface UX dead-ends. Pass `false` to disable, or a partial
-     * config to tune thresholds. Default: ON.
-     */
-    autoCaptureClickFrustration?: boolean | ClickFrustrationConfig;
-    /**
-     * Application version string (e.g. build SHA or semver). When set, sent on
-     * every event as `app_version` so the backend can attribute events to a
-     * Release. Without this, release-health metrics can't correlate events to
-     * specific builds.
-     */
-    appVersion?: string;
-}
-type FlagValue = boolean | string | number | Record<string, unknown>;
-interface ExperimentResult {
-    variant: string;
-    payload?: Record<string, unknown>;
-}
-interface SDKStatus {
-    initialized: boolean;
-    online: boolean;
-    queueDepth: number;
-    offlineQueueDepth: number;
-    lastFlushAt: Date | null;
-    deviceId: string | null;
-    userId: string | null;
-    flagCount: number;
-    experimentCount: number;
-    sdkVersion: string;
-}
-interface DeviceInfo {
-    platform: string;
-    userAgent: string;
-    language: string;
-    screenWidth: number;
-    screenHeight: number;
-    timezone: string;
-}
-interface EnrichedEvent {
-    event_id: string;
-    event_name: string;
-    event_properties?: Record<string, unknown>;
-    device_id: string;
-    anonymous_id: string;
-    session_id: string;
-    user_id: string | null;
-    platform: string;
-    app_version?: string;
-    sdk_version: string;
-    locale: string;
-    timezone: string;
-    timestamp: string;
-}
-interface FlagConfig {
-    key: string;
-    enabled: boolean;
-    default_value: FlagValue;
-    flag_type: string;
-    rules: FlagRule[];
-}
-interface FlagRule {
-    conditions: Condition[];
-    value: FlagValue;
-    percentage: number;
-    enabled: boolean;
-}
-type ConditionOp = "eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "exists";
-interface Condition {
-    field: string;
-    op: ConditionOp;
-    values: unknown[];
-}
-type ExperimentStatus = "draft" | "running" | "paused" | "completed";
-/** Pre-bucketed assignment returned by `/v1/config`. */
-interface ExperimentAssignment {
-    variant_key: string;
-    payload?: Record<string, unknown>;
-}
-/**
- * Full experiment config — only used internally for admin flows and
- * tests. Regular SDK consumers receive `ExperimentAssignment`.
- */
-interface ExperimentConfig {
-    key: string;
-    name: string;
-    status: ExperimentStatus;
-    traffic_pct: number;
-    variants: ExperimentVariant[];
-}
-interface ExperimentVariant {
-    key: string;
-    name: string;
-    weight: number;
-    is_control: boolean;
-    payload?: Record<string, unknown>;
-}
-interface SDKConfig {
-    /** Server-evaluated flag values keyed by flag_key. */
-    flags: Record<string, unknown>;
-    /** Pre-bucketed experiment assignments keyed by experiment_key. */
-    experiments: Record<string, ExperimentAssignment>;
-    server_time?: string;
-}
-/**
- * First-touch attribution payload attached to every event fired during a
- * given session. Captured from the session's first pageview (UTM params
- * on the URL + document.referrer + landing pathname). All fields are
- * optional because most organic visits have none of them set.
- */
-interface AttributionContext {
-    utm_source?: string;
-    utm_medium?: string;
-    utm_campaign?: string;
-    utm_content?: string;
-    utm_term?: string;
-    /** Ad-click IDs the ad platforms round-trip on their click URLs. */
-    gclid?: string;
-    fbclid?: string;
-    /** `document.referrer` minus query + trailing slash. May be the empty
-     *  string when direct-traffic / privacy mode hides it. */
-    referrer?: string;
-    /** Hostname of the referrer, for easy grouping without full-URL parsing
-     *  server-side. */
-    referrer_host?: string;
-    /** Pathname + search that the user first hit this session. */
-    landing_page?: string;
-}
-interface EventContext {
-    device_id: string;
-    anonymous_id: string;
-    session_id: string;
-    user_id: string | null;
-    platform: string;
-    locale: string;
-    timezone: string;
-    sdk_version: string;
-    /** First-touch attribution captured at session start. Same snapshot is
-     *  attached to every event in the session so segmenting "events from
-     *  users who came via utm_source=twitter" works without a join. */
-    attribution?: AttributionContext;
-    /** Ever-first-touch attribution across the whole device lifetime.
-     *  Written once; lets you distinguish "first-session" from "returning"
-     *  traffic even after the original UTM params are long gone. */
-    first_touch?: AttributionContext;
-}
-
-export { BrowserErrorCapture as B, type Condition as C, DiagnosticBus as D, type ExperimentResult as E, type FlagValue as F, type GoaTechConfig as G, HttpErrorCapture as H, type SDKStatus as S, type DiagnosticEvent as a, type ConditionOp as b, type DeviceInfo as c, type DiagnosticCategory as d, type DiagnosticListener as e, type DiagnosticSeverity as f, type EnrichedEvent as g, type ErrorCaptureConfig as h, type EventContext as i, type ExperimentConfig as j, type ExperimentStatus as k, type ExperimentVariant as l, type FlagConfig as m, type FlagRule as n, type HttpErrorCaptureConfig as o, type HttpErrorEventDetail as p, type SDKConfig as q, type SubscribeOptions as r, type ExperimentAssignment as s };