@watchforge/browser 0.1.0

package/CONFIGURATION_GUIDE.md

@@ -0,0 +1,755 @@
+# WatchForge JavaScript SDK - Configuration Guide
+
+## Overview
+
+The WatchForge JavaScript SDK automatically captures errors and events in:
+- **Node.js** applications
+- **Express.js** web servers
+- **React** frontend applications
+
+## Installation
+
+### From npm (when published)
+
+```bash
+npm install @watchforge/browser
+# or
+yarn add @watchforge/browser
+```
+
+### From Local Directory (for development/testing)
+
+If you want to install the SDK directly from your local directory:
+
+**Option 1: Install from local path**
+```bash
+# In your project directory
+npm install /path/to/watchforge-javascript-sdk
+# or with relative path
+npm install ../watchforge-javascript-sdk
+# or
+yarn add /path/to/watchforge-javascript-sdk
+```
+
+**Option 2: Use npm link (recommended for development)**
+```bash
+# Step 1: In watchforge-javascript-sdk directory
+cd watchforge-javascript-sdk
+npm link
+
+# Step 2: In your project directory
+cd /path/to/your-project
+npm link @watchforge/browser
+```
+
+**Option 3: Install from local directory with file: protocol**
+```bash
+# In your project directory
+npm install file:../watchforge-javascript-sdk
+# or
+yarn add file:../watchforge-javascript-sdk
+```
+
+**Example:**
+```bash
+# If your project structure is:
+# /Users/shubhampatel/Documents/
+#   ├── test-example/
+#   │   ├── watchforge-javascript-sdk/
+#   │   └── my-react-app/
+
+# From my-react-app directory:
+cd my-react-app
+npm install ../watchforge-javascript-sdk
+```
+
+After installation, use it the same way:
+```javascript
+import { register, ErrorBoundary } from '@watchforge/browser';
+```
+
+## Quick Testing
+
+### Prerequisites
+
+1. **Make sure your backend is running:**
+   ```bash
+   cd watchforge-backend
+   python manage.py runserver 8001
+   ```
+
+2. **Navigate to SDK directory:**
+   ```bash
+   cd watchforge-javascript-sdk
+   ```
+
+### Test Node.js SDK
+
+```bash
+# Run the test script
+node test-node.js
+```
+
+This will:
+- ✅ Initialize the SDK
+- ✅ Capture a test exception
+- ✅ Capture exception with user context
+- ✅ Send test messages
+- ✅ Trigger unhandled exceptions/rejections (auto-captured)
+
+**Expected Output:**
+```
+✅ WatchForge SDK initialized for Node.js
+📝 Test 1: Capturing exception...
+✅ Exception captured
+...
+✅ Test complete!
+```
+
+### Test Express.js SDK
+
+```bash
+# Step 1: Install Express (first time only)
+npm install express
+
+# Step 2: Run the test server
+node test-express.js
+```
+
+**Expected Output:**
+```
+✅ WatchForge SDK initialized for Express.js
+🚀 Express server running on http://localhost:3000
+```
+
+**Step 3: Test endpoints:**
+```bash
+# Visit in browser or use curl:
+curl http://localhost:3000/ok          # Works fine
+curl http://localhost:3000/error        # Triggers error (check backend logs)
+curl http://localhost:3000/async-error # Triggers async error
+```
+
+### Test React SDK
+
+**Note:** `test-react.html` is a demonstration file. In a real React app:
+
+1. **Install the SDK:**
+   ```bash
+   npm install @watchforge/browser
+   ```
+
+2. **Use in your React app:**
+   ```javascript
+   import { register, ErrorBoundary } from '@watchforge/browser';
+   
+   register({
+     dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+     app_env: "production",
+   });
+   
+   // Wrap your app
+   <ErrorBoundary>
+     <App />
+   </ErrorBoundary>
+   ```
+
+See the React setup section below for complete examples.
+
+## Quick Start
+
+### 1. Node.js Application
+
+```javascript
+// app.js
+const { register, captureException, captureMessage } = require('@watchforge/browser');
+
+// Initialize SDK
+// API URL is automatically derived from DSN host
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+
+// Your application code
+try {
+  // some code that might fail
+} catch (error) {
+  captureException(error); // ✅ Automatically sent to backend
+}
+
+// Log messages
+captureMessage("User logged in", "info");
+```
+
+### 2. Express.js Application
+
+```javascript
+// server.js
+const express = require('express');
+const { register, expressMiddleware } = require('@watchforge/browser');
+
+const app = express();
+
+// Initialize SDK
+// API URL is automatically derived from DSN host
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+
+// Use Express error handler middleware (automatically captures errors with context)
+app.use(expressMiddleware());
+
+// Your routes
+app.get('/api/users', (req, res) => {
+  // If error occurs, it's automatically captured with request context
+  res.json({ users: [] });
+});
+
+app.listen(3000);
+```
+
+### 3. React Application
+
+```javascript
+// src/index.js or App.js
+import { register, ErrorBoundary } from '@watchforge/browser';
+
+// Initialize SDK
+// API URL is automatically derived from DSN host
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+
+// Wrap your app with ErrorBoundary
+function App() {
+  return (
+    <ErrorBoundary>
+      <YourApp />
+    </ErrorBoundary>
+  );
+}
+```
+
+## API Reference
+
+### `register(options)`
+
+Initialize the WatchForge SDK.
+
+**Options:**
+- `dsn` (string, required): Your project DSN. API URL is automatically derived from the DSN host.
+- `app_env` (string, default: "production"): Application environment name
+- `release` (string, optional): Release version identifier (e.g., "my-app@1.2.3" or "bustto-main-domain@9.6.5")
+- `debug` (boolean, default: false): Enable debug logging
+
+**Example:**
+```javascript
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+  release: "my-app@1.2.3", // Optional: Track which version caused errors
+  debug: true, // Enable debug logging
+});
+```
+
+**Release Parameter:**
+The `release` parameter helps you:
+- Track which version of your app caused errors
+- Filter errors by release version
+- Make rollback decisions based on error rates
+- Correlate errors with specific deployments
+
+**Example release formats:**
+- `"my-app@1.2.3"` - Semantic versioning
+- `"bustto-main-domain@9.6.5"` - Domain and version
+- `"v1.2.3"` - Simple version tag
+- `"2024-01-15-release"` - Date-based release
+
+**Note:** The API URL is automatically derived from the DSN host. For local development:
+- Use a DSN with `localhost` or `127.0.0.1`: `https://PUBLIC_KEY@127.0.0.1:8001/PROJECT_ID`
+- Or set `WATCHFORGE_API_URL` environment variable to override
+
+**Note:** `init()` is deprecated. Use `register()` instead for consistency with the Python SDK.
+
+### `captureException(error, context)`
+
+Capture an exception with optional context.
+
+**Parameters:**
+- `error` (Error): The error/exception to capture
+- `context` (object, optional): Additional context
+  - `user` (object): User information
+  - `request` (object): Request information
+  - `tags` (object): Tags for filtering
+  - `extra` (object): Extra data
+
+**Example:**
+```javascript
+try {
+  // your code
+} catch (error) {
+  captureException(error, {
+    user: {
+      id: "123",
+      email: "user@example.com",
+      ip_address: "192.168.1.1",
+    },
+    request: {
+      url: "/api/users",
+      method: "GET",
+    },
+    tags: {
+      component: "user-service",
+    },
+  });
+}
+```
+
+### `captureMessage(message, level, context)`
+
+Capture a custom message.
+
+**Parameters:**
+- `message` (string): Message to capture
+- `level` (string, default: "info"): Level (info, warning, error)
+- `context` (object, optional): Additional context
+
+**Example:**
+```javascript
+captureMessage("User logged in", "info", {
+  user: { id: "123", email: "user@example.com" },
+});
+```
+
+## Framework-Specific Examples
+
+### Express.js - Complete Setup
+
+```javascript
+// server.js
+const express = require('express');
+const { register, expressMiddleware } = require('@watchforge/browser');
+
+const app = express();
+
+// Initialize SDK
+// API URL is automatically derived from DSN host
+// Set WATCHFORGE_API_URL env var to override for local dev
+register({
+  dsn: process.env.WATCHFORGE_DSN,
+  app_env: process.env.NODE_ENV || "production",
+  debug: process.env.NODE_ENV === 'development',
+});
+
+// Use Express error handler middleware
+// This automatically captures errors with request context, user info, and IP address
+app.use(expressMiddleware());
+
+// Your routes
+app.get('/api/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+app.listen(3000);
+```
+
+### React - Complete Setup
+
+```javascript
+// src/index.js
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { register, ErrorBoundary } from '@watchforge/browser';
+import App from './App';
+
+// Initialize SDK
+// API URL is automatically derived from DSN host
+register({
+  dsn: process.env.REACT_APP_WATCHFORGE_DSN,
+  app_env: process.env.NODE_ENV || "production",
+  debug: process.env.NODE_ENV === 'development',
+});
+
+// ✅ Automatically captured (NO ErrorBoundary needed):
+// - window.onerror (uncaught JavaScript errors)
+// - window.onunhandledrejection (unhandled promise rejections)
+// - Errors in event handlers
+// - Errors in async code
+
+// ⚠️ ErrorBoundary needed for:
+// - React component render errors
+// - React lifecycle method errors
+// - React constructor errors
+
+// Recommended: Wrap your app with ErrorBoundary to catch React component errors
+ReactDOM.render(
+  <ErrorBoundary>
+    <App />
+  </ErrorBoundary>,
+  document.getElementById('root')
+);
+```
+
+**Is ErrorBoundary compulsory?**
+
+**No, but recommended:**
+- ✅ **General JavaScript errors** are automatically captured (no ErrorBoundary needed)
+- ✅ **Unhandled promise rejections** are automatically captured
+- ✅ **Event handler errors** are automatically captured
+- ⚠️ **React component errors** require ErrorBoundary (React requirement)
+
+**Minimal setup (without ErrorBoundary):**
+```javascript
+// This will still capture most errors automatically
+register({
+  dsn: "...",
+  app_env: "production",
+});
+
+ReactDOM.render(<App />, document.getElementById('root'));
+// ✅ JavaScript errors, promise rejections, etc. are auto-captured
+// ❌ React component render errors won't be captured
+```
+
+**Recommended setup (with ErrorBoundary):**
+```javascript
+register({
+  dsn: "...",
+  app_env: "production",
+});
+
+ReactDOM.render(
+  <ErrorBoundary>
+    <App />
+  </ErrorBoundary>,
+  document.getElementById('root')
+);
+// ✅ All errors captured including React component errors
+```
+
+### Node.js - Complete Setup
+
+```javascript
+// app.js
+const { register, captureException } = require('@watchforge/browser');
+
+// Initialize SDK
+// API URL is automatically derived from DSN host
+register({
+  dsn: process.env.WATCHFORGE_DSN,
+  app_env: process.env.NODE_ENV || "production",
+});
+
+// Global uncaught exception handler
+process.on('uncaughtException', (error) => {
+  captureException(error);
+  process.exit(1);
+});
+
+// Global unhandled rejection handler
+process.on('unhandledRejection', (reason, promise) => {
+  captureException(reason);
+});
+
+// Your application code
+async function main() {
+  try {
+    // your code
+  } catch (error) {
+    captureException(error);
+  }
+}
+
+main();
+```
+
+## Environment Variables
+
+### Development (.env)
+
+```bash
+WATCHFORGE_DSN=https://PUBLIC_KEY@watchforge.io/PROJECT_ID
+WATCHFORGE_API_URL=http://127.0.0.1:8001/api/ingestion/events/
+NODE_ENV=development
+```
+
+### Production
+
+```bash
+WATCHFORGE_DSN=https://PUBLIC_KEY@watchforge.io/PROJECT_ID
+NODE_ENV=production
+# Don't set WATCHFORGE_API_URL - uses DSN-derived URL
+```
+
+## Automatic Capture
+
+The SDK automatically captures errors when you call `register()`:
+
+### Browser (React) - Auto-captured (NO setup needed)
+- ✅ `window.onerror` - Uncaught JavaScript errors
+- ✅ `window.onunhandledrejection` - Unhandled promise rejections
+- ✅ Errors in event handlers
+- ✅ Errors in async code
+- ⚠️ React component errors - Requires `<ErrorBoundary>` wrapper
+
+### Node.js - Auto-captured
+- ✅ `process.on('uncaughtException')` - Uncaught exceptions
+- ✅ `process.on('unhandledRejection')` - Unhandled promise rejections
+
+### Express.js - Requires middleware
+- ⚠️ Express errors - Requires `app.use(expressMiddleware())`
+- ✅ Request context (URL, method, headers, user) - Auto-included with middleware
+
+## Manual Capture
+
+You can also manually capture:
+
+```javascript
+import { captureException, captureMessage } from '@watchforge/browser';
+
+// Capture exception
+try {
+  // code
+} catch (error) {
+  captureException(error);
+}
+
+// Capture message
+captureMessage("User action", "info");
+```
+
+## Best Practices
+
+1. **Initialize early**: Call `register()` as early as possible in your application
+2. **Use environment variables**: Don't hardcode DSNs
+3. **Set user context**: Include user information in error context
+4. **Include request context**: For Express.js, use `expressMiddleware()`
+5. **Use ErrorBoundary in React**: Wrap your app with `<ErrorBoundary>` to catch React component errors (optional but recommended)
+
+## Troubleshooting
+
+### Events not appearing?
+
+1. **Check DSN is correct**
+   ```javascript
+   // Make sure DSN format is: https://PUBLIC_KEY@HOST/PROJECT_ID
+   register({
+     dsn: "https://...@watchforge.io/...",
+   });
+   ```
+
+2. **For local development, use a DSN with localhost or set environment variable**
+   ```javascript
+   // Option 1: Use DSN with localhost
+   register({
+     dsn: "https://PUBLIC_KEY@127.0.0.1:8001/PROJECT_ID", // ✅ API URL derived from DSN
+   });
+   
+   // Option 2: Set environment variable
+   // WATCHFORGE_API_URL=http://127.0.0.1:8001/api/ingestion/events/
+   register({
+     dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID", // ✅ API URL from env var
+   });
+   ```
+
+3. **Check backend is running**
+   ```bash
+   # Make sure backend is running on port 8001
+   cd watchforge-backend
+   python manage.py runserver 8001
+   ```
+
+4. **Enable debug mode**
+   ```javascript
+   register({
+     dsn: "...",
+     debug: true, // ✅ See debug logs in console
+   });
+   ```
+
+5. **Check network connectivity**
+   - Open browser DevTools → Network tab
+   - Look for POST requests to `/api/ingestion/events/`
+   - Check for CORS errors
+
+6. **Check browser/Node.js console for errors**
+   - Look for SDK initialization messages
+   - Check for any error messages
+
+### IP address missing?
+
+Make sure to include IP address in user context:
+```javascript
+// Express.js - IP is automatically extracted by expressMiddleware()
+app.use(expressMiddleware()); // ✅ Automatically includes IP
+
+// Manual capture
+captureException(error, {
+  user: {
+    id: user.id,
+    email: user.email,
+    ip_address: req.ip, // ✅ Include IP
+  },
+});
+```
+
+### Common Issues
+
+**Issue: "DSN not set"**
+- Make sure you call `register()` before using `captureException()`
+
+**Issue: Events not reaching backend**
+- Check DSN host is correct (API URL is derived from DSN)
+- For local dev, use DSN with `127.0.0.1:8001` or set `WATCHFORGE_API_URL` env var
+- Verify backend is running and accessible
+- Check CORS settings if testing from browser
+
+**Issue: No debug output**
+- Set `debug: true` in `register()` options
+- Check console for SDK messages
+
+## Testing Your Setup
+
+### Step 1: Start Your Backend
+
+Make sure your WatchForge backend is running:
+
+```bash
+cd watchforge-backend
+python manage.py runserver 8001
+```
+
+### Step 2: Test Node.js SDK
+
+```bash
+# In watchforge-javascript-sdk directory
+node test-node.js
+```
+
+**Expected Output:**
+```
+✅ WatchForge SDK initialized for Node.js
+📝 Test 1: Capturing exception...
+✅ Exception captured
+📝 Test 2: Capturing exception with context...
+✅ Exception with context captured
+...
+```
+
+**Check Backend Logs:**
+You should see events appearing in your backend logs at `/api/ingestion/events/`
+
+### Step 3: Test Express.js SDK
+
+```bash
+# Install Express if needed
+npm install express
+
+# Run test server
+node test-express.js
+```
+
+**Then visit:**
+- `http://localhost:3000/ok` - Should return JSON
+- `http://localhost:3000/error` - Will trigger error (check backend logs)
+
+### Step 4: Verify Events in Backend
+
+Check your backend terminal/logs for:
+```
+POST /api/ingestion/events/ - 201 Created
+```
+
+Or check the Django admin or your database for new events.
+
+### Test DSN (for local testing)
+
+Use this DSN for local development:
+```
+https://91960c09176bb2e7d0909156db1aa5c4ec44eba5e7b862a84f0de952077756c9@watchforge.io/5edc2191-c7ff-4341-ae45-c8693d16f689
+```
+
+And set:
+```javascript
+// For local development, use DSN with 127.0.0.1:8001
+register({
+  dsn: "https://91960c09176bb2e7d0909156db1aa5c4ec44eba5e7b862a84f0de952077756c9@127.0.0.1:8001/5edc2191-c7ff-4341-ae45-c8693d16f689",
+  app_env: "development",
+  debug: true, // Enable to see debug logs
+});
+```
+
+## Complete Examples
+
+### Example 1: Minimal Node.js Setup
+
+```javascript
+// app.js
+const { register, captureException } = require('@watchforge/browser');
+
+// Initialize
+// API URL is automatically derived from DSN host
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+
+// Use
+try {
+  // your code
+} catch (error) {
+  captureException(error);
+}
+```
+
+### Example 2: Express.js with Error Handling
+
+```javascript
+// server.js
+const express = require('express');
+const { register, expressMiddleware } = require('@watchforge/browser');
+
+const app = express();
+
+register({
+  dsn: process.env.WATCHFORGE_DSN,
+  app_env: process.env.NODE_ENV,
+});
+
+// Add error handler (must be last middleware)
+app.use(expressMiddleware());
+
+app.listen(3000);
+```
+
+### Example 3: React with Error Boundary
+
+```javascript
+// src/index.js
+import { register, ErrorBoundary } from '@watchforge/browser';
+import App from './App';
+
+register({
+  dsn: process.env.REACT_APP_WATCHFORGE_DSN,
+  app_env: process.env.NODE_ENV,
+});
+
+ReactDOM.render(
+  <ErrorBoundary>
+    <App />
+  </ErrorBoundary>,
+  document.getElementById('root')
+);
+```
+
+## Test Scripts
+
+Test scripts are included in the SDK directory:
+- `test-node.js` - Test Node.js SDK
+- `test-express.js` - Test Express.js SDK  
+- `test-react.html` - Test React SDK (HTML example)
+
+Run them to verify your setup is working correctly!