@watchforge/browser 0.1.14 → 0.1.16

package/bin/watchforge.js

@@ -344,6 +344,65 @@ export default function GlobalError(${propsSignature}) {
   log(`wrote ${path.relative(cwd, globalErrorPath)}`);
 }
 
+function createNextAppError(cwd, layoutPath) {
+  const appDir = path.dirname(layoutPath);
+  const usesTs = projectUsesTypeScript(cwd);
+  const errorPath = path.join(appDir, usesTs ? "error.tsx" : "error.jsx");
+
+  if (fileExists(errorPath)) {
+    const content = fs.readFileSync(errorPath, "utf8");
+    if (content.includes("@watchforge/browser") || content.includes("captureException")) {
+      log(`${path.relative(cwd, errorPath)} already contains WatchForge setup`);
+      return;
+    }
+    log(`skipped ${path.relative(cwd, errorPath)} because it already exists`);
+    log("add captureException(error) there to report App Router segment render errors");
+    return;
+  }
+
+  const propsSignature = usesTs
+    ? `{\n  error,\n  reset,\n}: {\n  error: Error & { digest?: string };\n  reset: () => void;\n}`
+    : `{ error, reset }`;
+
+  const content = `"use client";
+
+import { useEffect } from "react";
+import { captureException } from "@watchforge/browser";
+
+export default function Error(${propsSignature}) {
+  useEffect(() => {
+    void captureException(error, {
+      tags: {
+        framework: "nextjs",
+        runtime: "error-boundary",
+      },
+      extra: {
+        digest: error.digest,
+      },
+      contexts: {
+        nextjs: {
+          error_boundary: "app-error",
+          digest: error.digest || null,
+        },
+      },
+    });
+  }, [error]);
+
+  return (
+    <div>
+      <h2>Something went wrong.</h2>
+      <button type="button" onClick={reset}>
+        Try again
+      </button>
+    </div>
+  );
+}
+`;
+
+  writeIfChanged(errorPath, content);
+  log(`wrote ${path.relative(cwd, errorPath)}`);
+}
+
 function createNextInstrumentation(cwd, layoutPath) {
   const appRoot = path.dirname(layoutPath).includes(`${path.sep}src${path.sep}app`)
     ? path.join(cwd, "src")
@@ -399,6 +458,41 @@ export const onRequestError = watchForgeOnRequestError;
   log(`wrote ${path.relative(cwd, instrumentationPath)}`);
 }
 
+function createNextClientInstrumentation(cwd, layoutPath) {
+  const appRoot = path.dirname(layoutPath).includes(`${path.sep}src${path.sep}app`)
+    ? path.join(cwd, "src")
+    : cwd;
+  const instrumentationClientPath = path.join(
+    appRoot,
+    projectUsesTypeScript(cwd) ? "instrumentation-client.ts" : "instrumentation-client.js"
+  );
+  const configImport = toImportPath(
+    path.dirname(instrumentationClientPath),
+    getConfigPath(cwd)
+  );
+
+  if (fileExists(instrumentationClientPath)) {
+    const content = fs.readFileSync(instrumentationClientPath, "utf8");
+    if (content.includes("@watchforge/browser") && content.includes("register(")) {
+      log(`${path.relative(cwd, instrumentationClientPath)} already contains WatchForge client setup`);
+      return;
+    }
+
+    log(`skipped ${path.relative(cwd, instrumentationClientPath)} because it already exists`);
+    log("add register(watchforgeConfig) there to install browser error handlers before hydration");
+    return;
+  }
+
+  const content = `import { register } from "@watchforge/browser";
+import { watchforgeConfig } from "${configImport}";
+
+register(watchforgeConfig);
+`;
+
+  writeIfChanged(instrumentationClientPath, content);
+  log(`wrote ${path.relative(cwd, instrumentationClientPath)}`);
+}
+
 function patchNextConfig(cwd) {
   const configPath = findNextConfig(cwd);
   if (!configPath) {
@@ -595,8 +689,10 @@ function initNextjs(args) {
   if (layoutPath) {
     patchNextConfig(cwd);
     patchAppRouter(cwd, layoutPath);
+    createNextAppError(cwd, layoutPath);
     createNextGlobalError(cwd, layoutPath);
     createNextInstrumentation(cwd, layoutPath);
+    createNextClientInstrumentation(cwd, layoutPath);
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "description": "WatchForge JavaScript SDK for browser JavaScript, Next.js, React, Node.js, and Express.js",

package/src/client.js

@@ -22,6 +22,10 @@ let APP_ENV = "production";
 let RELEASE = null;
 let DEBUG = false;
 let CAPTURE_CONSOLE_ERRORS = true;
+let CAPTURE_RESOURCE_ERRORS = true;
+let CAPTURE_FAILED_REQUESTS = true;
+let CAPTURE_NODE_WARNINGS = false;
+let CAPTURE_NODE_MULTIPLE_RESOLVES = false;
 
 // Detect environment
 const isBrowser = typeof window !== "undefined";
@@ -34,6 +38,8 @@ let breadcrumbs = [];
 let browserInstrumentationInstalled = false;
 let nodeInstrumentationInstalled = false;
 let replayInitPromise = null;
+let capturingGlobalError = false;
+let browserRegisterKey = null;
 
 export function addBreadcrumb(breadcrumb) {
   const entry = {
@@ -58,6 +64,59 @@ function isWatchForgeInternalMessage(message) {
   return String(message || "").includes("WatchForge SDK");
 }
 
+function normalizeException(error, fallbackMessage = "Unknown error") {
+  if (error instanceof Error) return error;
+
+  const message =
+    typeof error === "string"
+      ? error
+      : error?.message ||
+        error?.reason?.message ||
+        String(error || fallbackMessage);
+  const normalized = new Error(message || fallbackMessage);
+
+  if (error && typeof error === "object") {
+    if (typeof error.stack === "string") {
+      normalized.stack = error.stack;
+    }
+    if (typeof error.name === "string") {
+      normalized.name = error.name;
+    }
+  }
+
+  return normalized;
+}
+
+function captureGlobalException(error, context = {}) {
+  if (capturingGlobalError) return;
+  capturingGlobalError = true;
+  setTimeout(() => {
+    capturingGlobalError = false;
+  }, 0);
+
+  void captureException(normalizeException(error, context.message), context);
+}
+
+function getElementDescriptor(element) {
+  if (!element || typeof element !== "object") return null;
+  const tag = element.tagName ? String(element.tagName).toLowerCase() : "unknown";
+  const src =
+    element.currentSrc ||
+    element.src ||
+    element.href ||
+    element.action ||
+    null;
+  return {
+    tag,
+    url: src ? String(src) : null,
+    id: element.id || null,
+    className:
+      typeof element.className === "string"
+        ? element.className
+        : null,
+  };
+}
+
 // Simple browser environment detectors (best-effort, not 100% accurate)
 function getBrowserContext() {
   if (!isBrowser) return null;
@@ -163,8 +222,7 @@ function setupBrowserInstrumentation() {
   if (browserInstrumentationInstalled) return;
   browserInstrumentationInstalled = true;
 
-  // Global error handlers (already existed but keep here with breadcrumbs)
-  window.onerror = function (msg, url, line, col, error) {
+  const handleWindowError = function (msg, url, line, col, error) {
     addBreadcrumb({
       type: "error",
       level: "error",
@@ -172,20 +230,94 @@ function setupBrowserInstrumentation() {
       message: String(msg),
       data: { url, line, col },
     });
-    void captureException(error || msg);
+    captureGlobalException(error || msg, {
+      tags: {
+        handled: false,
+        mechanism: "window.onerror",
+      },
+      extra: { url, line, col },
+      message: String(msg),
+    });
   };
 
-  window.onunhandledrejection = function (event) {
+  const handleUnhandledRejection = function (event) {
+    const reason = event?.reason;
     addBreadcrumb({
       type: "error",
       level: "error",
       category: "unhandledrejection",
-      message: String(event.reason),
+      message: String(reason),
       data: {},
     });
-    void captureException(event.reason);
+    captureGlobalException(reason, {
+      tags: {
+        handled: false,
+        mechanism: "unhandledrejection",
+      },
+    });
   };
 
+  const previousOnError = window.onerror;
+  window.onerror = function (msg, url, line, col, error) {
+    handleWindowError(msg, url, line, col, error);
+    if (typeof previousOnError === "function") {
+      return previousOnError.call(window, msg, url, line, col, error);
+    }
+    return false;
+  };
+
+  const previousUnhandledRejection = window.onunhandledrejection;
+  window.onunhandledrejection = function (event) {
+    handleUnhandledRejection(event);
+    if (typeof previousUnhandledRejection === "function") {
+      return previousUnhandledRejection.call(window, event);
+    }
+    return false;
+  };
+
+  window.addEventListener(
+    "error",
+    (event) => {
+      if (event?.error || event?.message) {
+        handleWindowError(
+          event.message,
+          event.filename,
+          event.lineno,
+          event.colno,
+          event.error
+        );
+        return;
+      }
+
+      const target = getElementDescriptor(event?.target);
+      if (!target) return;
+
+      addBreadcrumb({
+        type: "error",
+        level: "error",
+        category: "resource",
+        message: `Failed to load <${target.tag}> resource`,
+        data: target,
+      });
+
+      if (!CAPTURE_RESOURCE_ERRORS) return;
+
+      captureGlobalException(
+        new Error(`Failed to load <${target.tag}> resource${target.url ? `: ${target.url}` : ""}`),
+        {
+          tags: {
+            handled: false,
+            mechanism: "resource.error",
+            resource_tag: target.tag,
+          },
+          extra: target,
+        }
+      );
+    },
+    true
+  );
+  window.addEventListener("unhandledrejection", handleUnhandledRejection);
+
   // Console breadcrumbs
   ["log", "info", "warn", "error", "debug"].forEach((level) => {
     if (!console[level]) return;
@@ -348,6 +480,20 @@ function setupBrowserInstrumentation() {
             duration_ms: duration,
           },
         });
+        if (CAPTURE_FAILED_REQUESTS) {
+          void captureException(error, {
+            tags: {
+              handled: true,
+              mechanism: "fetch",
+              operation: "http.client",
+            },
+            extra: {
+              url,
+              method,
+              duration_ms: duration,
+            },
+          });
+        }
         throw error;
       }
     };
@@ -373,9 +519,10 @@ function setupBrowserInstrumentation() {
         const start = Date.now();
         xhr.addEventListener("loadend", () => {
           const duration = Date.now() - start;
+          const level = xhr.status >= 500 || xhr.status === 0 ? "error" : "info";
           addBreadcrumb({
             type: "http",
-            level: "info",
+            level,
             category: "http",
             message: `${method} ${url}`,
             data: {
@@ -386,6 +533,20 @@ function setupBrowserInstrumentation() {
             },
           });
         });
+        xhr.addEventListener("error", () => {
+          if (!CAPTURE_FAILED_REQUESTS) return;
+          void captureException(new Error(`XMLHttpRequest failed: ${method || "GET"} ${url || ""}`), {
+            tags: {
+              handled: true,
+              mechanism: "xhr",
+              operation: "http.client",
+            },
+            extra: {
+              url,
+              method,
+            },
+          });
+        });
         origSend.apply(xhr, sendArgs);
       };
 
@@ -431,13 +592,43 @@ export function register({
   ignoreClass = "rr-ignore",
   maskTextClass = "rr-mask",
   captureConsoleErrors = true,
+  captureResourceErrors = true,
+  captureFailedRequests = true,
+  captureNodeWarnings = false,
+  captureNodeMultipleResolves = false,
   projectRoot = null,
 }) {
+  const nextBrowserRegisterKey = isBrowser
+    ? JSON.stringify({
+        dsn,
+        app_env,
+        release,
+        debug,
+        replaysSessionSampleRate,
+        replaysOnErrorSampleRate,
+        maskAllInputs,
+        blockClass,
+        ignoreClass,
+        maskTextClass,
+        captureConsoleErrors,
+        captureResourceErrors,
+        captureFailedRequests,
+      })
+    : null;
+
+  if (isBrowser && browserRegisterKey === nextBrowserRegisterKey) {
+    return;
+  }
+
   DSN = dsn;
   APP_ENV = app_env;
   RELEASE = release;
   DEBUG = debug;
   CAPTURE_CONSOLE_ERRORS = Boolean(captureConsoleErrors);
+  CAPTURE_RESOURCE_ERRORS = Boolean(captureResourceErrors);
+  CAPTURE_FAILED_REQUESTS = Boolean(captureFailedRequests);
+  CAPTURE_NODE_WARNINGS = Boolean(captureNodeWarnings);
+  CAPTURE_NODE_MULTIPLE_RESOLVES = Boolean(captureNodeMultipleResolves);
   setProjectRoot(
     projectRoot ||
       (isNode ? process.env.WATCHFORGE_PROJECT_ROOT || process.env.INIT_CWD : null)
@@ -467,6 +658,7 @@ export function register({
   
   // Browser: Set up full instrumentation (errors, breadcrumbs, HTTP, navigation)
   if (isBrowser) {
+    browserRegisterKey = nextBrowserRegisterKey;
     setupBrowserInstrumentation();
     replayInitPromise = initReplay({
       replaysSessionSampleRate,
@@ -491,6 +683,52 @@ export function register({
     process.on("unhandledRejection", (reason) => {
       void captureException(reason);
     });
+
+    process.on("multipleResolves", (type, promise, reason) => {
+      addBreadcrumb({
+        type: "error",
+        level: "warning",
+        category: "process.multipleResolves",
+        message: `Node.js promise multipleResolves: ${type}`,
+        data: {
+          type,
+          reason: reason?.message || String(reason || ""),
+        },
+      });
+
+      if (!CAPTURE_NODE_MULTIPLE_RESOLVES) return;
+      void captureException(
+        normalizeException(reason, `Node.js promise multipleResolves: ${type}`),
+        {
+          tags: {
+            handled: true,
+            mechanism: "process.multipleResolves",
+            type,
+          },
+        }
+      );
+    });
+
+    process.on("warning", (warning) => {
+      addBreadcrumb({
+        type: "warning",
+        level: "warning",
+        category: "process.warning",
+        message: warning?.message || String(warning),
+        data: {
+          name: warning?.name || null,
+          code: warning?.code || null,
+        },
+      });
+
+      if (!CAPTURE_NODE_WARNINGS) return;
+      void captureException(normalizeException(warning, "Node.js process warning"), {
+        tags: {
+          handled: true,
+          mechanism: "process.warning",
+        },
+      });
+    });
   }
 }
 

package/src/express.d.ts

@@ -10,3 +10,15 @@ export function expressMiddleware(): (
   res: any,
   next: (error?: unknown) => void
 ) => void;
+
+export type ExpressHandler = (
+  req: any,
+  res: any,
+  next?: (error?: unknown) => void
+) => unknown | Promise<unknown>;
+
+export function withWatchForgeExpressHandler<T extends ExpressHandler>(
+  handler: T
+): T;
+
+export const wrapExpressHandler: typeof withWatchForgeExpressHandler;

package/src/express.js

@@ -87,6 +87,75 @@ export function expressMiddleware() {
   };
 }
 
+export function withWatchForgeExpressHandler(handler) {
+  return async function watchForgeExpressHandler(req, res, next) {
+    try {
+      return await handler(req, res, next);
+    } catch (error) {
+      await captureException(error, {
+        user: getUserContext(req),
+        request: getExpressRequestContext(req),
+        tags: {
+          framework: "express",
+          route: req.route?.path || req.path,
+          runtime: "server",
+        },
+        extra: {
+          params: req.params || {},
+        },
+        contexts: {
+          express: {
+            route: req.route?.path || req.path,
+            base_url: req.baseUrl || null,
+            handler_wrapper: true,
+          },
+        },
+      });
+      if (typeof next === "function") {
+        return next(error);
+      }
+      throw error;
+    }
+  };
+}
+
+export const wrapExpressHandler = withWatchForgeExpressHandler;
+
+function getRequestIp(req) {
+  return (
+    req.ip ||
+    req.connection?.remoteAddress ||
+    req.socket?.remoteAddress ||
+    (req.connection?.socket ? req.connection.socket.remoteAddress : null) ||
+    req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+    req.headers["x-real-ip"] ||
+    null
+  );
+}
+
+function getUserContext(req) {
+  const ip = getRequestIp(req);
+  return req.user
+    ? {
+        id: String(req.user.id),
+        email: req.user.email || null,
+        username: req.user.username || null,
+        ip_address: ip,
+      }
+    : null;
+}
+
+function getExpressRequestContext(req) {
+  return {
+    url: `${req.protocol}://${req.get("host")}${req.originalUrl || req.url}`,
+    method: req.method,
+    headers: sanitizeHeaders(req.headers),
+    query: req.query || {},
+    body: req.body || {},
+    ip: getRequestIp(req),
+  };
+}
+
 function sanitizeHeaders(headers) {
   const sanitized = {};
   for (const [key, value] of Object.entries(headers)) {

package/src/index.d.ts

@@ -10,6 +10,10 @@ export interface WatchForgeRegisterOptions {
   ignoreClass?: string;
   maskTextClass?: string;
   captureConsoleErrors?: boolean;
+  captureResourceErrors?: boolean;
+  captureFailedRequests?: boolean;
+  captureNodeWarnings?: boolean;
+  captureNodeMultipleResolves?: boolean;
   projectRoot?: string | null;
 }
 
@@ -41,3 +45,10 @@ export {
   Transaction,
   Span,
 } from "./tracing.js";
+
+export {
+  expressMiddleware,
+  expressRequestMiddleware,
+  withWatchForgeExpressHandler,
+  wrapExpressHandler,
+} from "./express.js";

package/src/index.js

@@ -13,4 +13,9 @@ export { init } from "./client.js";
 export { startTransaction, getCurrentTransaction, finishTransaction, Transaction, Span } from "./tracing.js";
 
 // Export framework integrations
-export { expressMiddleware, expressRequestMiddleware } from "./express.js";
+export {
+  expressMiddleware,
+  expressRequestMiddleware,
+  withWatchForgeExpressHandler,
+  wrapExpressHandler,
+} from "./express.js";

package/src/next-server.d.ts

@@ -45,3 +45,18 @@ export type NextRouteHandler<TContext = unknown> = (
 export function withWatchForgeRouteHandler<TContext = unknown>(
   handler: NextRouteHandler<TContext>
 ): NextRouteHandler<TContext>;
+
+export function withWatchForgeServerAction<TArgs extends unknown[], TResult>(
+  action: (...args: TArgs) => TResult | Promise<TResult>,
+  actionName?: string
+): (...args: TArgs) => Promise<TResult>;
+
+export type NextApiHandler = (req: any, res: any) => unknown | Promise<unknown>;
+
+export function withWatchForgeApiHandler<T extends NextApiHandler>(
+  handler: T
+): T;
+
+export const wrapRouteHandler: typeof withWatchForgeRouteHandler;
+export const wrapServerAction: typeof withWatchForgeServerAction;
+export const wrapApiHandler: typeof withWatchForgeApiHandler;

package/src/next-server.js

@@ -116,3 +116,63 @@ export function withWatchForgeRouteHandler(handler) {
     }
   };
 }
+
+export function withWatchForgeServerAction(action, actionName = action?.name || "serverAction") {
+  return async function watchForgeServerAction(...args) {
+    try {
+      return await action(...args);
+    } catch (error) {
+      await captureException(error, {
+        tags: {
+          framework: "nextjs",
+          runtime: "server",
+          mechanism: "server-action",
+          action: actionName,
+        },
+        contexts: {
+          nextjs: {
+            router: "app",
+            server_action: true,
+            action: actionName,
+          },
+        },
+      });
+      throw error;
+    }
+  };
+}
+
+export function withWatchForgeApiHandler(handler) {
+  return async function watchForgeApiHandler(req, res) {
+    try {
+      return await handler(req, res);
+    } catch (error) {
+      await captureException(error, {
+        request: {
+          url: req?.url || "",
+          method: req?.method || "",
+          headers: sanitizeRequestHeaders(req?.headers),
+          query: req?.query || {},
+          body: req?.body,
+        },
+        tags: {
+          framework: "nextjs",
+          runtime: "server",
+          router: "pages",
+          route_type: "api",
+        },
+        contexts: {
+          nextjs: {
+            router: "pages",
+            api_route: true,
+          },
+        },
+      });
+      throw error;
+    }
+  };
+}
+
+export const wrapRouteHandler = withWatchForgeRouteHandler;
+export const wrapServerAction = withWatchForgeServerAction;
+export const wrapApiHandler = withWatchForgeApiHandler;

package/src/next.d.ts

@@ -4,6 +4,7 @@ import type { WatchForgeRegisterOptions } from "./index.js";
 export interface WatchForgeProviderProps {
   options: WatchForgeRegisterOptions;
   children?: ReactNode;
+  fallback?: ReactNode;
 }
 
 export function WatchForgeProvider(

package/src/next.js

@@ -2,11 +2,14 @@
 
 import React, { useEffect } from "react";
 import { register } from "./client.js";
+import { ErrorBoundary } from "./react.js";
 
-export function WatchForgeProvider({ options, children = null }) {
+export function WatchForgeProvider({ options, children = null, fallback = null }) {
   useEffect(() => {
     register(options);
   }, [options]);
 
-  return React.createElement(React.Fragment, null, children);
+  if (!children) return null;
+
+  return React.createElement(ErrorBoundary, { fallback }, children);
 }

package/src/react.d.ts

@@ -1,4 +1,4 @@
-import type { Component, ReactNode } from "react";
+import type { Component, ComponentType, ReactNode } from "react";
 
 export interface ErrorBoundaryProps {
   children?: ReactNode;
@@ -6,3 +6,10 @@ export interface ErrorBoundaryProps {
 }
 
 export class ErrorBoundary extends Component<ErrorBoundaryProps> {}
+
+export function withWatchForgeErrorBoundary<P>(
+  component: ComponentType<P>,
+  options?: Pick<ErrorBoundaryProps, "fallback">
+): ComponentType<P>;
+
+export const withErrorBoundary: typeof withWatchForgeErrorBoundary;

package/src/react.js

@@ -50,3 +50,21 @@ export class ErrorBoundary extends React.Component {
     return this.props.children;
   }
 }
+
+export function withWatchForgeErrorBoundary(Component, options = {}) {
+  const Wrapped = function WatchForgeErrorBoundaryWrapper(props) {
+    return React.createElement(
+      ErrorBoundary,
+      { fallback: options.fallback },
+      React.createElement(Component, props)
+    );
+  };
+
+  Wrapped.displayName = `withWatchForgeErrorBoundary(${
+    Component.displayName || Component.name || "Component"
+  })`;
+
+  return Wrapped;
+}
+
+export const withErrorBoundary = withWatchForgeErrorBoundary;