sitepong 0.0.1 → 0.0.5

package/dist/react/index.d.ts

@@ -0,0 +1,409 @@
+import React, { Component, ReactNode, ErrorInfo } from 'react';
+import { TrackProperties, UserTraits, GroupTraits, DeviceSignals, WebVitals } from '../index.js';
+export { CapturedError, CronCheckinOptions, CronHandle, DatabaseQueryEvent, DatabaseTrackerConfig, ErrorContext, FraudCheckResult, MetricOptions, PerformanceConfig, PerformanceSpan, PerformanceTransaction, ProfileData, ProfileFrame, ProfilerConfig, ReplayConfig, ReplayEvent, SitePongConfig, SitePongInitConfig, TraceContext, TracePropagator, VisitorIdResult, areFlagsReady, captureError, captureMessage, clearAnonymousId, createTraceContext, cronCheckin, cronStart, cronWrap, dbTrack, dbTrackSync, 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 } from '../index.js';
+
+/**
+ * SitePong SDK Types
+ */
+interface SitePongConfig {
+    /** DSN in format: https://<public_key>@ingest.sitepong.com/<project_id> */
+    dsn?: string;
+    /** API key in format: sp_live_xxx or sp_test_xxx */
+    apiKey?: string;
+    /** Environment name (e.g., 'production', 'staging', 'development') */
+    environment?: string;
+    /** Release/version string */
+    release?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable/disable the SDK entirely */
+    enabled?: boolean;
+    /** Sample rate for errors (0.0 to 1.0) */
+    sampleRate?: number;
+    /** Maximum number of breadcrumbs to keep */
+    maxBreadcrumbs?: number;
+    /** Hook to modify or filter events before sending */
+    beforeSend?: (event: ErrorEvent) => ErrorEvent | null;
+    /** Auto-capture configuration */
+    autoCapture?: {
+        errors?: boolean;
+        unhandledRejections?: boolean;
+        console?: boolean;
+    };
+    /** Custom API endpoint (for self-hosted) */
+    apiEndpoint?: string;
+}
+interface User {
+    id?: string;
+    email?: string;
+    username?: string;
+    [key: string]: unknown;
+}
+interface Breadcrumb {
+    type: "default" | "http" | "navigation" | "ui" | "console" | "error";
+    category?: string;
+    message?: string;
+    level?: "fatal" | "error" | "warning" | "info" | "debug";
+    timestamp: number;
+    data?: Record<string, unknown>;
+}
+interface ErrorEvent {
+    event_id: string;
+    timestamp: string;
+    level: "fatal" | "error" | "warning" | "info" | "debug";
+    message: string;
+    exception?: {
+        type: string;
+        value: string;
+        stacktrace?: StackFrame[];
+    };
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    user?: User;
+    breadcrumbs?: Breadcrumb[];
+    context?: {
+        browser?: BrowserContext;
+        os?: OSContext;
+        device?: DeviceContext;
+        [key: string]: unknown;
+    };
+    environment?: string;
+    release?: string;
+    request?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+    };
+}
+interface StackFrame {
+    filename?: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+}
+interface BrowserContext {
+    name?: string;
+    version?: string;
+}
+interface OSContext {
+    name?: string;
+    version?: string;
+}
+interface DeviceContext {
+    family?: string;
+    model?: string;
+    brand?: string;
+}
+type LogLevel = "fatal" | "error" | "warning" | "info" | "debug";
+interface CaptureContext {
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    user?: User;
+    level?: LogLevel;
+    fingerprint?: string[];
+}
+
+interface SitePongContextValue {
+    isInitialized: boolean;
+}
+declare const SitePongContext: React.Context<SitePongContextValue>;
+interface SitePongProviderProps {
+    /**
+     * DSN in format: https://<public_key>@ingest.sitepong.com/<project_id>
+     */
+    dsn?: string;
+    /**
+     * API key in format: sp_live_xxx or sp_test_xxx
+     */
+    apiKey?: string;
+    /**
+     * Additional configuration options
+     */
+    config?: Omit<SitePongConfig, "dsn" | "apiKey">;
+    /**
+     * Children to render
+     */
+    children: React.ReactNode;
+}
+/**
+ * SitePong Provider Component
+ *
+ * Initializes the SitePong SDK and provides context to child components.
+ *
+ * @example
+ * ```tsx
+ * import { SitePongProvider } from '@sitepong/react';
+ *
+ * function App() {
+ *   return (
+ *     <SitePongProvider dsn={process.env.NEXT_PUBLIC_SITEPONG_DSN}>
+ *       <MyApp />
+ *     </SitePongProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SitePongProvider({ dsn, apiKey, config, children, }: SitePongProviderProps): React.ReactElement;
+
+interface SitePongErrorBoundaryProps {
+    /**
+     * Fallback UI to render when an error occurs
+     */
+    fallback?: ReactNode | ((error: Error, resetError: () => void) => ReactNode);
+    /**
+     * Callback when an error is caught
+     */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /**
+     * Callback before the error is sent to SitePong
+     */
+    beforeCapture?: (error: Error) => void;
+    /**
+     * Whether to show a dialog to the user (future feature)
+     */
+    showDialog?: boolean;
+    /**
+     * Children to render
+     */
+    children: ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * SitePong Error Boundary
+ *
+ * Catches React component errors and reports them to SitePong.
+ *
+ * @example
+ * ```tsx
+ * import { SitePongErrorBoundary } from '@sitepong/react';
+ *
+ * function App() {
+ *   return (
+ *     <SitePongErrorBoundary fallback={<ErrorPage />}>
+ *       <MyApp />
+ *     </SitePongErrorBoundary>
+ *   );
+ * }
+ * ```
+ *
+ * @example With reset functionality
+ * ```tsx
+ * <SitePongErrorBoundary
+ *   fallback={(error, resetError) => (
+ *     <div>
+ *       <p>Something went wrong: {error.message}</p>
+ *       <button onClick={resetError}>Try again</button>
+ *     </div>
+ *   )}
+ * >
+ *   <MyApp />
+ * </SitePongErrorBoundary>
+ * ```
+ */
+declare class SitePongErrorBoundary extends Component<SitePongErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: SitePongErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    resetError: () => void;
+    render(): ReactNode;
+}
+
+/**
+ * Add a breadcrumb to the trail
+ */
+declare function addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+
+/**
+ * Hook to access all SitePong SDK methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const sitepong = useSitePong();
+ *
+ *   useEffect(() => {
+ *     sitepong.setUser({ id: 'user-123' });
+ *   }, []);
+ *
+ *   const handleError = () => {
+ *     sitepong.captureMessage('Something happened', 'warning');
+ *   };
+ * }
+ * ```
+ */
+declare function useSitePong(): {
+    isInitialized: boolean;
+    captureException: (error: Error | unknown, context?: CaptureContext) => string | null;
+    captureMessage: (message: string, level?: LogLevel, context?: CaptureContext) => string | null;
+    setUser: (user: User | null) => void;
+    clearUser: () => void;
+    setTag: (key: string, value: string) => void;
+    setTags: (tags: Record<string, string>) => void;
+    setContext: (name: string, context: Record<string, unknown>) => void;
+    addBreadcrumb: typeof addBreadcrumb;
+    getConfig: () => SitePongConfig | null;
+};
+/**
+ * Hook to capture errors with a stable callback
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const capture = useErrorCapture();
+ *
+ *   const handleClick = async () => {
+ *     try {
+ *       await riskyOperation();
+ *     } catch (error) {
+ *       capture(error, { tags: { action: 'click' } });
+ *     }
+ *   };
+ * }
+ * ```
+ */
+declare function useErrorCapture(): (error: Error | unknown, context?: CaptureContext) => string | null;
+/**
+ * Hook to capture exceptions (alias for useErrorCapture)
+ */
+declare function useCaptureException(): (error: Error | unknown, context?: CaptureContext) => string | null;
+/**
+ * Hook to capture messages
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const capture = useCaptureMessage();
+ *
+ *   useEffect(() => {
+ *     capture('Component mounted', 'info');
+ *   }, []);
+ * }
+ * ```
+ */
+declare function useCaptureMessage(): (message: string, level?: LogLevel, context?: CaptureContext) => string | null;
+/**
+ * Hook to set the current user
+ *
+ * @example
+ * ```tsx
+ * function useAuth() {
+ *   const setUser = useSetUser();
+ *
+ *   const login = (user) => {
+ *     setUser({
+ *       id: user.id,
+ *       email: user.email,
+ *       username: user.name,
+ *     });
+ *   };
+ * }
+ * ```
+ */
+declare function useSetUser(): (user: User | null) => void;
+/**
+ * Hook to add breadcrumbs
+ *
+ * @example
+ * ```tsx
+ * function NavigationTracker() {
+ *   const addBreadcrumb = useAddBreadcrumb();
+ *
+ *   useEffect(() => {
+ *     addBreadcrumb({
+ *       type: 'navigation',
+ *       category: 'route',
+ *       message: 'Navigated to /dashboard',
+ *     });
+ *   }, []);
+ * }
+ * ```
+ */
+declare function useAddBreadcrumb(): (breadcrumb: Parameters<typeof addBreadcrumb>[0]) => void;
+/**
+ * Hook to track custom events with a stable callback
+ */
+declare function useTrack(): (eventName: string, properties?: TrackProperties) => void;
+/**
+ * Hook to track page views with a stable callback
+ */
+declare function useTrackPageView(): (url?: string, properties?: TrackProperties) => void;
+/**
+ * Hook to identify users with a stable callback
+ */
+declare function useIdentify(): (userId: string, traits?: UserTraits) => void;
+/**
+ * Hook to associate users with groups with a stable callback
+ */
+declare function useGroup(): (groupId: string, traits?: GroupTraits) => void;
+/**
+ * Hook to get the visitor ID with loading/error state
+ */
+declare function useVisitorId(): {
+    visitorId: string | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to perform a fraud check with loading/error state
+ */
+declare function useFraudCheck(): {
+    visitorId: string | null;
+    riskScore: number | null;
+    signals: DeviceSignals | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook to get a feature flag value with reactive updates
+ */
+declare function useFeatureFlag(key: string, defaultValue?: boolean): boolean;
+/**
+ * Hook to get a feature flag payload (the flag value and metadata)
+ */
+declare function useFeatureFlagPayload(key: string): {
+    enabled: boolean;
+    loading: boolean;
+};
+/**
+ * Hook for A/B experiments based on feature flags
+ * Returns the experiment variant (true/false) and loading state
+ */
+declare function useExperiment(experimentKey: string): {
+    variant: 'control' | 'test';
+    loading: boolean;
+};
+/**
+ * Hook to get all feature flags
+ */
+declare function useAllFlags(): Record<string, boolean>;
+/**
+ * Hook to track component render performance as a transaction
+ */
+declare function usePerformanceTransaction(name: string): {
+    start: () => string;
+    end: (status?: "ok" | "error") => void;
+    transactionId: string | null;
+};
+/**
+ * Hook to get current Web Vitals
+ */
+declare function useWebVitals(): WebVitals;
+/**
+ * Hook to control session replay recording
+ */
+declare function useReplay(): {
+    recording: boolean;
+    start: () => boolean;
+    stop: () => void;
+};
+
+export { DeviceSignals, GroupTraits, SitePongContext, SitePongErrorBoundary, type SitePongErrorBoundaryProps, SitePongProvider, type SitePongProviderProps, TrackProperties, UserTraits, WebVitals, useAddBreadcrumb, useAllFlags, useCaptureException, useCaptureMessage, useErrorCapture, useExperiment, useFeatureFlag, useFeatureFlagPayload, useFraudCheck, useGroup, useIdentify, usePerformanceTransaction, useReplay, useSetUser, useSitePong, useTrack, useTrackPageView, useVisitorId, useWebVitals };