@watchupltd/browser 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,280 @@
+# @watchupltd/browser
+
+Browser runtime integration for incident tracking in vanilla JavaScript/TypeScript applications.
+
+## Installation
+
+```bash
+npm install @watchupltd/browser
+```
+
+## Usage
+
+### Basic Setup
+
+```javascript
+import { init } from '@watchupltd/browser';
+
+const client = init({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  environment: 'production',
+  captureConsoleErrors: true // Optional: capture console.error calls
+});
+```
+
+### Manual Error Capture
+
+```javascript
+try {
+  riskyOperation();
+} catch (error) {
+  client.captureError(error, {
+    tags: { section: 'checkout' },
+    extra: { orderId: '12345' }
+  });
+}
+```
+
+### Capture Messages
+
+```javascript
+client.captureMessage('Payment processed successfully', 'info');
+```
+
+### Set User Context
+
+```javascript
+client.setUser({
+  id: 'user-123',
+  email: 'user@example.com',
+  username: 'john_doe'
+});
+```
+
+### Add Breadcrumbs
+
+```javascript
+client.addBreadcrumb({
+  message: 'User clicked checkout button',
+  category: 'user-action',
+  level: 'info'
+});
+```
+
+### Add Tags
+
+```javascript
+client.setTag('version', '1.2.3');
+client.setTags({
+  browser: 'chrome',
+  os: 'windows'
+});
+```
+
+## What It Tracks
+
+### Automatic Tracking
+
+- **Global JavaScript Errors**: Captures all uncaught errors via `window.onerror`
+- **Unhandled Promise Rejections**: Captures via `window.onunhandledrejection`
+- **Console Errors**: Optionally captures `console.error()` calls
+
+### Manual Tracking
+
+- Custom errors via `captureError()`
+- Log messages via `captureMessage()`
+- User actions via `addBreadcrumb()`
+
+## Configuration Options
+
+```typescript
+interface BrowserConfig {
+  apiKey: string;                    // Required: Your API key
+  projectId: string;                 // Required: Your project ID
+  endpoint?: string;                 // Optional: Custom API endpoint
+  environment?: string;              // Optional: Environment (default: 'production')
+  batchInterval?: number;            // Optional: Batch interval in ms (default: 5000)
+  maxBatchSize?: number;             // Optional: Max events per batch (default: 10)
+  maxRetries?: number;               // Optional: Max retry attempts (default: 3)
+  enabled?: boolean;                 // Optional: Enable/disable SDK (default: true)
+  captureConsoleErrors?: boolean;    // Optional: Capture console.error (default: false)
+}
+```
+
+## Data Models
+
+### Event Model
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "project_id": "proj_abc123",
+  "fingerprint": "a1b2c3d4e5f6...",
+  "title": "ValueError",
+  "message": "Invalid user input: expected integer",
+  "stack_trace": "Traceback (most recent call last):\n  File \"app.py\", line 42...",
+  "service": "frontend",
+  "environment": "production",
+  "severity": "error",
+  "timestamp": 1678901234567,
+  "platform": "javascript",
+  "release": "1.2.3",
+  "server_name": "web-app-01",
+  "metadata": {
+    "custom_key": "custom_value"
+  },
+  "user": {
+    "id": "user-123",
+    "email": "user@example.com",
+    "username": "john_doe",
+    "ip_address": "192.168.1.1"
+  },
+  "tags": {
+    "component": "payment",
+    "version": "1.2.3"
+  },
+  "breadcrumbs": [
+    {
+      "timestamp": 1678901230000,
+      "message": "User logged in",
+      "category": "auth",
+      "level": "info",
+      "data": {}
+    }
+  ],
+  "context": {
+    "browser": {
+      "name": "Chrome",
+      "version": "120.0.0"
+    },
+    "os": {
+      "name": "Windows",
+      "version": "10.0"
+    }
+  }
+}
+```
+
+### User Model
+
+```json
+{
+  "id": "user-123",
+  "email": "user@example.com",
+  "username": "john_doe",
+  "ip_address": "192.168.1.1"
+}
+```
+
+### Breadcrumb Model
+
+```json
+{
+  "timestamp": 1678901234567,
+  "message": "User action description",
+  "category": "user-action | navigation | http | database | console",
+  "level": "fatal | error | warning | info | debug",
+  "data": {
+    "key": "value"
+  }
+}
+```
+
+## Use Cases
+
+Perfect for:
+- Vanilla JavaScript applications
+- TypeScript applications without frameworks
+- Static websites with custom JavaScript
+- Browser extensions
+- Bookmarklets
+- Any web application not using React/Vue/Angular/etc.
+
+## Example: Complete Setup
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My App</title>
+</head>
+<body>
+  <button id="testBtn">Test Error</button>
+
+  <script type="module">
+    import { init } from '@watchupltd/browser';
+
+    // Initialize
+    const client = init({
+      apiKey: 'your-api-key',
+      projectId: 'your-project-id',
+      environment: 'production',
+      captureConsoleErrors: true
+    });
+
+    // Set user context
+    client.setUser({
+      id: '123',
+      email: 'user@example.com'
+    });
+
+    // Add breadcrumb
+    client.addBreadcrumb({
+      message: 'Page loaded',
+      category: 'navigation'
+    });
+
+    // Manual error capture
+    document.getElementById('testBtn').addEventListener('click', () => {
+      try {
+        throw new Error('Test error');
+      } catch (error) {
+        client.captureError(error, {
+          tags: { source: 'button-click' }
+        });
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included.
+
+```typescript
+import { init, getClient, IncidentClient } from '@watchupltd/browser';
+import type { BrowserConfig, SeverityLevel } from '@watchupltd/browser';
+
+const config: BrowserConfig = {
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id'
+};
+
+const client: IncidentClient = init(config);
+```
+
+## API Reference
+
+### `init(config: BrowserConfig): IncidentClient`
+Initialize the browser SDK and set up global error handlers.
+
+### `getClient(): IncidentClient | null`
+Get the current client instance.
+
+### `IncidentClient` Methods
+
+- `captureError(error: Error, context?: EventContext): Promise<string | null>`
+- `captureMessage(message: string, level?: SeverityLevel, context?: EventContext): Promise<string | null>`
+- `addBreadcrumb(breadcrumb: Breadcrumb): void`
+- `setUser(user: User | null): void`
+- `setTag(key: string, value: string): void`
+- `setTags(tags: Record<string, string>): void`
+- `flush(): Promise<void>`
+- `close(): void`
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchupltd/browser",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -12,11 +12,11 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+    "build": "tsup src/index.ts --format cjs,esm --dts --external @watchupltd/core --no-splitting",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --external @watchupltd/core --no-splitting --watch"
   },
   "dependencies": {
-    "@watchupltd/core": "file:../core"
+    "@watchupltd/core": "^1.0.0"
   },
   "devDependencies": {
     "tsup": "^7.0.0",