@iaportafolio/nextjs 0.1.1 → 0.3.0

package/dist/client.cjs

@@ -1,6 +1,9 @@
+"use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -14,131 +17,400 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
-  faroClient: () => faroClient,
-  initFaroClient: () => initFaroClient
+  FaroErrorBoundary: () => FaroErrorBoundary,
+  addBreadcrumb: () => addBreadcrumb,
+  captureException: () => captureException,
+  close: () => close,
+  error: () => error,
+  flush: () => flush,
+  getClient: () => getClient,
+  info: () => info,
+  initFaroClient: () => initFaroClient,
+  log: () => log,
+  setUser: () => setUser,
+  warn: () => warn
 });
 module.exports = __toCommonJS(client_exports);
-var client = null;
-function newClient(opts) {
-  const endpoint = opts.endpoint.replace(/\/$/, "");
-  const queue = [];
-  const maxBatch = opts.maxBatchSize ?? 100;
-  let pendingTimer = null;
-  function scheduleFlush() {
-    if (pendingTimer) return;
-    pendingTimer = setTimeout(() => {
-      pendingTimer = null;
-      void flush();
-    }, opts.flushIntervalMs ?? 1500);
-  }
-  async function flush() {
-    if (queue.length === 0) return;
-    const batch = queue.splice(0, maxBatch);
-    try {
-      const body = JSON.stringify({ service: opts.service, logs: batch });
-      const ok = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && document.visibilityState === "hidden" ? navigator.sendBeacon(
-        `${endpoint}/api/v1/ingest/logs?_token=${encodeURIComponent(opts.token)}`,
-        new Blob([body], { type: "application/json" })
-      ) : false;
+
+// src/browser-core.ts
+var FaroBrowser = class {
+  constructor(opts) {
+    this.queue = [];
+    this.breadcrumbs = [];
+    this.user = null;
+    this.timer = null;
+    this.cleanup = [];
+    this.closed = false;
+    this.opts = {
+      endpoint: opts.endpoint.replace(/\/$/, ""),
+      token: opts.token,
+      service: opts.service,
+      environment: opts.environment,
+      release: opts.release,
+      attributes: opts.attributes,
+      flushIntervalMs: opts.flushIntervalMs ?? 2e3,
+      maxBatchSize: opts.maxBatchSize ?? 100,
+      maxQueueSize: opts.maxQueueSize ?? 2e3,
+      maxBreadcrumbs: opts.maxBreadcrumbs ?? 30,
+      captureUnhandled: opts.captureUnhandled ?? true,
+      captureConsole: opts.captureConsole ?? false,
+      captureWebVitals: opts.captureWebVitals ?? true,
+      captureClicks: opts.captureClicks ?? true,
+      captureNavigation: opts.captureNavigation ?? true,
+      beforeSend: opts.beforeSend
+    };
+    if (typeof window === "undefined") {
+      return;
+    }
+    this.timer = setInterval(() => void this.flush(), this.opts.flushIntervalMs);
+    if (this.opts.captureUnhandled) this.installErrorHandlers();
+    if (this.opts.captureConsole) this.installConsoleCapture();
+    if (this.opts.captureWebVitals) this.installWebVitals();
+    if (this.opts.captureClicks) this.installClickTracking();
+    if (this.opts.captureNavigation) this.installNavigationTracking();
+    this.installLifecycleHooks();
+  }
+  setUser(user) {
+    this.user = user;
+  }
+  addBreadcrumb(crumb) {
+    if (this.breadcrumbs.length >= this.opts.maxBreadcrumbs) {
+      this.breadcrumbs.shift();
+    }
+    this.breadcrumbs.push({ ...crumb, timestamp: Date.now() });
+  }
+  log(entry) {
+    if (this.closed) return;
+    const attrs = this.composeAttributes(entry.attributes);
+    const evt = {
+      level: entry.level ?? "INFO",
+      message: entry.message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      attributes: attrs,
+      trace_id: entry.trace_id,
+      span_id: entry.span_id
+    };
+    this.enqueue(evt);
+  }
+  info(message, attrs) {
+    this.log({ level: "INFO", message, attributes: attrs });
+  }
+  warn(message, attrs) {
+    this.log({ level: "WARN", message, attributes: attrs });
+  }
+  error(message, attrs) {
+    this.log({ level: "ERROR", message, attributes: attrs });
+  }
+  captureException(err, ctx) {
+    const e = toError(err);
+    this.log({
+      level: "ERROR",
+      message: ctx?.message ?? `${e.name}: ${e.message}`,
+      attributes: {
+        "exception.type": e.name,
+        "exception.message": e.message,
+        "exception.stacktrace": e.stack ?? "",
+        ...ctx?.tags ?? {}
+      }
+    });
+  }
+  async flush(useBeacon = false) {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.opts.maxBatchSize);
+    const body = JSON.stringify({ service: this.opts.service, logs: batch });
+    const url = `${this.opts.endpoint}/api/v1/ingest/logs`;
+    if (useBeacon && typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      const beaconUrl = `${url}?_token=${encodeURIComponent(this.opts.token)}`;
+      const ok = navigator.sendBeacon(beaconUrl, new Blob([body], { type: "application/json" }));
       if (ok) return;
-      const res = await fetch(`${endpoint}/api/v1/ingest/logs`, {
+    }
+    try {
+      const res = await fetch(url, {
         method: "POST",
         keepalive: true,
         headers: {
-          "Authorization": `Bearer ${opts.token}`,
+          "Authorization": `Bearer ${this.opts.token}`,
           "Content-Type": "application/json"
         },
         body
       });
-      if (!res.ok) {
-        if (res.status >= 500) queue.unshift(...batch);
+      if (!res.ok && res.status >= 500) {
+        this.queue.unshift(...batch);
       }
-    } catch (_e) {
-      queue.unshift(...batch);
+    } catch {
+      this.queue.unshift(...batch);
     }
   }
-  function enqueue(level, message, attributes) {
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    for (const fn of this.cleanup) fn();
+    this.cleanup = [];
+    void this.flush(true);
+  }
+  enqueue(evt) {
+    const processed = this.opts.beforeSend ? this.opts.beforeSend(evt) : evt;
+    if (!processed) return;
+    if (this.queue.length >= this.opts.maxQueueSize) return;
+    this.queue.push(processed);
+  }
+  composeAttributes(extra) {
     const attrs = {};
-    if (opts.attributes) {
-      for (const [k, v] of Object.entries(opts.attributes)) attrs[k] = String(v);
+    if (this.opts.attributes) {
+      for (const [k, v] of Object.entries(this.opts.attributes)) attrs[k] = String(v);
     }
-    if (opts.environment) attrs["deployment.environment"] = opts.environment;
-    if (opts.release) attrs["service.version"] = opts.release;
+    if (this.opts.environment) attrs["deployment.environment"] = this.opts.environment;
+    if (this.opts.release) attrs["service.version"] = this.opts.release;
     if (typeof window !== "undefined") {
       attrs["browser.url"] = window.location.href;
       attrs["browser.userAgent"] = navigator.userAgent;
     }
-    if (attributes) {
-      for (const [k, v] of Object.entries(attributes)) {
+    if (this.user) {
+      if (this.user.id) attrs["user.id"] = this.user.id;
+      if (this.user.email) attrs["user.email"] = this.user.email;
+      if (this.user.username) attrs["user.name"] = this.user.username;
+    }
+    if (this.breadcrumbs.length > 0) {
+      attrs["breadcrumbs"] = JSON.stringify(this.breadcrumbs.slice(-this.opts.maxBreadcrumbs));
+    }
+    if (extra) {
+      for (const [k, v] of Object.entries(extra)) {
         attrs[k] = typeof v === "string" ? v : JSON.stringify(v);
       }
     }
-    queue.push({
-      level,
-      message,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      attributes: attrs
-    });
-    if (queue.length >= maxBatch) void flush();
-    else scheduleFlush();
-  }
-  return {
-    log: (e) => enqueue(e.level ?? "INFO", e.message, e.attributes),
-    info: (m, a) => enqueue("INFO", m, a),
-    warn: (m, a) => enqueue("WARN", m, a),
-    error: (m, a) => enqueue("ERROR", m, a),
-    captureException: (err, ctx) => {
-      const e = err instanceof Error ? err : new Error(typeof err === "string" ? err : JSON.stringify(err));
-      enqueue("ERROR", (ctx == null ? void 0 : ctx.message) ?? `${e.name}: ${e.message}`, {
-        "exception.type": e.name,
-        "exception.message": e.message,
-        "exception.stacktrace": e.stack ?? "",
-        ...(ctx == null ? void 0 : ctx.tags) ?? {}
+    return attrs;
+  }
+  installErrorHandlers() {
+    const onError = (ev) => {
+      this.captureException(ev.error ?? ev.message, {
+        tags: { origin: "window.error", "source.file": ev.filename ?? "", "source.line": String(ev.lineno ?? 0) }
       });
-    },
-    flush
-  };
-}
-function initFaroClient(opts) {
-  if (typeof window === "undefined") {
-    return {
-      log() {
-      },
-      info() {
-      },
-      warn() {
-      },
-      error() {
-      },
-      captureException() {
-      },
-      flush: async () => void 0
     };
+    const onRejection = (ev) => {
+      this.captureException(ev.reason, { tags: { origin: "unhandledrejection" } });
+    };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    this.cleanup.push(() => window.removeEventListener("error", onError));
+    this.cleanup.push(() => window.removeEventListener("unhandledrejection", onRejection));
   }
-  client = newClient(opts);
-  window.addEventListener("error", (ev) => {
-    client == null ? void 0 : client.captureException(ev.error ?? ev.message, { tags: { origin: "window.error" } });
-  });
-  window.addEventListener("unhandledrejection", (ev) => {
-    client == null ? void 0 : client.captureException(ev.reason, { tags: { origin: "unhandledrejection" } });
-  });
-  document.addEventListener("visibilitychange", () => {
-    if (document.visibilityState === "hidden") void (client == null ? void 0 : client.flush());
-  });
-  window.addEventListener("pagehide", () => void (client == null ? void 0 : client.flush()));
-  return client;
+  installConsoleCapture() {
+    const orig = { error: console.error, warn: console.warn };
+    console.error = (...args) => {
+      this.addBreadcrumb({ category: "console", message: String(args[0] ?? ""), data: { level: "error" } });
+      this.log({ level: "ERROR", message: stringifyArgs(args), attributes: { "console.method": "error" } });
+      orig.error.apply(console, args);
+    };
+    console.warn = (...args) => {
+      this.addBreadcrumb({ category: "console", message: String(args[0] ?? ""), data: { level: "warn" } });
+      orig.warn.apply(console, args);
+    };
+    this.cleanup.push(() => {
+      console.error = orig.error;
+      console.warn = orig.warn;
+    });
+  }
+  installWebVitals() {
+    void import("web-vitals").then(({ onLCP, onCLS, onINP, onFCP, onTTFB }) => {
+      const report = (name) => (m) => {
+        this.log({
+          level: "INFO",
+          message: `web-vital ${name}`,
+          attributes: {
+            "metric.name": name,
+            "metric.value": m.value,
+            "metric.rating": m.rating,
+            "metric.id": m.id
+          }
+        });
+      };
+      onLCP(report("LCP"));
+      onCLS(report("CLS"));
+      onINP(report("INP"));
+      onFCP(report("FCP"));
+      onTTFB(report("TTFB"));
+    }).catch(() => {
+    });
+  }
+  installClickTracking() {
+    const onClick = (ev) => {
+      const target = ev.target;
+      if (!target) return;
+      const tag = target.tagName?.toLowerCase() ?? "";
+      const id = target.id;
+      const text = (target.textContent ?? "").trim().slice(0, 60);
+      const data = { tag };
+      if (id) data.id = id;
+      if (text) data.text = text;
+      this.addBreadcrumb({ category: "click", message: `${tag}${id ? "#" + id : ""}`, data });
+    };
+    window.addEventListener("click", onClick, { capture: true, passive: true });
+    this.cleanup.push(() => window.removeEventListener("click", onClick, { capture: true }));
+  }
+  installNavigationTracking() {
+    const log2 = (from, to, method) => {
+      if (from === to) return;
+      this.addBreadcrumb({ category: "navigation", message: `${from} \u2192 ${to}`, data: { method, to } });
+    };
+    const origPush = history.pushState;
+    const origReplace = history.replaceState;
+    history.pushState = function(...args) {
+      const from = location.href;
+      const ret = origPush.apply(this, args);
+      log2(from, location.href, "pushState");
+      return ret;
+    };
+    history.replaceState = function(...args) {
+      const from = location.href;
+      const ret = origReplace.apply(this, args);
+      log2(from, location.href, "replaceState");
+      return ret;
+    };
+    const onPop = () => log2("", location.href, "popstate");
+    window.addEventListener("popstate", onPop);
+    this.cleanup.push(() => {
+      history.pushState = origPush;
+      history.replaceState = origReplace;
+      window.removeEventListener("popstate", onPop);
+    });
+  }
+  installLifecycleHooks() {
+    const onHide = () => {
+      if (document.visibilityState === "hidden") void this.flush(true);
+    };
+    const onPageHide = () => void this.flush(true);
+    document.addEventListener("visibilitychange", onHide);
+    window.addEventListener("pagehide", onPageHide);
+    this.cleanup.push(() => document.removeEventListener("visibilitychange", onHide));
+    this.cleanup.push(() => window.removeEventListener("pagehide", onPageHide));
+  }
+};
+function toError(err) {
+  if (err instanceof Error) return err;
+  if (typeof err === "string") return new Error(err);
+  try {
+    return new Error(JSON.stringify(err));
+  } catch {
+    return new Error(String(err));
+  }
+}
+function stringifyArgs(args) {
+  return args.map((a) => typeof a === "string" ? a : a instanceof Error ? a.stack ?? a.message : safeJson(a)).join(" ");
+}
+function safeJson(v) {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+var singleton = null;
+function init(opts) {
+  if (singleton) singleton.close();
+  singleton = new FaroBrowser(opts);
+  return singleton;
+}
+function getClient() {
+  if (!singleton) throw new Error("faro: init() must be called before use");
+  return singleton;
+}
+function log(entry) {
+  getClient().log(entry);
+}
+function info(msg, attrs) {
+  getClient().info(msg, attrs);
 }
-function faroClient() {
-  if (!client) throw new Error("Hay que llamar a initFaroClient() antes de usarlo");
-  return client;
+function warn(msg, attrs) {
+  getClient().warn(msg, attrs);
+}
+function error(msg, attrs) {
+  getClient().error(msg, attrs);
+}
+function captureException(err, ctx) {
+  getClient().captureException(err, ctx);
+}
+function setUser(user) {
+  getClient().setUser(user);
+}
+function addBreadcrumb(crumb) {
+  getClient().addBreadcrumb(crumb);
+}
+function flush() {
+  return getClient().flush();
+}
+function close() {
+  getClient().close();
+}
+
+// src/browser-react.tsx
+var React = __toESM(require("react"), 1);
+var FaroErrorBoundary = class extends React.Component {
+  constructor() {
+    super(...arguments);
+    this.state = { error: null };
+    this.reset = () => {
+      this.setState({ error: null });
+    };
+  }
+  static getDerivedStateFromError(error2) {
+    return { error: error2 };
+  }
+  componentDidCatch(error2, info2) {
+    captureException(error2, {
+      tags: {
+        origin: "react.error-boundary",
+        ...this.props.tags ?? {}
+      },
+      message: error2.message
+    });
+    this.props.onError?.(error2, info2);
+  }
+  render() {
+    if (this.state.error) {
+      const fb = this.props.fallback;
+      if (typeof fb === "function") return fb({ error: this.state.error, reset: this.reset });
+      if (fb !== void 0) return fb;
+      return null;
+    }
+    return this.props.children;
+  }
+};
+
+// src/client.ts
+function initFaroClient(opts) {
+  let release = opts.release;
+  if (!release && typeof process !== "undefined" && process.env) {
+    release = process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA || process.env.NEXT_PUBLIC_GIT_COMMIT_SHA || process.env.NEXT_PUBLIC_VERSION || void 0;
+  }
+  return init({ ...opts, release });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  faroClient,
-  initFaroClient
+  FaroErrorBoundary,
+  addBreadcrumb,
+  captureException,
+  close,
+  error,
+  flush,
+  getClient,
+  info,
+  initFaroClient,
+  log,
+  setUser,
+  warn
 });

package/dist/client.d.cts

@@ -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 };