sitepong 0.0.1 → 0.0.5

package/dist/index.d.mts

@@ -1,3 +1,381 @@
+interface CoreSignals {
+    userAgent: string;
+    language: string;
+    languages: string[];
+    platform: string;
+    screenWidth: number;
+    screenHeight: number;
+    screenColorDepth: number;
+    devicePixelRatio: number;
+    timezoneOffset: number;
+    timezone: string;
+    sessionStorage: boolean;
+    localStorage: boolean;
+    indexedDB: boolean;
+    cookieEnabled: boolean;
+    hardwareConcurrency: number;
+    maxTouchPoints: number;
+    deviceMemory?: number;
+}
+interface ExtendedSignals {
+    canvasFingerprint?: string;
+    webglVendor?: string;
+    webglRenderer?: string;
+    audioFingerprint?: string;
+}
+interface SmartSignals {
+    incognito?: boolean;
+    bot?: boolean;
+    /** Browser timezone differs from what's expected for this IP location (computed server-side) */
+    timezoneMismatch?: boolean;
+    /** Browser language doesn't match expected language for IP location (computed server-side) */
+    languageMismatch?: boolean;
+    /** First time this device was seen (from localStorage) */
+    deviceFirstSeen?: string;
+    /** Number of times this device has been seen (incremented per session) */
+    deviceVisitCount?: number;
+    /** Whether the device appears to be using a privacy-focused browser */
+    privacyBrowser?: boolean;
+    /** Whether developer tools appear to be open */
+    devToolsOpen?: boolean;
+    /** Connection type (if available) */
+    connectionType?: string;
+    /** Whether the browser supports notifications */
+    notificationsEnabled?: boolean;
+    /** Whether do-not-track is enabled */
+    doNotTrack?: boolean;
+    /** Browser UA/fingerprint appears spoofed */
+    browserTampered?: boolean;
+    /** Canvas fingerprint noise/blocking detected */
+    canvasTampered?: boolean;
+    /** WebGL fingerprint spoofing detected */
+    webglTampered?: boolean;
+    /** Virtual machine environment detected */
+    vmDetected?: boolean;
+    /** VM indicator details */
+    vmIndicators?: string[];
+}
+interface BehaviorScore {
+    score: number;
+    mouseMovements: number;
+    keystrokes: number;
+    scrolls: number;
+    clicks: number;
+    isHuman: boolean;
+}
+interface DeviceSignals extends CoreSignals {
+    extended?: ExtendedSignals;
+    smart?: SmartSignals;
+    behavior?: BehaviorScore;
+    /** @deprecated Use smart.incognito */
+    incognito?: boolean;
+    /** @deprecated Use smart.bot */
+    bot?: boolean;
+}
+interface VisitorIdResult {
+    visitorId: string;
+    confidence: number;
+    firstSeenAt?: string;
+    lastSeenAt?: string;
+}
+interface FraudCheckResult {
+    visitorId: string;
+    riskScore: number;
+    signals: DeviceSignals;
+    flags?: {
+        incognito?: boolean;
+        bot?: boolean;
+        vpn?: boolean;
+        tampered?: boolean;
+    };
+}
+
+interface RecaptchaV3 {
+    ready: (cb: () => void) => void;
+    execute: (siteKey: string, options: {
+        action: string;
+    }) => Promise<string>;
+}
+interface HCaptcha {
+    execute: (siteKey: string, options?: {
+        async: boolean;
+    }) => Promise<{
+        response: string;
+    }>;
+    render: (container: string | HTMLElement, options: object) => string;
+}
+declare global {
+    interface Window {
+        grecaptcha?: RecaptchaV3;
+        hcaptcha?: HCaptcha;
+    }
+}
+
+interface TrackProperties {
+    [key: string]: unknown;
+}
+interface UserTraits {
+    email?: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    avatar?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface GroupTraits {
+    name?: string;
+    industry?: string;
+    employees?: number;
+    plan?: string;
+    [key: string]: unknown;
+}
+
+interface PerformanceConfig {
+    apiKey: string;
+    endpoint?: string;
+    enabled?: boolean;
+    /** Collect Web Vitals (default: true) */
+    webVitals?: boolean;
+    /** Report navigation timing (default: true) */
+    navigationTiming?: boolean;
+    /** Report resource timing (default: false) */
+    resourceTiming?: boolean;
+    /** Custom endpoint for performance data */
+    performanceEndpoint?: string;
+    /** Flush interval in ms (default: 10000) */
+    flushInterval?: number;
+    /** Sample rate 0-1 (default: 1.0) */
+    sampleRate?: number;
+    debug?: boolean;
+}
+interface WebVitals {
+    lcp?: number;
+    fid?: number;
+    cls?: number;
+    fcp?: number;
+    ttfb?: number;
+    inp?: number;
+}
+interface PerformanceSpan {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    status: 'ok' | 'error' | 'running';
+    data?: Record<string, unknown>;
+}
+interface PerformanceTransaction {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    status: 'ok' | 'error' | 'running';
+    spans: PerformanceSpan[];
+    data?: Record<string, unknown>;
+}
+
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    sampled: boolean;
+}
+declare function generateTraceId(): string;
+declare function generateSpanId(): string;
+declare function createTraceContext(): TraceContext;
+declare function propagateTrace(context: TraceContext): Record<string, string>;
+declare function extractTrace(headers: Record<string, string>): TraceContext | null;
+declare class TracePropagator {
+    private targets;
+    private originalFetch;
+    constructor(targets: string[]);
+    shouldPropagate(url: string): boolean;
+    injectHeaders(url: string, headers: Record<string, string>, context: TraceContext): Record<string, string>;
+    start(): void;
+    stop(): void;
+}
+
+/**
+ * Cron Job Monitoring SDK Module
+ *
+ * Usage:
+ *   import { cronMonitor } from '@sitepong/sdk';
+ *
+ *   // Simple check-in
+ *   await cronMonitor.checkin('my-job-slug');
+ *
+ *   // With duration tracking
+ *   const done = cronMonitor.start('my-job-slug');
+ *   try { await doWork(); done.ok(); }
+ *   catch (e) { done.error(e.message); }
+ */
+interface CronCheckinOptions {
+    status?: 'ok' | 'error' | 'in_progress';
+    duration_ms?: number;
+    message?: string;
+    environment?: string;
+}
+interface CronHandle {
+    ok: (message?: string) => Promise<void>;
+    error: (message?: string) => Promise<void>;
+}
+
+/**
+ * Custom Metrics SDK Module
+ *
+ * Usage:
+ *   import { metrics } from '@sitepong/sdk';
+ *
+ *   // Counter
+ *   metrics.increment('api.requests', 1, { endpoint: '/users' });
+ *
+ *   // Gauge
+ *   metrics.gauge('memory.usage', process.memoryUsage().heapUsed, { unit: 'bytes' });
+ *
+ *   // Distribution (for percentile calculations)
+ *   metrics.distribution('api.latency', responseTime, { unit: 'ms' });
+ *
+ *   // Histogram
+ *   metrics.histogram('request.size', bodySize, { unit: 'bytes' });
+ */
+interface MetricOptions {
+    tags?: Record<string, string>;
+    unit?: string;
+    timestamp?: string;
+}
+
+/**
+ * Production Profiling SDK Module
+ *
+ * Usage:
+ *   import { profiler } from '@sitepong/sdk';
+ *
+ *   // Profile a function
+ *   const result = await profiler.profile('processOrder', async () => {
+ *     return await processOrder(orderId);
+ *   });
+ *
+ *   // Get flame graph data
+ *   const profile = profiler.getProfile();
+ */
+interface ProfileFrame {
+    name: string;
+    duration_ms: number;
+    start_ms: number;
+    children: ProfileFrame[];
+    metadata?: Record<string, unknown>;
+}
+interface ProfileData {
+    id: string;
+    name: string;
+    startTime: number;
+    duration_ms: number;
+    frames: ProfileFrame[];
+    metadata?: Record<string, unknown>;
+}
+interface ProfilerConfig {
+    apiKey: string;
+    endpoint: string;
+    debug?: boolean;
+    /** Sample rate for profiling (0-1, default 0.1 = 10%) */
+    sampleRate?: number;
+    /** Maximum profile duration in ms (default 30000) */
+    maxDuration?: number;
+    /** Flush interval for sending profiles (default 30000) */
+    flushInterval?: number;
+}
+
+/**
+ * Anonymous ID Management
+ * Generates and persists a unique ID for consistent flag evaluation
+ */
+declare function getAnonymousId(): string;
+/**
+ * Clear the anonymous ID
+ * Useful for testing or when user wants to reset their identity
+ */
+declare function clearAnonymousId(): void;
+/**
+ * Set a custom anonymous ID
+ * Useful when you want to use your own user identifier
+ */
+declare function setAnonymousId(id: string): void;
+
+interface ReplayConfig {
+    apiKey: string;
+    endpoint?: string;
+    enabled?: boolean;
+    /** Mask all text input values (default: true) */
+    maskInputs?: boolean;
+    /** CSS selector for elements to block from recording */
+    blockSelector?: string;
+    /** CSS selector for elements to mask content */
+    maskSelector?: string;
+    /** Maximum session duration in ms (default: 60 minutes) */
+    maxSessionDuration?: number;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Maximum events per batch (default: 100) */
+    maxBatchSize?: number;
+    /** Sample rate 0-1 (default: 1.0 = record all sessions) */
+    sampleRate?: number;
+    /** Custom endpoint for replay data */
+    replayEndpoint?: string;
+    /** Record network requests (XHR/fetch) */
+    recordNetwork?: boolean;
+    /** Capture request/response headers in network recording */
+    captureNetworkHeaders?: boolean;
+    /** Record console logs */
+    recordConsole?: boolean;
+    /** Console levels to record (default: all) */
+    consoleLevels?: Array<'log' | 'info' | 'warn' | 'error' | 'debug'>;
+    debug?: boolean;
+}
+type ReplayEventType = 'snapshot' | 'mutation' | 'mouse_move' | 'mouse_click' | 'mouse_leave' | 'touch' | 'scroll' | 'input' | 'resize' | 'focus' | 'blur' | 'network' | 'console' | 'custom';
+interface ReplayEvent {
+    type: ReplayEventType;
+    timestamp: number;
+    data: unknown;
+}
+
+/**
+ * Database Query Tracking SDK Module
+ *
+ * Usage (Node.js):
+ *   import { dbTracker } from '@sitepong/sdk';
+ *
+ *   // Wrap a database query
+ *   const result = await dbTracker.track('SELECT * FROM users WHERE id = ?', async () => {
+ *     return await db.query('SELECT * FROM users WHERE id = ?', [userId]);
+ *   });
+ *
+ *   // Integration with ORMs
+ *   dbTracker.patchKnex(knex); // Auto-tracks all Knex queries
+ */
+interface DatabaseQueryEvent {
+    query: string;
+    duration_ms: number;
+    timestamp: string;
+    source?: string;
+    rows_affected?: number;
+    error?: string;
+    is_slow?: boolean;
+}
+interface DatabaseTrackerConfig {
+    apiKey: string;
+    endpoint: string;
+    debug?: boolean;
+    slowQueryThreshold?: number;
+    maxBatchSize?: number;
+    flushInterval?: number;
+    /** Redact query parameters for security */
+    redactParams?: boolean;
+}
+
 interface SitePongConfig {
     apiKey: string;
     endpoint?: string;
@@ -28,6 +406,91 @@ interface CapturedError {
     release?: string;
     context?: ErrorContext;
     fingerprint?: string;
+    /** Replay session ID if session recording is active */
+    replaySessionId?: string;
+}
+
+interface SitePongInitConfig extends SitePongConfig {
+    /** Enable feature flags (default: false) */
+    enableFlags?: boolean;
+    /** Custom endpoint for flags API (default: uses main endpoint) */
+    flagsEndpoint?: string;
+    /** Analytics configuration */
+    analytics?: {
+        enabled?: boolean;
+        autocapturePageviews?: boolean;
+        autocaptureClicks?: boolean;
+        autocaptureForms?: boolean;
+        /** Full autocapture configuration (overrides individual autocapture flags) */
+        autocapture?: {
+            clicks?: boolean;
+            forms?: boolean;
+            pageviews?: boolean;
+            blockSelectors?: string[];
+            allowSelectors?: string[];
+        } | boolean;
+        maxBatchSize?: number;
+        flushInterval?: number;
+        eventsEndpoint?: string;
+    };
+    /** Fingerprint / device intelligence configuration */
+    fingerprint?: {
+        enabled?: boolean;
+        extendedSignals?: boolean;
+        visitorEndpoint?: string;
+    };
+    /** Performance monitoring configuration */
+    performance?: {
+        enabled?: boolean;
+        webVitals?: boolean;
+        navigationTiming?: boolean;
+        resourceTiming?: boolean;
+        sampleRate?: number;
+        flushInterval?: number;
+        performanceEndpoint?: string;
+    };
+    /** Session replay configuration */
+    replay?: {
+        enabled?: boolean;
+        maskInputs?: boolean;
+        blockSelector?: string;
+        maskSelector?: string;
+        sampleRate?: number;
+        maxSessionDuration?: number;
+        flushInterval?: number;
+        replayEndpoint?: string;
+        /** Record network requests (XHR/fetch) in the replay timeline */
+        recordNetwork?: boolean;
+        /** Include request/response headers in network recording */
+        captureNetworkHeaders?: boolean;
+        /** Record console logs in the replay timeline */
+        recordConsole?: boolean;
+        /** Which console levels to record (default: all) */
+        consoleLevels?: Array<'log' | 'info' | 'warn' | 'error' | 'debug'>;
+    };
+    /** Cron monitoring configuration */
+    crons?: {
+        enabled?: boolean;
+    };
+    /** Custom metrics configuration */
+    metrics?: {
+        enabled?: boolean;
+        flushInterval?: number;
+        maxBatchSize?: number;
+    };
+    /** Database query tracking configuration */
+    database?: {
+        enabled?: boolean;
+        slowQueryThreshold?: number;
+        redactParams?: boolean;
+    };
+    /** Production profiling configuration */
+    profiling?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        maxDuration?: number;
+        flushInterval?: number;
+    };
 }
 declare class SitePongClient {
     private config;
@@ -35,8 +498,89 @@ declare class SitePongClient {
     private flushTimer;
     private context;
     private initialized;
+    private flagManager;
+    private analyticsManager;
+    private fingerprintManager;
+    private replayManager;
+    private performanceManager;
+    private cronManager;
+    private metricsManager;
+    private databaseTracker;
+    private profiler;
     constructor();
-    init(config: SitePongConfig): void;
+    init(config: SitePongInitConfig): void;
+    /**
+     * Get a feature flag value
+     * Returns the cached evaluated result or default value
+     */
+    getFlag(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Get all feature flag values
+     */
+    getAllFlags(): Record<string, boolean>;
+    /**
+     * Wait for flags to be initialized
+     */
+    waitForFlags(): Promise<void>;
+    /**
+     * Check if flags are ready
+     */
+    areFlagsReady(): boolean;
+    /**
+     * Get a multivariate flag variant
+     * Returns the assigned variant key or the default value
+     */
+    getVariant(key: string, defaultValue?: string | null): string | null;
+    /**
+     * Get the payload for a multivariate flag's assigned variant
+     */
+    getVariantPayload<T = unknown>(key: string, defaultValue?: T | null): T | null;
+    /**
+     * Force refresh flags from the server
+     */
+    refreshFlags(): Promise<void>;
+    track(eventName: string, properties?: TrackProperties): void;
+    trackPageView(url?: string, properties?: TrackProperties): void;
+    identify(userId: string, traits?: UserTraits): void;
+    group(groupId: string, traits?: GroupTraits): void;
+    resetAnalytics(): void;
+    getVisitorId(): Promise<VisitorIdResult>;
+    getDeviceSignals(): Promise<DeviceSignals>;
+    getFraudCheck(): Promise<FraudCheckResult>;
+    startReplay(): boolean;
+    stopReplay(): void;
+    isReplayRecording(): boolean;
+    getReplaySessionId(): string | null;
+    startTransaction(name: string, data?: Record<string, unknown>): string;
+    endTransaction(id: string, status?: 'ok' | 'error'): void;
+    startSpan(transactionId: string, name: string, data?: Record<string, unknown>): string;
+    endSpan(transactionId: string, spanId: string, status?: 'ok' | 'error'): void;
+    getWebVitals(): WebVitals;
+    cronCheckin(slug: string, options?: CronCheckinOptions): Promise<void>;
+    cronStart(slug: string, environment?: string): CronHandle;
+    cronWrap<T>(slug: string, fn: () => Promise<T>, environment?: string): Promise<T>;
+    metricIncrement(name: string, value?: number, options?: MetricOptions): void;
+    metricGauge(name: string, value: number, options?: MetricOptions): void;
+    metricHistogram(name: string, value: number, options?: MetricOptions): void;
+    metricDistribution(name: string, value: number, options?: MetricOptions): void;
+    metricTime<T>(name: string, fn: () => Promise<T>, options?: MetricOptions): Promise<T>;
+    metricStartTimer(name: string, options?: MetricOptions): {
+        stop: () => void;
+    };
+    flushMetrics(): Promise<void>;
+    dbTrack<T>(query: string, fn: () => Promise<T>, source?: string): Promise<T>;
+    dbTrackSync<T>(query: string, fn: () => T, source?: string): T;
+    getDbQueryCount(): number;
+    resetDbQueryCount(): void;
+    getDbNPlusOnePatterns(): Array<{
+        query: string;
+        count: number;
+    }>;
+    profile<T>(name: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+    startProfileSpan(name: string, metadata?: Record<string, unknown>): () => void;
+    getProfiles(): ProfileData[];
+    getLatestProfile(): ProfileData | null;
+    flushProfiles(): Promise<void>;
     setContext(context: ErrorContext): void;
     setUser(user: ErrorContext['user']): void;
     setTags(tags: Record<string, string>): void;
@@ -53,12 +597,61 @@ declare class SitePongClient {
     private log;
 }
 declare const sitepong: SitePongClient;
-declare const init: (config: SitePongConfig) => void;
+declare const init: (config: SitePongInitConfig) => void;
 declare const captureError: (error: Error | string, additionalContext?: ErrorContext) => void;
 declare const captureMessage: (message: string, level?: "info" | "warning" | "error", additionalContext?: ErrorContext) => void;
 declare const setContext: (context: ErrorContext) => void;
 declare const setUser: (user: ErrorContext["user"]) => void;
 declare const setTags: (tags: Record<string, string>) => void;
 declare const flush: () => Promise<void>;
+declare const getFlag: (key: string, defaultValue?: boolean) => boolean;
+declare const getAllFlags: () => Record<string, boolean>;
+declare const getVariant: (key: string, defaultValue?: string | null) => string | null;
+declare const getVariantPayload: <T = unknown>(key: string, defaultValue?: T | null) => T | null;
+declare const waitForFlags: () => Promise<void>;
+declare const areFlagsReady: () => boolean;
+declare const refreshFlags: () => Promise<void>;
+declare const track: (eventName: string, properties?: TrackProperties) => void;
+declare const trackPageView: (url?: string, properties?: TrackProperties) => void;
+declare const identify: (userId: string, traits?: UserTraits) => void;
+declare const group: (groupId: string, traits?: GroupTraits) => void;
+declare const resetAnalytics: () => void;
+declare const getVisitorId: () => Promise<VisitorIdResult>;
+declare const getDeviceSignals: () => Promise<DeviceSignals>;
+declare const getFraudCheck: () => Promise<FraudCheckResult>;
+declare const startReplay: () => boolean;
+declare const stopReplay: () => void;
+declare const isReplayRecording: () => boolean;
+declare const getReplaySessionId: () => string | null;
+declare const startTransaction: (name: string, data?: Record<string, unknown>) => string;
+declare const endTransaction: (id: string, status?: "ok" | "error") => void;
+declare const startSpan: (transactionId: string, name: string, data?: Record<string, unknown>) => string;
+declare const endSpan: (transactionId: string, spanId: string, status?: "ok" | "error") => void;
+declare const getWebVitals: () => WebVitals;
+declare const dbTrack: <T>(query: string, fn: () => Promise<T>, source?: string) => Promise<T>;
+declare const dbTrackSync: <T>(query: string, fn: () => T, source?: string) => T;
+declare const getDbQueryCount: () => number;
+declare const resetDbQueryCount: () => void;
+declare const getDbNPlusOnePatterns: () => Array<{
+    query: string;
+    count: number;
+}>;
+declare const cronCheckin: (slug: string, options?: CronCheckinOptions) => Promise<void>;
+declare const cronStart: (slug: string, environment?: string) => CronHandle;
+declare const cronWrap: <T>(slug: string, fn: () => Promise<T>, environment?: string) => Promise<T>;
+declare const metricIncrement: (name: string, value?: number, options?: MetricOptions) => void;
+declare const metricGauge: (name: string, value: number, options?: MetricOptions) => void;
+declare const metricHistogram: (name: string, value: number, options?: MetricOptions) => void;
+declare const metricDistribution: (name: string, value: number, options?: MetricOptions) => void;
+declare const metricTime: <T>(name: string, fn: () => Promise<T>, options?: MetricOptions) => Promise<T>;
+declare const metricStartTimer: (name: string, options?: MetricOptions) => {
+    stop: () => void;
+};
+declare const flushMetrics: () => Promise<void>;
+declare const profile: <T>(name: string, fn: () => Promise<T>, metadata?: Record<string, unknown>) => Promise<T>;
+declare const startProfileSpan: (name: string, metadata?: Record<string, unknown>) => () => void;
+declare const getProfiles: () => ProfileData[];
+declare const getLatestProfile: () => ProfileData | null;
+declare const flushProfiles: () => Promise<void>;
 
-export { type CapturedError, type ErrorContext, type SitePongConfig, captureError, captureMessage, sitepong as default, flush, init, setContext, setTags, setUser };
+export { type CapturedError, type CronCheckinOptions, type CronHandle, type DatabaseQueryEvent, type DatabaseTrackerConfig, type DeviceSignals, type ErrorContext, type FraudCheckResult, type GroupTraits, type MetricOptions, type PerformanceConfig, type PerformanceSpan, type PerformanceTransaction, type ProfileData, type ProfileFrame, type ProfilerConfig, type ReplayConfig, type ReplayEvent, type SitePongConfig, type SitePongInitConfig, type TraceContext, TracePropagator, type TrackProperties, type UserTraits, type VisitorIdResult, type WebVitals, areFlagsReady, captureError, captureMessage, clearAnonymousId, createTraceContext, cronCheckin, cronStart, cronWrap, dbTrack, dbTrackSync, sitepong as default, endSpan, endTransaction, extractTrace, flush, flushMetrics, flushProfiles, generateSpanId, generateTraceId, getAllFlags, getAnonymousId, getDbNPlusOnePatterns, getDbQueryCount, getDeviceSignals, getFlag, getFraudCheck, getLatestProfile, getProfiles, getReplaySessionId, getVariant, getVariantPayload, getVisitorId, getWebVitals, group, identify, init, isReplayRecording, metricDistribution, metricGauge, metricHistogram, metricIncrement, metricStartTimer, metricTime, profile, propagateTrace, refreshFlags, resetAnalytics, resetDbQueryCount, setAnonymousId, setContext, setTags, setUser, startProfileSpan, startReplay, startSpan, startTransaction, stopReplay, track, trackPageView, waitForFlags };