@scoperat/tracker 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,201 @@
-import scoperat from "./client.js";
-export default scoperat;
-export type { EventSource, FlushResult, IdentifyTraits, InitOptions, TrackEvent, } from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+type EventSource = "browser" | "server" | "worker";
+interface TrackEvent {
+    event: string;
+    properties?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    source?: EventSource;
+    occurred_at?: Date | string;
+    org_id?: string;
+    user_id?: string;
+    anonymous_id?: string;
+    session_id?: string;
+}
+interface IdentifyTraits {
+    orgId?: string;
+    orgName?: string;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface IdentifyOptions {
+    /**
+     * HMAC-SHA256(identityVerificationSecret, userId) in lowercase
+     * hex, computed by the host site's backend. Required for the
+     * support-ticket widget to authenticate the end-user — without
+     * it, ticket reads/writes fall back to the anonymous session
+     * channel (bootstrapped via `POST /ticket/session`).
+     *
+     * Retrieve the per-project `identityVerificationSecret` from the
+     * ScopeRat dashboard (Analytics → Project → Install). Never ship
+     * the secret to the browser — compute the hash server-side.
+     */
+    userHash?: string;
+}
+interface InitOptions {
+    endpoint?: string;
+    flushAt?: number;
+    flushInterval?: number;
+    timeout?: number;
+    onError?: (error: Error, events: TrackEvent[]) => void;
+    /** Session inactivity timeout in ms. Defaults to 30 minutes. */
+    sessionTimeout?: number;
+    /** Automatically capture uncaught errors and unhandled rejections. Defaults to false. */
+    captureErrors?: boolean;
+    /** Environment name for feature flag evaluation (e.g. "production", "development"). */
+    environment?: string;
+    /** Polling interval for feature flag updates in ms. Defaults to 60 seconds. */
+    flagPollInterval?: number;
+}
+interface FlushResult {
+    success: boolean;
+    ingested: number;
+}
+interface EvaluatedFlag {
+    key: string;
+    value: unknown;
+    type: "boolean" | "string" | "number" | "json";
+    source: "default" | "override" | "targeted" | "rollout";
+}
+
+interface FlagClientConfig {
+    endpoint: string;
+    writeKey: string;
+    timeout?: number;
+    environment?: string;
+    pollInterval?: number;
+    getIdentity: () => {
+        userId?: string;
+        anonymousId?: string;
+        orgId?: string;
+    };
+    /** Called when a flag is first evaluated (for impression tracking). */
+    onEvaluation?: (key: string, flag: EvaluatedFlag) => void;
+}
+declare class FlagClient {
+    private endpoint;
+    private writeKey;
+    private timeout;
+    private environment;
+    private getIdentity;
+    private onEvaluation;
+    private cache;
+    private ready;
+    private readyCallbacks;
+    private changeListeners;
+    private evalTracked;
+    private timer;
+    constructor(config: FlagClientConfig);
+    getFlag<T = unknown>(key: string, defaultValue: T): T;
+    onFlagsReady(callback: () => void): void;
+    onFlagChange(listener: () => void): () => void;
+    refresh(): Promise<void>;
+    destroy(): void;
+    private fetch;
+}
+
+/** Why a session ended / began, attached as the event's `reason` property. */
+type SessionReason = "initial" | "login" | "logout" | "timeout";
+interface StoredTicketSession {
+    anonymousId: string;
+    token: string;
+    expiresAt: number;
+}
+declare class TrackerImpl {
+    private writeKey;
+    private endpoint;
+    private flushAt;
+    private flushInterval;
+    private timeout;
+    private onError?;
+    private buffer;
+    private timer;
+    private visibilityHandler;
+    private userId;
+    private orgId;
+    private traits;
+    private userHash;
+    private anonymousId;
+    private sessionId;
+    private sessionTimeout;
+    private ticketSessionFetch;
+    private _flagClient;
+    init(writeKey: string, options?: InitOptions): void;
+    /** The underlying flag evaluation client. Use for direct SDK integration. */
+    get flags(): FlagClient;
+    identify(userId: string, traits?: IdentifyTraits, options?: IdentifyOptions): void;
+    reset(): void;
+    /**
+     * Begin a new analytics session, ending the current one first if it
+     * exists. Emits `$session_end` (for the old session) and
+     * `$session_start` (for the new). Called automatically on login via
+     * {@link identify}; also exposed for explicit control.
+     */
+    startSession(reason?: SessionReason): string | undefined;
+    /**
+     * End the current analytics session (if any), emitting `$session_end`,
+     * and clear the stored session. The next tracked event will lazily
+     * start a fresh session. Called automatically on logout via
+     * {@link reset}; also exposed for explicit control.
+     *
+     * @param immediate - flush buffered events synchronously (via
+     *   `sendBeacon`) so the end event isn't lost if the page unloads.
+     */
+    endSession(reason?: SessionReason, immediate?: boolean): void;
+    private readStoredUserId;
+    private writeStoredUserId;
+    private clearStoredUserId;
+    private clearTicketSession;
+    private readStoredTicketSession;
+    /**
+     * @internal Used by the widget API helpers. Returns a cached or
+     * newly-minted anonymous session token, or `null` if the server
+     * has anonymous sessions disabled. Coalesces concurrent callers
+     * onto a single in-flight network request so mount-time parallel
+     * API calls don't each trigger a `POST /ticket/session`.
+     */
+    _ensureTicketSession(): Promise<StoredTicketSession | null>;
+    /**
+     * Return the id of the current session, rotating it when the previous
+     * session has expired through inactivity. On rotation it emits a
+     * `$session_end` for the timed-out session (backdated to the last
+     * recorded activity) and a `$session_start` for the new one. Called on
+     * every tracked event so sessions advance with real user activity.
+     */
+    private ensureSession;
+    private readStoredSession;
+    private readLastActivity;
+    private persistSession;
+    /**
+     * Enqueue a session lifecycle event already stamped with its session id
+     * (so it never re-enters {@link ensureSession} and risks recursion).
+     */
+    private emitSessionEvent;
+    private clearSession;
+    getSessionId(): string | undefined;
+    /** @internal Used by the widget to read tracker config. */
+    _getEndpoint(): string;
+    /** @internal Used by the widget to read the write key. */
+    _getWriteKey(): string | null;
+    /** @internal Used by the widget to read the current user identity. */
+    _getIdentity(): {
+        userId?: string;
+        anonymousId?: string;
+        email?: string;
+        name?: string;
+        userHash?: string;
+    };
+    captureException(error: Error, context?: Record<string, unknown>): void;
+    addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;
+    track(event: string, properties?: Record<string, unknown>): void;
+    track(event: TrackEvent): void;
+    flush(): Promise<FlushResult>;
+    private flushSync;
+    getFlag<T = unknown>(key: string, defaultValue: T): T;
+    onFlagsReady(callback: () => void): void;
+    onFlagChange(listener: () => void): () => void;
+    refreshFlags(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare const scoperat: TrackerImpl;
+
+export { type EvaluatedFlag, type EventSource, FlagClient, type FlushResult, type IdentifyOptions, type IdentifyTraits, type InitOptions, type TrackEvent, scoperat as default };