@watchforge/browser 0.1.0 → 0.1.1

package/README.md

@@ -1,142 +1,62 @@
-# WatchForge JavaScript SDK
+# WatchForge JavaScript SDK (`@watchforge/browser`)
 
-Official JavaScript SDK for WatchForge error tracking and monitoring.
+Browser and Node SDK for WatchForge. **One call to `register()`** turns on automatic error reporting—no manual `try/catch` required for typical crashes.
 
-## Installation
+## What this package does *not* require
 
-### Option 1: Copy SDK files directly
+- **No Material UI (MUI)** and no other UI library. If `npm install` fails with errors about `@mui/material` or `@mui/lab`, that conflict comes from **your app’s existing dependencies**, not from WatchForge. Fix or align MUI versions in your project, or install with:
 
-Copy the `src/` folder into your project and import:
+  ```bash
+  npm install @watchforge/browser --legacy-peer-deps
+  ```
 
-```javascript
-import { register, captureException, captureMessage } from './path/to/sdk/index.js';
-```
+- **React is optional.** It is only needed if you use the React `ErrorBoundary` export from `@watchforge/browser/react`. Plain JavaScript, Vue, Angular, etc. can use the main entry without installing React.
 
-### Option 2: Install via npm (when published)
+## Installation
 
 ```bash
 npm install @watchforge/browser
 ```
 
-## Quick Start
-
-```javascript
-import { register, captureException, captureMessage, flush } from '@watchforge/browser';
-
-// Initialize the SDK
-register({
-  endpoint: "https://PUBLIC_KEY@localhost:8001/PROJECT_ID",
-  app_env: "development",
-  debug: true  // Set to false in production
-});
-
-// Capture an exception
-try {
-  // your code
-} catch (error) {
-  captureException(error);
-}
-
-// Capture a message
-captureMessage("Something happened", "info");
-
-// Manually flush events (optional - auto-flushes after 5s or 10 events)
-flush();
-```
-
-## API Reference
+## Quick start (all most apps need)
 
-### `register(options)`
+Call **`register()` once** as early as possible (e.g. app entry / main bundle), with your **DSN** from the WatchForge project settings.
 
-Initialize the WatchForge SDK.
-
-**Parameters:**
-- `endpoint` (string, required): Your WatchForge endpoint URL
-- `app_env` (string, optional): Application environment (default: "production")
-- `debug` (boolean, optional): Enable debug logging (default: false)
-
-**Example:**
 ```javascript
+import { register } from '@watchforge/browser';
+
 register({
-  endpoint: "https://abc123@watchforge.io/project-uuid",
-  app_env: "production",
-  debug: false
+  dsn: 'https://PUBLIC_KEY@your-host/PROJECT_ID',
+  app_env: 'production',  // e.g. development | staging | production
+  debug: false,           // true while integrating locally
 });
 ```
 
-### `captureException(error)`
-
-Capture an exception/error.
-
-**Parameters:**
-- `error` (Error): The error object to capture
-
-**Example:**
-```javascript
-try {
-  riskyOperation();
-} catch (error) {
-  captureException(error);
-}
-```
-
-### `captureMessage(message, level)`
-
-Capture a custom message.
-
-**Parameters:**
-- `message` (string): The message to capture
-- `level` (string, optional): Message level - "info", "warning", or "error" (default: "info")
-
-**Example:**
-```javascript
-captureMessage("User logged in", "info");
-captureMessage("Rate limit approaching", "warning");
-captureMessage("Critical system failure", "error");
-```
-
-### `flush()`
-
-Manually flush all buffered events to the backend immediately.
+That’s enough for **automatic** reporting in the browser and Node:
 
-**Example:**
-```javascript
-captureMessage("Important event");
-flush();  // Send immediately
-```
+| Where | What gets reported automatically |
+|--------|----------------------------------|
+| **Browser** | Uncaught errors (`window.onerror`), unhandled promise rejections, plus breadcrumbs (console, clicks, navigation) to give context around failures |
+| **Node** | `uncaughtException` and `unhandledRejection` |
 
-## Automatic Error Capture
+You do **not** need to call `captureException` in normal flows—those global handlers already send errors to WatchForge.
 
-The SDK automatically captures:
-- **Unhandled errors** via `window.onerror`
-- **Unhandled promise rejections** via `window.onunhandledrejection`
+## How events reach WatchForge
 
-No additional setup required!
+After `register()`, the SDK buffers events and sends them to your ingestion endpoint derived from the DSN. Failures are grouped and shown in the WatchForge UI like other SDKs.
 
-## Event Buffering
+## Optional: copy files instead of npm
 
-Events are automatically buffered and sent:
-- When 10 events accumulate, OR
-- After 5 seconds of inactivity
+You can copy the `src/` folder into your repo and import from your path (same `register` API).
 
-Use `flush()` to send immediately.
+## Advanced (optional APIs)
 
-## Backward Compatibility
+For manual reporting (handled errors, custom messages, immediate flush), see **`CONFIGURATION_GUIDE.md`** in this repository. The main package also exports `captureException`, `captureMessage`, and `flush` if you need them—**they are not required** for automatic error capture.
 
-The old `init()` function is still available but deprecated:
-
-```javascript
-// Old (deprecated)
-init({ dsn: "...", environment: "production" });
-
-// New (recommended)
-register({ endpoint: "...", app_env: "production" });
-```
+### Deprecated
 
-## Browser Support
+`init()` is deprecated; use `register()` with a `dsn` field.
 
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
+## Browser support
 
-Requires ES6 modules support.
+Modern browsers with ES modules. For **React** error boundaries, import from `@watchforge/browser/react`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "./src/index.js",
   "description": "WatchForge JavaScript SDK for Node.js, Express.js, and React",
   "license": "MIT",
@@ -32,6 +32,11 @@
   "peerDependencies": {
     "react": ">=16.8.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "browser": {
     "http": false,
     "https": false,