@bugmail-js/core 0.1.0 → 0.1.3

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/package.json

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