@bugmail-js/core 0.1.0 → 0.1.4

package/README.md

@@ -1,3 +1,89 @@
+# @bugmail-js/core — Core utilities for BugMail SDKs
+
+This package contains framework-agnostic building blocks used by the BugMail JavaScript SDKs (browser, Node, and server integrations).
+
+Use this package if you are building a custom integration or need low-level control. It exports small, well-scoped classes for capturing errors, tracking breadcrumbs, and sending reports.
+
+Highlights
+- `BugMailCoreClient` — lightweight client that prepares and sends error payloads to the BugMail backend.
+- `BreadcrumbTracker` — record user events leading up to an error.
+- `CoreNetworkManager`, `CoreErrorProcessor` — helpers for networking and normalization.
+
+Installation
+
+Typically you do not need to install this directly; other SDK packages depend on it. If you need it directly:
+
+```bash
+npm install @bugmail-js/core
+```
+
+Quick example (capture an exception)
+
+```javascript
+import { BugMailCoreClient } from '@bugmail-js/core';
+
+const client = new BugMailCoreClient({
+  baseUrl: 'http://localhost:8000',
+  apiPath: '/api/sdk/v1/errors',
+  onError: (info) => console.warn('Reporting failed', info),
+});
+
+await client.captureException(new Error('Test error'), {
+  headers: { 'X-Bugmail-Api-Key': 'YOUR_PROJECT_API_KEY' },
+  payload: {
+    error: { name: 'Error', message: 'Test error', stack: '...' },
+    context: { url: '/test', environment: 'development' }
+  },
+});
+```
+
+API reference (important parts)
+
+- `new BugMailCoreClient(config)`
+  - `config.baseUrl` — backend base URL (default: env `BUGMAIL_API_BASE_URL` or `http://localhost:8000`)
+  - `config.apiPath` — ingestion path (default: `/api/sdk/v1/errors`)
+  - `config.onError` — optional callback invoked when report fails
+
+- `captureException(error, context)`
+  - `error` — Error object or any serializable value
+  - `context` — optional object: `{ headers, payload, user, breadcrumbs }`
+    - Include `headers: { 'X-Bugmail-Api-Key': '<YOUR_PROJECT_API_KEY>' }`
+
+- `BreadcrumbTracker`
+  - `new BreadcrumbTracker({ maxBreadcrumbs })`
+  - `record(breadcrumb)` — add a breadcrumb object
+  - `recordCustom(message, category, data, level)`
+  - `recordRequest(requestData)` — convenience for HTTP breadcrumbs
+  - `getBreadcrumbs()`, `clear()`
+
+Advanced
+
+- `CoreNetworkManager` and `CoreErrorProcessor` are exported for advanced integration points (custom retries, queueing, or server-side normalization).
+
+Integration notes
+
+- The core package is intentionally minimal and has no browser-only dependencies. Browser and Node SDKs re-export and extend it with environment-specific behavior (automatic capture, global handlers, middleware, etc.).
+
+Backend integration & headers
+
+- Ingestion endpoint: `POST {baseUrl}/api/sdk/v1/errors`
+- Auth header: `x-bugmail-api-key: <YOUR_PROJECT_API_KEY>` (case-insensitive)
+- Typical payload shape:
+
+```
+{
+  "error": { "name": "TypeError", "message": "...", "stack": "..." },
+  "context": { "breadcrumbs": [...], "request": { ... } },
+  "timestamp": "2025-09-06T15:40:00.000Z",
+  "environment": "production"
+}
+```
+
+The backend validates the API key, groups the error, stores breadcrumbs, enforces rate/plan limits, may run AI analysis, and returns `201` with `{ status: "success", error_id: "..." }`.
+
+Contributing
+
+Please follow the repository contributing guidelines. Tests and simple usage examples are appreciated.
 # Shared core logic for BugMail SDKs
 
 This package will contain shared logic for Node.js and Django SDKs.

package/bugmail-core-client.js

@@ -26,11 +26,18 @@ export class BugMailCoreClient {
 
     try {
       // Use fetch if available (browser or Node >=18), else fallback
+      // Prefer global fetch (browsers, Node 18+). Avoid importing node-fetch in bundlers
       let fetchFn = (typeof fetch !== 'undefined') ? fetch : undefined;
       if (!fetchFn) {
+        // In Node environments where fetch is not global, try dynamic import at runtime only
         try {
-          // Dynamically import node-fetch if not in browser
-          fetchFn = (await import('node-fetch')).default;
+          // Use require-like dynamic import only in Node; bundlers should not include node-fetch for browser builds
+          if (typeof process !== 'undefined' && process.versions && process.versions.node) {
+            fetchFn = (await import('node-fetch')).default;
+          } else {
+            console.error('[BugMail] fetch is not available in this environment.');
+            return;
+          }
         } catch (e) {
           console.error('[BugMail] fetch is not available in this environment.');
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bugmail-js/core",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "main": "index.js",
   "module": "index.js",
   "exports": {
@@ -35,4 +35,4 @@
     "url": "https://github.com/MarcorpAI/Bugmail-SDKs/issues"
   },
   "sideEffects": false
-}
+}

package/plugin-manager.js

@@ -1,7 +1,45 @@
 // Plugin manager (core, generic)
 export class CorePluginManager {
   constructor() {
-    // ...core plugin system
+    // Maintain a set of plugins and a simple hook map
+    this.plugins = new Set();
+    this.hooks = {
+      setup: new Set(),
+      disconnect: new Set(),
+      onErrorCaptured: new Set(),
+    };
+  }
+
+  register(plugin) {
+    this.plugins.add(plugin);
+  }
+
+  unregister(plugin) {
+    this.plugins.delete(plugin);
+  }
+
+  runHooks(hookName, data, client) {
+    const hooks = this.hooks[hookName];
+    if (!hooks) return data;
+    let result = data;
+    for (const fn of hooks) {
+      try {
+        const r = fn(result, client);
+        if (r !== undefined) result = r;
+      } catch (e) {
+        // swallow plugin errors to avoid breaking host app
+        console.error('[BugMail] Plugin hook error:', e);
+      }
+    }
+    return result;
+  }
+
+  addHook(hookName, fn) {
+    if (!this.hooks[hookName]) this.hooks[hookName] = new Set();
+    this.hooks[hookName].add(fn);
+  }
+
+  removeHook(hookName, fn) {
+    this.hooks[hookName]?.delete(fn);
   }
-  // ...core methods
 }