@watchforge/browser 0.1.3 → 0.1.5

package/bin/watchforge.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const HELP = `
+WatchForge setup wizard
+
+Usage:
+  npx @watchforge/browser -i nextjs --dsn <dsn> [options]
+  npx @watchforge/browser init nextjs --dsn <dsn> [options]
+
+Options:
+  -i, --integration <name>        Framework integration. Currently: nextjs
+  --dsn <dsn>                    WatchForge DSN
+  --app-env <env>                App environment (default: production)
+  --debug                        Enable SDK debug logging
+  --replays-on-error <rate>      Upload replay when errors happen (default: 0)
+  --replays-session <rate>       Continuously sample sessions (default: 0)
+  --skip-install                 Do not install @watchforge/browser
+  -h, --help                     Show help
+
+Example:
+  npx @watchforge/browser -i nextjs --dsn "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID" --app-env development --replays-on-error 1
+`;
+
+function parseArgs(argv) {
+  const args = {
+    integration: null,
+    dsn: null,
+    appEnv: "production",
+    debug: false,
+    replaysOnError: "0",
+    replaysSession: "0",
+    skipInstall: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === "-h" || arg === "--help") args.help = true;
+    else if (arg === "-i" || arg === "--integration") {
+      args.integration = next;
+      i++;
+    } else if (arg === "init" || arg === "setup") {
+      args.integration = argv[i + 1] || args.integration;
+      i++;
+    } else if (arg === "--dsn") {
+      args.dsn = next;
+      i++;
+    } else if (arg === "--app-env" || arg === "--environment") {
+      args.appEnv = next || args.appEnv;
+      i++;
+    } else if (arg === "--debug") {
+      args.debug = true;
+    } else if (arg === "--replays-on-error") {
+      args.replaysOnError = next || "0";
+      i++;
+    } else if (arg === "--replays-session") {
+      args.replaysSession = next || "0";
+      i++;
+    } else if (arg === "--skip-install") {
+      args.skipInstall = true;
+    }
+  }
+
+  return args;
+}
+
+function log(message) {
+  console.log(`WatchForge: ${message}`);
+}
+
+function fail(message) {
+  console.error(`WatchForge setup failed: ${message}`);
+  process.exit(1);
+}
+
+function fileExists(filePath) {
+  return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+}
+
+function commandExists(command) {
+  try {
+    execSync(`command -v ${command}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findNextLayout(cwd) {
+  const candidates = [
+    path.join(cwd, "src", "app", "layout.tsx"),
+    path.join(cwd, "src", "app", "layout.jsx"),
+    path.join(cwd, "app", "layout.tsx"),
+    path.join(cwd, "app", "layout.jsx"),
+  ];
+
+  for (const appRoot of [path.join(cwd, "src", "app"), path.join(cwd, "app")]) {
+    if (!fs.existsSync(appRoot) || !fs.statSync(appRoot).isDirectory()) continue;
+    const entries = fs.readdirSync(appRoot, { withFileTypes: true }).sort((a, b) => {
+      const score = (name) => {
+        if (name.includes("frontend") || name.includes("site")) return -1;
+        if (name.includes("payload") || name.includes("admin")) return 1;
+        return 0;
+      };
+      return score(a.name) - score(b.name) || a.name.localeCompare(b.name);
+    });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      candidates.push(path.join(appRoot, entry.name, "layout.tsx"));
+      candidates.push(path.join(appRoot, entry.name, "layout.jsx"));
+    }
+  }
+
+  return candidates.find(fileExists) || null;
+}
+
+function findPagesApp(cwd) {
+  const candidates = [
+    path.join(cwd, "src", "pages", "_app.tsx"),
+    path.join(cwd, "src", "pages", "_app.jsx"),
+    path.join(cwd, "pages", "_app.tsx"),
+    path.join(cwd, "pages", "_app.jsx"),
+  ];
+  return candidates.find(fileExists) || null;
+}
+
+function writeIfChanged(filePath, content) {
+  if (fileExists(filePath) && fs.readFileSync(filePath, "utf8") === content) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+function createConfig(cwd, args) {
+  const configPath = path.join(cwd, "watchforge.config.ts");
+  const content = `export const watchforgeConfig = {
+  dsn: ${JSON.stringify(args.dsn)},
+  app_env: ${JSON.stringify(args.appEnv)},
+  debug: ${args.debug ? "true" : "false"},
+  replaysOnErrorSampleRate: ${Number(args.replaysOnError)},
+  replaysSessionSampleRate: ${Number(args.replaysSession)},
+  maskAllInputs: true,
+};
+`;
+  writeIfChanged(configPath, content);
+  log(`wrote ${path.relative(cwd, configPath)}`);
+}
+
+function installPackage(cwd, skipInstall) {
+  if (skipInstall) {
+    log("skipped npm install");
+    return;
+  }
+
+  const hasPnpm = fileExists(path.join(cwd, "pnpm-lock.yaml"));
+  const hasYarn = fileExists(path.join(cwd, "yarn.lock"));
+  const hasBun = fileExists(path.join(cwd, "bun.lockb"));
+
+  const command = hasPnpm && commandExists("pnpm")
+    ? "pnpm add @watchforge/browser"
+    : hasYarn && commandExists("yarn")
+      ? "yarn add @watchforge/browser"
+      : hasBun && commandExists("bun")
+        ? "bun add @watchforge/browser"
+        : "npm install @watchforge/browser";
+
+  log(`installing package: ${command}`);
+  execSync(command, { cwd, stdio: "inherit" });
+}
+
+function patchAppRouter(cwd, layoutPath) {
+  const appDir = path.dirname(layoutPath);
+  const configPath = path.join(cwd, "watchforge.config.ts");
+  let configImport = path.relative(appDir, configPath).replace(/\\/g, "/");
+  configImport = configImport.replace(/\.ts$/, "");
+  if (!configImport.startsWith(".")) {
+    configImport = `./${configImport}`;
+  }
+  const initPath = path.join(appDir, "watchforge-init.tsx");
+
+  const initContent = `"use client";
+
+import { WatchForgeProvider } from "@watchforge/browser/next";
+import { watchforgeConfig } from "${configImport}";
+
+export default function WatchForgeInit() {
+  return <WatchForgeProvider options={watchforgeConfig} />;
+}
+`;
+
+  writeIfChanged(initPath, initContent);
+  log(`wrote ${path.relative(cwd, initPath)}`);
+
+  let layout = fs.readFileSync(layoutPath, "utf8");
+  if (!layout.includes("WatchForgeInit")) {
+    layout = `import WatchForgeInit from "./watchforge-init";\n${layout}`;
+  }
+
+  if (!layout.includes("<WatchForgeInit />")) {
+    layout = layout.replace(/<body([^>]*)>/, "<body$1>\n        <WatchForgeInit />\n        ");
+  }
+
+  fs.writeFileSync(layoutPath, layout);
+  log(`patched ${path.relative(cwd, layoutPath)}`);
+}
+
+function patchPagesRouter(cwd, appPath) {
+  const pagesDir = path.dirname(appPath);
+  const isSrcPages = pagesDir.endsWith(path.join("src", "pages"));
+  const configImport = isSrcPages ? "../../watchforge.config" : "../watchforge.config";
+  const content = fs.readFileSync(appPath, "utf8");
+
+  if (content.includes("register(watchforgeConfig)")) {
+    log(`${path.relative(cwd, appPath)} already contains WatchForge setup`);
+    return;
+  }
+
+  const patched = `import { useEffect } from "react";
+import { register } from "@watchforge/browser";
+import { watchforgeConfig } from "${configImport}";
+
+${content.replace(
+  /function\s+App\s*\(([^)]*)\)\s*{/,
+  "function App($1) {\n  useEffect(() => {\n    register(watchforgeConfig);\n  }, []);"
+)}`;
+
+  fs.writeFileSync(appPath, patched);
+  log(`patched ${path.relative(cwd, appPath)}`);
+}
+
+function initNextjs(args) {
+  const cwd = process.cwd();
+  if (!fileExists(path.join(cwd, "package.json"))) {
+    fail("run this command from the root of your Next.js project");
+  }
+
+  createConfig(cwd, args);
+  installPackage(cwd, args.skipInstall);
+
+  const layoutPath = findNextLayout(cwd);
+  if (layoutPath) {
+    patchAppRouter(cwd, layoutPath);
+    return;
+  }
+
+  const appPath = findPagesApp(cwd);
+  if (appPath) {
+    patchPagesRouter(cwd, appPath);
+    return;
+  }
+
+  fail("could not find app/layout.tsx or pages/_app.tsx");
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (!args.integration) {
+  fail("missing integration. Use: -i nextjs");
+}
+
+if (args.integration !== "nextjs") {
+  fail(`unsupported integration "${args.integration}". Currently supported: nextjs`);
+}
+
+if (!args.dsn) {
+  fail("missing --dsn");
+}
+
+initNextjs(args);
+log("setup complete");

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "main": "./src/index.js",
-  "description": "WatchForge JavaScript SDK for Node.js, Express.js, and React",
+  "types": "./src/index.d.ts",
+  "description": "WatchForge JavaScript SDK for browser JavaScript, Next.js, React, Node.js, and Express.js",
   "license": "MIT",
   "keywords": [
     "watchforge",
@@ -15,24 +16,55 @@
   ],
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "browser": "./src/index.js",
       "node": "./src/index.js",
       "default": "./src/index.js"
     },
-    "./express": "./src/express.js",
-    "./react": "./src/react.js"
+    "./node": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./next": {
+      "types": "./src/next.d.ts",
+      "default": "./src/next.js"
+    },
+    "./next/server": {
+      "types": "./src/next-server.d.ts",
+      "default": "./src/next-server.js"
+    },
+    "./express": {
+      "types": "./src/express.d.ts",
+      "default": "./src/express.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "default": "./src/react.js"
+    }
+  },
+  "bin": {
+    "watchforge": "bin/watchforge.js"
   },
   "files": [
+    "bin/**/*.js",
     "src/**/*.js",
+    "src/**/*.d.ts",
     "README.md",
     "CONFIGURATION_GUIDE.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "peerDependencies": {
+    "express": ">=4.0.0",
     "react": ">=16.8.0"
   },
   "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }
@@ -43,7 +75,8 @@
     "url": false
   },
   "dependencies": {
-    "express": "^5.2.1"
+    "rrweb": "^2.0.1",
+    "source-map-js": "^1.2.1"
   },
   "devDependencies": {
     "rollup": "^4.60.0"

package/src/client.js

@@ -9,6 +9,11 @@ import {
   getPerformanceContext,
   getNodeServerContext,
 } from "./contexts.js";
+import {
+  flushReplayForEvent,
+  getReplayContext,
+  initReplay,
+} from "./replay.js";
 
 let DSN = null;
 let APP_ENV = "production";
@@ -378,6 +383,12 @@ export function register({
   app_env = "production",
   release = null,
   debug = false,
+  replaysSessionSampleRate = 0,
+  replaysOnErrorSampleRate = 0,
+  maskAllInputs = true,
+  blockClass = "rr-block",
+  ignoreClass = "rr-ignore",
+  maskTextClass = "rr-mask",
 }) {
   DSN = dsn;
   APP_ENV = app_env;
@@ -409,6 +420,15 @@ export function register({
   // Browser: Set up full instrumentation (errors, breadcrumbs, HTTP, navigation)
   if (isBrowser) {
     setupBrowserInstrumentation();
+    initReplay({
+      replaysSessionSampleRate,
+      replaysOnErrorSampleRate,
+      maskAllInputs,
+      blockClass,
+      ignoreClass,
+      maskTextClass,
+      debug,
+    });
   }
   
   // Node.js: Set up process error handlers
@@ -448,6 +468,12 @@ export async function captureException(error, context = {}) {
     sdk: getSdkMetadata(),
   };
 
+  const replay = flushReplayForEvent(DSN, event.event_id);
+  if (replay) {
+    event.replay_id = replay.replay_id;
+    event.session_id = replay.session_id;
+  }
+
   if (RELEASE) {
     event.release = RELEASE;
   }
@@ -487,6 +513,10 @@ export async function captureException(error, context = {}) {
   }
 
   event.contexts = await buildEventContexts(context);
+  const replayContext = getReplayContext();
+  if (replayContext) {
+    event.contexts.replay = replayContext;
+  }
 
   const bcs = getBreadcrumbsSnapshot();
   if (bcs.length > 0) {

package/src/express.d.ts

@@ -0,0 +1,12 @@
+export function expressRequestMiddleware(): (
+  req: any,
+  res: any,
+  next: (error?: unknown) => void
+) => void;
+
+export function expressMiddleware(): (
+  err: Error,
+  req: any,
+  res: any,
+  next: (error?: unknown) => void
+) => void;

package/src/index.d.ts

@@ -0,0 +1,41 @@
+export interface WatchForgeRegisterOptions {
+  dsn: string;
+  app_env?: string;
+  release?: string | null;
+  debug?: boolean;
+  replaysSessionSampleRate?: number;
+  replaysOnErrorSampleRate?: number;
+  maskAllInputs?: boolean;
+  blockClass?: string;
+  ignoreClass?: string;
+  maskTextClass?: string;
+}
+
+export interface WatchForgeCaptureContext {
+  user?: Record<string, unknown>;
+  request?: Record<string, unknown>;
+  tags?: Record<string, unknown>;
+  extra?: Record<string, unknown>;
+  contexts?: Record<string, unknown>;
+}
+
+export function register(options: WatchForgeRegisterOptions): void;
+export function init(options: WatchForgeRegisterOptions): void;
+export function captureException(
+  error: unknown,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+export function captureMessage(
+  message: string,
+  level?: string,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+export function addBreadcrumb(breadcrumb: Record<string, unknown>): void;
+
+export {
+  startTransaction,
+  getCurrentTransaction,
+  finishTransaction,
+  Transaction,
+  Span,
+} from "./tracing.js";

package/src/index.js

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

package/src/next-server.d.ts

@@ -0,0 +1,26 @@
+import type {
+  WatchForgeCaptureContext,
+  WatchForgeRegisterOptions,
+} from "./index.js";
+
+export function register(options: WatchForgeRegisterOptions): void;
+
+export function captureException(
+  error: unknown,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+
+export function captureMessage(
+  message: string,
+  level?: string,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+
+export type NextRouteHandler<TContext = unknown> = (
+  request: Request,
+  context: TContext
+) => Response | Promise<Response>;
+
+export function withWatchForgeRouteHandler<TContext = unknown>(
+  handler: NextRouteHandler<TContext>
+): NextRouteHandler<TContext>;

package/src/next-server.js

@@ -0,0 +1,58 @@
+import {
+  captureException,
+  captureMessage,
+  register,
+} from "./client.js";
+
+export { captureException, captureMessage, register };
+
+function sanitizeHeaders(headers) {
+  if (!headers || typeof headers.entries !== "function") return {};
+
+  const sensitive = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-csrftoken",
+  ]);
+
+  return Object.fromEntries(
+    Array.from(headers.entries()).filter(
+      ([key]) => !sensitive.has(key.toLowerCase())
+    )
+  );
+}
+
+function getRequestContext(request) {
+  if (!request) return null;
+
+  return {
+    url: request.url || "",
+    method: request.method || "",
+    headers: sanitizeHeaders(request.headers),
+  };
+}
+
+export function withWatchForgeRouteHandler(handler) {
+  return async function watchForgeRouteHandler(request, context) {
+    try {
+      return await handler(request, context);
+    } catch (error) {
+      await captureException(error, {
+        request: getRequestContext(request),
+        tags: {
+          framework: "nextjs",
+          runtime: "server",
+        },
+        contexts: {
+          nextjs: {
+            router: "app",
+            route_handler: true,
+          },
+        },
+      });
+      throw error;
+    }
+  };
+}

package/src/next.d.ts

@@ -0,0 +1,11 @@
+import type { ReactElement, ReactNode } from "react";
+import type { WatchForgeRegisterOptions } from "./index.js";
+
+export interface WatchForgeProviderProps {
+  options: WatchForgeRegisterOptions;
+  children?: ReactNode;
+}
+
+export function WatchForgeProvider(
+  props: WatchForgeProviderProps
+): ReactElement | null;

package/src/next.js

@@ -0,0 +1,12 @@
+"use client";
+
+import React, { useEffect } from "react";
+import { register } from "./client.js";
+
+export function WatchForgeProvider({ options, children = null }) {
+  useEffect(() => {
+    register(options);
+  }, [options]);
+
+  return React.createElement(React.Fragment, null, children);
+}

package/src/react.d.ts

@@ -0,0 +1,8 @@
+import type { Component, ReactNode } from "react";
+
+export interface ErrorBoundaryProps {
+  children?: ReactNode;
+  fallback?: ReactNode;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps> {}