@watchforge/browser 0.1.3 → 0.1.4

package/CONFIGURATION_GUIDE.md

@@ -68,6 +68,36 @@ After installation, use it the same way:
 import { register, ErrorBoundary } from '@watchforge/browser';
 ```
 
+### Next.js Wizard Setup
+
+From your Next.js project root:
+
+```bash
+npx @watchforge/browser -i nextjs --dsn "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID" --app-env production
+```
+
+With error-triggered Session Replay:
+
+```bash
+npx @watchforge/browser -i nextjs \
+  --dsn "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID" \
+  --app-env production \
+  --replays-on-error 1
+```
+
+The wizard:
+
+1. Installs `@watchforge/browser`
+2. Creates `watchforge.config.ts`
+3. Creates `app/watchforge-init.tsx` (or `src/app/watchforge-init.tsx`)
+4. Patches `app/layout.tsx` to render `<WatchForgeInit />`
+
+If you only want file generation and no package install:
+
+```bash
+npx @watchforge/browser -i nextjs --dsn "..." --skip-install
+```
+
 ## Quick Testing
 
 ### Prerequisites
@@ -710,7 +740,11 @@ try {
 ```javascript
 // server.js
 const express = require('express');
-const { register, expressMiddleware } = require('@watchforge/browser');
+const {
+  register,
+  expressRequestMiddleware,
+  expressMiddleware,
+} = require('@watchforge/browser');
 
 const app = express();
 
@@ -719,6 +753,11 @@ register({
   app_env: process.env.NODE_ENV,
 });
 
+app.use(express.json());
+app.use(expressRequestMiddleware());
+
+// routes here
+
 // Add error handler (must be last middleware)
 app.use(expressMiddleware());
 
@@ -735,6 +774,11 @@ import App from './App';
 register({
   dsn: process.env.REACT_APP_WATCHFORGE_DSN,
   app_env: process.env.NODE_ENV,
+  // Optional: upload the last 60s of masked browser replay events when an error occurs.
+  replaysOnErrorSampleRate: 1.0,
+  // Optional: continuously sample full sessions. Keep 0 in production unless you need it.
+  replaysSessionSampleRate: 0,
+  maskAllInputs: true,
 });
 
 ReactDOM.render(
@@ -745,6 +789,95 @@ ReactDOM.render(
 );
 ```
 
+## Stack Trace Source Context
+
+The SDK enriches stack frames with Python-style source context when possible:
+
+| Field | Description |
+|-------|-------------|
+| `context_line` | The exact line where the error occurred |
+| `pre_context` | Up to 5 lines before the error |
+| `post_context` | Up to 5 lines after the error |
+
+### Node.js / Express
+
+For local project files, the SDK reads source from disk and attaches context lines automatically. No extra configuration is required.
+
+### Browser (development)
+
+In dev builds (Next.js, Vite, etc.), the SDK attempts to fetch same-origin script URLs from the stack trace and slice source lines around the reported line number.
+
+Works when stack frames point to readable URLs such as:
+
+```txt
+http://localhost:3000/_next/static/chunks/...
+http://localhost:3000/src/App.tsx
+```
+
+### Browser (production / minified bundles)
+
+Production bundles often report locations like:
+
+```txt
+https://your-app.com/_next/static/chunks/app-abc123.js:1:98432
+```
+
+The SDK still sends filename, line, and column, but **cannot** show original TypeScript/JSX source without **source maps**.
+
+**Current status:** source map upload and symbolication are not yet supported (planned for a future release).
+
+**Workarounds today:**
+
+1. Test with `npm run dev` / unminified builds to see source lines in WatchForge.
+2. Use `release` in `register()` so issues are grouped by deploy version.
+3. Rely on breadcrumbs and the Browser Event Summary in the dashboard to understand user actions before the error.
+
+When source map support ships, you will upload maps during deploy and WatchForge will resolve minified frames back to original files.
+
+## Session Replay
+
+The browser SDK can record a Sentry-style DOM replay using `rrweb`. Replays are **not videos**; they are masked DOM snapshots and incremental browser events that WatchForge can play back in the Issue Detail page.
+
+Enable replay capture when registering the SDK:
+
+```javascript
+register({
+  dsn: "https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID",
+  app_env: "production",
+  replaysOnErrorSampleRate: 1.0,
+  replaysSessionSampleRate: 0,
+  maskAllInputs: true,
+});
+```
+
+Replay behavior:
+
+- `replaysOnErrorSampleRate`: records in buffer mode and uploads the last 60 seconds when an error is captured.
+- `replaysSessionSampleRate`: continuously samples full browser sessions.
+- Text/input privacy is handled in the browser before upload.
+- Password, email, tel and text inputs are masked when `maskAllInputs` is true.
+- Elements with `.rr-block` are blocked.
+- Elements with `.rr-ignore` ignore input events.
+- Elements with `.rr-mask` mask text.
+
+When an error is captured, the SDK attaches:
+
+```json
+{
+  "replay_id": "...",
+  "session_id": "...",
+  "contexts": {
+    "replay": {
+      "replay_id": "...",
+      "session_id": "...",
+      "sampled": true
+    }
+  }
+}
+```
+
+The dashboard shows the linked replay in the Issue Detail **Session Replay** tab.
+
 ## Test Scripts
 
 Test scripts are included in the SDK directory:

package/README.md

@@ -18,6 +18,25 @@ Browser and Node SDK for WatchForge. **One call to `register()`** turns on autom
 npm install @watchforge/browser
 ```
 
+## Next.js one-line setup
+
+For Next.js apps, run the setup wizard from your app root:
+
+```bash
+npx @watchforge/browser -i nextjs --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" --app-env production
+```
+
+With Session Replay on errors:
+
+```bash
+npx @watchforge/browser -i nextjs \
+  --dsn "https://PUBLIC_KEY@your-host/PROJECT_ID" \
+  --app-env production \
+  --replays-on-error 1
+```
+
+The wizard installs `@watchforge/browser`, writes `watchforge.config.ts`, creates a client init component, and patches `app/layout.tsx` or `pages/_app.tsx`.
+
 ## Quick start (all most apps need)
 
 Call **`register()` once** as early as possible (e.g. app entry / main bundle), with your **DSN** from the WatchForge project settings.

package/bin/watchforge.js

@@ -0,0 +1,258 @@
+#!/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 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"),
+  ];
+  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
+    ? "pnpm add @watchforge/browser"
+    : hasYarn
+      ? "yarn add @watchforge/browser"
+      : hasBun
+        ? "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 isSrcApp = appDir.endsWith(path.join("src", "app"));
+  const configImport = isSrcApp ? "../../watchforge.config" : "../watchforge.config";
+  const initPath = path.join(appDir, "watchforge-init.tsx");
+
+  const initContent = `"use client";
+
+import { useEffect } from "react";
+import { register } from "@watchforge/browser";
+import { watchforgeConfig } from "${configImport}";
+
+export default function WatchForgeInit() {
+  useEffect(() => {
+    register(watchforgeConfig);
+  }, []);
+
+  return null;
+}
+`;
+
+  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,6 +1,6 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "main": "./src/index.js",
   "description": "WatchForge JavaScript SDK for Node.js, Express.js, and React",
   "license": "MIT",
@@ -22,12 +22,19 @@
     "./express": "./src/express.js",
     "./react": "./src/react.js"
   },
+  "bin": {
+    "watchforge": "bin/watchforge.js"
+  },
   "files": [
+    "bin/**/*.js",
     "src/**/*.js",
     "README.md",
     "CONFIGURATION_GUIDE.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "peerDependencies": {
     "react": ">=16.8.0"
@@ -43,7 +50,8 @@
     "url": false
   },
   "dependencies": {
-    "express": "^5.2.1"
+    "express": "^5.2.1",
+    "rrweb": "^2.0.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/replay.js

@@ -0,0 +1,128 @@
+import { sendReplay } from "./transport.js";
+
+const isBrowser = typeof window !== "undefined";
+const MAX_BUFFER_MS = 60 * 1000;
+const MAX_EVENTS = 500;
+
+let options = {
+  replaysSessionSampleRate: 0,
+  replaysOnErrorSampleRate: 0,
+  maskAllInputs: true,
+  blockClass: "rr-block",
+  ignoreClass: "rr-ignore",
+  maskTextClass: "rr-mask",
+};
+let stopRecording = null;
+let events = [];
+let replayId = null;
+let sessionId = null;
+let startedAt = null;
+let sessionSampled = false;
+
+function uuid() {
+  if (isBrowser && crypto?.randomUUID) return crypto.randomUUID();
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+function shouldSample(rate) {
+  const n = Number(rate || 0);
+  if (n <= 0) return false;
+  if (n >= 1) return true;
+  return Math.random() < n;
+}
+
+function trimBuffer(now = Date.now()) {
+  events = events.filter((event) => now - event.timestamp <= MAX_BUFFER_MS);
+  if (events.length > MAX_EVENTS) {
+    events = events.slice(-MAX_EVENTS);
+  }
+}
+
+export async function initReplay(config = {}) {
+  if (!isBrowser) return;
+
+  options = {
+    ...options,
+    ...config,
+  };
+
+  sessionSampled = shouldSample(options.replaysSessionSampleRate);
+  const shouldRecord = sessionSampled || Number(options.replaysOnErrorSampleRate || 0) > 0;
+
+  if (!shouldRecord || stopRecording) return;
+
+  replayId = replayId || uuid();
+  sessionId = sessionId || uuid();
+  startedAt = new Date().toISOString();
+
+  try {
+    const { record } = await import("rrweb");
+    stopRecording = record({
+      emit(event) {
+        events.push(event);
+        trimBuffer(event.timestamp || Date.now());
+      },
+      maskAllInputs: options.maskAllInputs,
+      blockClass: options.blockClass,
+      ignoreClass: options.ignoreClass,
+      maskTextClass: options.maskTextClass,
+      maskInputOptions: {
+        password: true,
+        email: true,
+        tel: true,
+        text: Boolean(options.maskAllInputs),
+      },
+    });
+  } catch (error) {
+    if (options.debug) {
+      console.warn("WatchForge SDK: failed to start replay recording", error);
+    }
+  }
+}
+
+export function getReplayContext() {
+  if (!isBrowser || !replayId || !sessionId) return null;
+  return {
+    replay_id: replayId,
+    session_id: sessionId,
+    sampled: Boolean(stopRecording),
+  };
+}
+
+export function flushReplayForEvent(dsn, eventId) {
+  if (!isBrowser || !dsn || !replayId || !sessionId || events.length === 0) {
+    return null;
+  }
+
+  if (!sessionSampled && !shouldSample(options.replaysOnErrorSampleRate)) {
+    return null;
+  }
+
+  trimBuffer();
+
+  const payload = {
+    replay_id: replayId,
+    session_id: sessionId,
+    event_id: eventId,
+    started_at: startedAt,
+    finished_at: new Date().toISOString(),
+    url: window.location.href,
+    user_agent: navigator.userAgent,
+    events,
+    sdk: {
+      name: "@watchforge/browser",
+      version: "0.1.3",
+    },
+  };
+
+  sendReplay(dsn, payload);
+  return {
+    replay_id: replayId,
+    session_id: sessionId,
+    event_count: events.length,
+  };
+}

package/src/stacktrace.js

@@ -25,7 +25,7 @@ function parseStackLine(line) {
   const trimmed = line.trim();
   if (!trimmed.startsWith("at ")) return null;
 
-  const withFn = trimmed.match(/^at\s+(.*?)\s+\((.*?):(\d+):(\d+)\)$/);
+  const withFn = trimmed.match(/^at\s+(?:async\s+)?(.*?)\s+\((.*?):(\d+):(\d+)\)$/);
   if (withFn) {
     return {
       function: withFn[1] || "<anonymous>",
@@ -35,7 +35,7 @@ function parseStackLine(line) {
     };
   }
 
-  const withoutFn = trimmed.match(/^at\s+(.*?):(\d+):(\d+)$/);
+  const withoutFn = trimmed.match(/^at\s+(?:async\s+)?(.*?):(\d+):(\d+)$/);
   if (withoutFn) {
     return {
       function: "<anonymous>",
@@ -111,14 +111,16 @@ function applySourceContext(frame, sourceLines, lineno) {
 }
 
 let nodeModulesPromise = null;
+const importNodeBuiltin = (specifier) =>
+  new Function("specifier", "return import(specifier)")(specifier);
 
 function getNodeModules() {
   if (!isNode) return Promise.resolve(null);
   if (!nodeModulesPromise) {
     nodeModulesPromise = (async () => {
       try {
-        const { createRequire } = await import("module");
-        const { fileURLToPath } = await import("url");
+        const { createRequire } = await importNodeBuiltin("module");
+        const { fileURLToPath } = await importNodeBuiltin("url");
         const req = createRequire(fileURLToPath(import.meta.url));
         return {
           fs: req("fs"),

package/src/transport.js

@@ -2,9 +2,12 @@
 const isBrowser = typeof window !== 'undefined';
 const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
 
-// Lazy-load Node.js require function for ES modules
+// Lazy-load Node.js require function for ES modules. Use Function-based import
+// so browser bundlers do not try to resolve Node built-ins like "module".
 let nodeRequire = null;
 let nodeRequirePromise = null;
+const importNodeBuiltin = (specifier) =>
+  new Function("specifier", "return import(specifier)")(specifier);
 
 function getNodeRequire() {
   if (!isNode) return Promise.resolve(null);
@@ -14,8 +17,8 @@ function getNodeRequire() {
   if (!nodeRequirePromise) {
     nodeRequirePromise = (async () => {
       try {
-        const { createRequire } = await import('module');
-        const { fileURLToPath } = await import('url');
+        const { createRequire } = await importNodeBuiltin('module');
+        const { fileURLToPath } = await importNodeBuiltin('url');
         nodeRequire = createRequire(fileURLToPath(import.meta.url));
         return nodeRequire;
       } catch (e) {
@@ -47,6 +50,7 @@ function parseDsn(dsn) {
         host,
         projectId,
         apiUrl: `${finalScheme}://${host}/api/ingestion/events/`,
+        replayUrl: `${finalScheme}://${host}/api/ingestion/replays/`,
       };
     }
   } catch (e) {
@@ -79,6 +83,20 @@ function getApiUrl(dsn) {
   return isBrowser ? "/api/ingestion/events/" : "http://127.0.0.1:8001/api/ingestion/events/";
 }
 
+function getReplayUrl(dsn) {
+  const apiUrl = getApiUrl(dsn);
+  if (apiUrl.endsWith("/events/")) {
+    return apiUrl.replace(/\/events\/$/, "/replays/");
+  }
+
+  const parsed = parseDsn(dsn);
+  if (parsed) {
+    return parsed.replayUrl;
+  }
+
+  return isBrowser ? "/api/ingestion/replays/" : "http://127.0.0.1:8001/api/ingestion/replays/";
+}
+
 export function sendEvent(dsn, payload) {
   const apiUrl = getApiUrl(dsn);
   
@@ -189,3 +207,27 @@ export function sendEvent(dsn, payload) {
     });
   }
 }
+
+export function sendReplay(dsn, payload) {
+  const apiUrl = getReplayUrl(dsn);
+
+  if (isBrowser) {
+    fetch(apiUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `DSN ${dsn}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+      keepalive: false,
+    }).catch((error) => {
+      console.error("WatchForge SDK - Failed to send replay:", error);
+    });
+    return;
+  }
+
+  if (isNode) {
+    // Replays are browser-only, but keep this no-op explicit for framework code paths.
+    return;
+  }
+}