@flavoai/fastfold/dist/client/observability.d.ts

Flavo frontend package

export interface ObservabilityConfig {
    enabled: boolean;
    appId?: string;
    endpoint?: string;
    trackPageviews?: boolean;
    trackErrors?: boolean;
    trackCustomEvents?: boolean;
    sessionTimeoutMinutes?: number;
    batchIntervalMs?: number;
    maxBatchSize?: number;
    maxEventsPerSession?: number;
    maxErrorsPerSession?: number;
}
export interface ObservabilityEvent {
    event_id: string;
    app_id: string;
    session_id: string;
    visitor_id: string;
    user_id?: string;
    user_email?: string;
    event_type: 'pageview' | 'session_start' | 'session_end' | 'error_frontend' | 'error_backend' | 'error_api' | 'custom';
    event_name?: string;
    timestamp: string;
    url: string;
    page_path?: string;
    referrer?: string;
    user_agent: string;
    pageview_count?: number;
    error?: {
        message: string;
        stack?: string;
        component?: string;
        endpoint?: string;
        status_code?: number;
        severity: 'error' | 'warning';
    };
    properties?: Record<string, unknown>;
}
export interface ErrorContext {
    source: 'frontend' | 'backend';
    component?: string;
    endpoint?: string;
    status_code?: number;
}
export declare class ObservabilityManager {
    private config;
    private sessionId;
    private visitorId;
    private userId;
    private userEmail;
    private pageviewCount;
    private eventBuffer;
    private errorCount;
    private eventCount;
    private flushTimer;
    private isInitialized;
    private sessionStartTime;
    private sessionEnded;
    private static readonly DEFAULT_SESSION_TIMEOUT_MINUTES;
    private static readonly DEFAULT_BATCH_INTERVAL_MS;
    private static readonly DEFAULT_MAX_BATCH_SIZE;
    private static readonly DEFAULT_MAX_EVENTS_PER_SESSION;
    private static readonly DEFAULT_MAX_ERRORS_PER_SESSION;
    private static readonly DEFAULT_ENDPOINT;
    private static readonly DEFAULT_APP_ID;
    constructor(config: ObservabilityConfig);
    /**
     * Initialize observability - setup error handlers, track session start
     */
    private initialize;
    /**
     * Get or create persistent visitor ID from localStorage
     */
    private getOrCreateVisitorId;
    /**
     * Get or create session ID with hybrid timeout logic
     */
    private getOrCreateSessionId;
    /**
     * Update last activity timestamp (called on user interactions)
     */
    private updateActivity;
    /**
     * Setup global error handlers
     */
    private setupErrorHandlers;
    /**
     * Setup visibility change tracking for session end
     */
    private setupVisibilityTracking;
    /**
     * Setup SPA navigation tracking via History API
     */
    private setupNavigationTracking;
    /**
     * Setup unload handler to flush remaining events
     */
    private setupUnloadHandler;
    /**
     * Start the periodic flush timer
     */
    private startFlushTimer;
    /**
     * Send an event to the buffer
     */
    private send;
    /**
     * Flush buffered events to the collector
     */
    private flush;
    /**
     * Get the current session ID (for API request headers)
     */
    get currentSessionId(): string;
    /**
     * Get the current visitor ID (for API request headers)
     */
    get currentVisitorId(): string;
    /**
     * Set the authenticated user ID and optional email
     */
    setUser(userId: string | null, email?: string): void;
    /**
     * Track a pageview event
     */
    trackPageview(url?: string): void;
    /**
     * Track an error event
     */
    trackError(error: Error, context: ErrorContext): void;
    /**
     * Track a custom event
     */
    track(eventName: string, properties?: Record<string, unknown>): void;
    /**
     * Manually flush events (useful before navigation)
     */
    forceFlush(): void;
    /**
     * Destroy the manager and cleanup
     */
    destroy(): void;
}
/**
 * Initialize observability (called by FastfoldProvider)
 */
export declare function initializeObservability(config: ObservabilityConfig): ObservabilityManager;
/**
 * Get the current observability instance
 */
export declare function getObservabilityInstance(): ObservabilityManager | null;
/**
 * Public observability API for use in apps
 */
export declare const observability: {
    /**
     * Track a custom event
     * @example observability.track('signup', { plan: 'pro' })
     */
    track: (eventName: string, properties?: Record<string, unknown>) => void;
    /**
     * Manually track a pageview (for edge cases)
     * @example observability.trackPageview('/custom-page')
     */
    trackPageview: (url?: string) => void;
    /**
     * Set the authenticated user ID and optional email
     * @example observability.setUser(user.id, user.email)
     */
    setUser: (userId: string | null, email?: string) => void;
    /**
     * Track an error (usually called automatically)
     */
    trackError: (error: Error, context: ErrorContext) => void;
    /**
     * Force flush any buffered events
     */
    flush: () => void;
    /**
     * Get the current session ID (for API headers)
     */
    readonly sessionId: string | undefined;
    /**
     * Get the current visitor ID (for API headers)
     */
    readonly visitorId: string | undefined;
};
//# sourceMappingURL=observability.d.ts.map