@iaportafolio/nextjs 0.1.1 → 0.3.0

package/dist/client.d.ts

@@ -0,0 +1,191 @@
+import * as React from 'react';
+
+/**
+ * Core RUM para navegador (interno de @iaportafolio/nextjs).
+ *
+ * Captura errores no manejados, Web Vitals, navegaciones y clicks como
+ * breadcrumbs, y envía todo en lotes a la API de ingesta usando
+ * sendBeacon cuando el tab se cierra (sin perder eventos).
+ *
+ * Este archivo no se exporta directamente al usuario; el entrypoint
+ * público es `@iaportafolio/nextjs/client`.
+ */
+type Severity = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+interface FaroBrowserOptions {
+    endpoint: string;
+    token: string;
+    service: string;
+    environment?: string;
+    release?: string;
+    /** Atributos por defecto adjuntados a cada evento */
+    attributes?: Record<string, string | number | boolean>;
+    /** Cadencia de flush en ms (default 2000) */
+    flushIntervalMs?: number;
+    /** Tamaño máximo de batch por POST (default 100) */
+    maxBatchSize?: number;
+    /** Cola en memoria máxima (default 2000) */
+    maxQueueSize?: number;
+    /** Tamaño del ring buffer de breadcrumbs (default 30) */
+    maxBreadcrumbs?: number;
+    /** Capturar window.onerror + unhandledrejection (default true) */
+    captureUnhandled?: boolean;
+    /** Capturar console.error y console.warn (default false — puede meter ruido) */
+    captureConsole?: boolean;
+    /** Capturar Web Vitals LCP/CLS/INP/FID/TTFB (default true) */
+    captureWebVitals?: boolean;
+    /** Capturar clicks como breadcrumbs (default true) */
+    captureClicks?: boolean;
+    /** Capturar navegaciones SPA (history.pushState/popstate) (default true) */
+    captureNavigation?: boolean;
+    /** Hook para muestrear o redactar eventos antes de enviar; devolver null descarta */
+    beforeSend?: (event: WireEvent) => WireEvent | null;
+}
+interface UserContext {
+    id?: string;
+    email?: string;
+    username?: string;
+    [key: string]: string | undefined;
+}
+interface Breadcrumb {
+    category: 'click' | 'navigation' | 'console' | 'fetch' | 'custom';
+    message: string;
+    timestamp: number;
+    data?: Record<string, string | number | boolean | undefined>;
+}
+interface LogEntry {
+    level?: Severity;
+    message: string;
+    attributes?: Record<string, unknown>;
+    trace_id?: string;
+    span_id?: string;
+}
+interface WireEvent {
+    level: Severity;
+    message: string;
+    timestamp: string;
+    attributes: Record<string, string>;
+    trace_id?: string;
+    span_id?: string;
+}
+declare class FaroBrowser {
+    private opts;
+    private queue;
+    private breadcrumbs;
+    private user;
+    private timer;
+    private cleanup;
+    private closed;
+    constructor(opts: FaroBrowserOptions);
+    setUser(user: UserContext | null): void;
+    addBreadcrumb(crumb: Omit<Breadcrumb, 'timestamp'>): void;
+    log(entry: LogEntry): void;
+    info(message: string, attrs?: Record<string, unknown>): void;
+    warn(message: string, attrs?: Record<string, unknown>): void;
+    error(message: string, attrs?: Record<string, unknown>): void;
+    captureException(err: unknown, ctx?: {
+        tags?: Record<string, string>;
+        message?: string;
+    }): void;
+    flush(useBeacon?: boolean): Promise<void>;
+    close(): void;
+    private enqueue;
+    private composeAttributes;
+    private installErrorHandlers;
+    private installConsoleCapture;
+    private installWebVitals;
+    private installClickTracking;
+    private installNavigationTracking;
+    private installLifecycleHooks;
+}
+declare function getClient(): FaroBrowser;
+declare function log(entry: LogEntry): void;
+declare function info(msg: string, attrs?: Record<string, unknown>): void;
+declare function warn(msg: string, attrs?: Record<string, unknown>): void;
+declare function error(msg: string, attrs?: Record<string, unknown>): void;
+declare function captureException(err: unknown, ctx?: {
+    tags?: Record<string, string>;
+    message?: string;
+}): void;
+declare function setUser(user: UserContext | null): void;
+declare function addBreadcrumb(crumb: Omit<Breadcrumb, 'timestamp'>): void;
+declare function flush(): Promise<void>;
+declare function close(): void;
+
+/**
+ * React ErrorBoundary que reporta automáticamente a Faro.
+ * Importar desde `@iaportafolio/nextjs/client`.
+ */
+
+interface FaroErrorBoundaryProps {
+    children: React.ReactNode;
+    /** Fallback UI cuando un hijo lanza. Recibe el error y un `reset` para reintentar. */
+    fallback?: React.ReactNode | ((args: {
+        error: Error;
+        reset: () => void;
+    }) => React.ReactNode);
+    /** Tags adicionales para el evento (ej. nombre del módulo) */
+    tags?: Record<string, string>;
+    /** Hook opcional cuando se captura un error (para tracking adicional) */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+}
+interface State {
+    error: Error | null;
+}
+declare class FaroErrorBoundary extends React.Component<FaroErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    reset: () => void;
+    render(): React.ReactNode;
+}
+
+/**
+ * Faro para Next.js — lado cliente (corre en el navegador).
+ *
+ * Punto de entrada público para el RUM en Next.js:
+ *  - captura de window.error / unhandledrejection
+ *  - Web Vitals (LCP/CLS/INP/FCP/TTFB)
+ *  - breadcrumbs de clicks y navegaciones (history.pushState/popstate)
+ *  - sendBeacon en pagehide / visibilitychange=hidden (no se pierden eventos)
+ *  - ErrorBoundary React (`<FaroErrorBoundary>`)
+ *  - auto-detección de release desde env vars típicas de Vercel/Next
+ *
+ * Uso típico (App Router):
+ *
+ *   // app/faro-client.tsx
+ *   'use client';
+ *   import { useEffect } from 'react';
+ *   import { usePathname, useSearchParams } from 'next/navigation';
+ *   import { initFaroClient, addBreadcrumb } from '@iaportafolio/nextjs/client';
+ *
+ *   export function FaroClient() {
+ *     const pathname = usePathname();
+ *     const search = useSearchParams();
+ *
+ *     useEffect(() => {
+ *       initFaroClient({
+ *         endpoint: process.env.NEXT_PUBLIC_FARO_ENDPOINT!,
+ *         token:    process.env.NEXT_PUBLIC_FARO_TOKEN!,
+ *         service:  'mi-next-app-web',
+ *       });
+ *     }, []);
+ *
+ *     useEffect(() => {
+ *       addBreadcrumb({ category: 'navigation', message: pathname, data: { pathname } });
+ *     }, [pathname, search]);
+ *
+ *     return null;
+ *   }
+ *
+ *   // app/layout.tsx
+ *   import { FaroClient } from './faro-client';
+ *   <body><FaroClient />{children}</body>
+ */
+
+/**
+ * Inicializa el RUM en el navegador. Seguro de llamar en SSR — si `typeof window === 'undefined'`
+ * el core no hace nada. Llámalo desde `useEffect` en un componente 'use client'.
+ */
+declare function initFaroClient(opts: FaroBrowserOptions): FaroBrowser;
+
+export { type Breadcrumb, FaroBrowser, type FaroBrowserOptions, FaroErrorBoundary, type FaroErrorBoundaryProps, type LogEntry, type Severity, type UserContext, type WireEvent, addBreadcrumb, captureException, close, error, flush, getClient, info, initFaroClient, log, setUser, warn };

package/dist/client.js

@@ -1,8 +1,28 @@
 import {
-  faroClient,
-  initFaroClient
-} from "./chunk-TYH3TMKC.js";
+  FaroErrorBoundary,
+  addBreadcrumb,
+  captureException,
+  close,
+  error,
+  flush,
+  getClient,
+  info,
+  initFaroClient,
+  log,
+  setUser,
+  warn
+} from "./chunk-I3FDJF4L.js";
 export {
-  faroClient,
-  initFaroClient
+  FaroErrorBoundary,
+  addBreadcrumb,
+  captureException,
+  close,
+  error,
+  flush,
+  getClient,
+  info,
+  initFaroClient,
+  log,
+  setUser,
+  warn
 };