@kenkaiiii/error-mom 0.3.3 → 0.3.5

package/README.md

@@ -1,17 +1,124 @@
 # @kenkaiiii/error-mom
 
-Automatic browser and Node.js error capture for a self-hosted Error Mom deployment.
+Automatic browser and Node.js error capture for a self-hosted [Error Mom](https://github.com/KenKaiii/error-mom) deployment.
+
+## Install
+
+```bash
+npm install @kenkaiiii/error-mom
+```
+
+Create a project and generate framework-specific setup with the Error Mom CLI:
+
+```bash
+npm install --global error-mom
+error-mom login https://errors.example.com --token "$ERROR_MOM_ADMIN_TOKEN"
+error-mom init
+```
+
+`error-mom init` detects your framework and prints the exact wiring step for its official error hook. The generated project key is write-only and safe to ship; the admin token must stay private.
+
+## Browser setup
 
 ```ts
 import { initErrorMom } from "@kenkaiiii/error-mom";
 
-initErrorMom({
+export const errorMom = initErrorMom({
   server: "https://errors.example.com",
   projectKey: "em_ingest_...",
-  release: "1.0.0",
+  environment: import.meta.env.MODE,
+  release: import.meta.env.VITE_APP_VERSION,
+});
+```
+
+The browser entry point captures uncaught errors, unhandled rejections, `console.error`, failed requests, and up to 50 preceding breadcrumbs. Failed sends queue in local storage and retry without blocking the app.
+
+## Node.js setup
+
+```ts
+import { initErrorMom } from "@kenkaiiii/error-mom/node";
+
+export const errorMom = initErrorMom({
+  server: process.env.ERROR_MOM_SERVER!,
+  projectKey: process.env.ERROR_MOM_PROJECT_KEY!,
+  environment: process.env.NODE_ENV,
+  release: process.env.APP_VERSION,
+});
+```
+
+The Node entry point captures uncaught errors, unhandled rejections, `console.error`, and failed requests. Events are written to a private JSONL spool under `~/.error-mom/spool` before upload so an outage or restart does not discard them.
+
+Initialize the SDK separately in every process: browser UI, Electron main process, workers, sidecars, and server processes.
+
+## Capture handled errors
+
+```ts
+try {
+  await exportVideo();
+} catch (error) {
+  errorMom.captureError(error, {
+    culprit: "video.export",
+    tags: { job: "render" },
+    context: { videoId },
+  });
+  throw error;
+}
+```
+
+Wrap handlers that are caught by a framework, queue, webhook runner, or MCP host:
+
+```ts
+export const handler = errorMom.wrap(runJob, {
+  culprit: "jobs.render-video",
 });
 ```
 
-Use `@kenkaiiii/error-mom/node` for Node.js. The browser adapter retries through local storage; the Node adapter writes a private JSONL spool before upload.
+Add application breadcrumbs when they help explain a later failure:
+
+```ts
+errorMom.addBreadcrumb({
+  category: "checkout",
+  level: "info",
+  message: "Payment submitted",
+  data: { provider: "stripe" },
+});
+```
+
+Use `await errorMom.flush()` before a controlled shutdown. Call `dispose()` during teardown to restore patched global handlers.
+
+## Options
+
+| Option                  | Required  | Description                                                          |
+| ----------------------- | --------- | -------------------------------------------------------------------- |
+| `server`                | yes       | Base URL of your Error Mom deployment.                               |
+| `projectKey`            | yes       | Write-only project ingest key. Safe to include in shipped clients.   |
+| `environment`           | no        | Deployment environment; defaults to `production`.                    |
+| `release`               | no        | App version used for regression detection and source maps.           |
+| `tags`                  | no        | String tags attached to every event.                                 |
+| `installationId`        | no        | Optional anonymous installation identifier. Only its hash is stored. |
+| `captureConsoleErrors`  | no        | Capture `console.error`; defaults to `true`.                         |
+| `captureFailedRequests` | no        | Capture failed requests; defaults to `true`.                         |
+| `flushIntervalMs`       | no        | Retry interval; defaults to 5 seconds.                               |
+| `maxQueueSize`          | no        | Browser default: 100. Node default: 1,000.                           |
+| `spoolDirectory`        | Node only | Override the Node JSONL spool directory.                             |
+
+## Automatic request capture
+
+Network failures and HTTP 5xx responses are captured automatically. Errors from known AI providers are named and tagged by provider; provider 4xx responses are captured as well. Captured request failures include sanitized method, URL, status, provider, and retryability context.
+
+## Privacy and safety
+
+Capture and upload failures never throw into the host application. Before sending, the SDK recursively scrubs secret-keyed fields, emails, query credentials, URL userinfo, Telegram bot tokens, Discord and Slack webhook credentials, and explicitly labeled credential path segments such as `/token/<value>` and `/api-key/<value>`. The collector repeats redaction before persistence.
+
+## Source maps and verification
+
+For minified production builds, report a `release`, enable source maps, and upload them after the build:
+
+```bash
+error-mom sourcemaps <build-directory> --release <app-version> --project <project-slug>
+error-mom doctor --symbolication
+```
+
+Source-map upload requires the private admin token. Ingest keys cannot upload or read data.
 
-See the repository README for framework setup, privacy controls, and deployment instructions.
+See the [repository README](https://github.com/KenKaiii/error-mom#readme) for deployment, framework setup, dashboard, CLI, and MCP instructions.

package/dist/{chunk-UNG24UNX.js → chunk-OWVVPGEQ.js}

@@ -3,7 +3,7 @@ import {
   redactStringCredentials
 } from "@kenkaiiii/error-mom-protocol";
 var SDK_NAME = "@kenkaiiii/error-mom";
-var SDK_VERSION = "0.3.3";
+var SDK_VERSION = "0.3.5";
 var MAX_BREADCRUMBS = 50;
 var SECRET_KEY = /authorization|cookie|password|passwd|secret|token|api[-_]?key|session/i;
 function wrapFunction(capture, fn, context) {
@@ -156,6 +156,7 @@ function describeFailedRequest(method, url, status) {
   const relevant = status >= 500 || provider !== void 0 && status >= 400;
   if (!relevant) return void 0;
   const cleanUrl = redactString(url);
+  const retryable = status === 408 || status === 429 || status >= 500;
   const error = new Error(`${method} ${cleanUrl} returned ${status}`);
   if (provider) {
     const label = provider.charAt(0).toUpperCase() + provider.slice(1);
@@ -168,7 +169,11 @@ function describeFailedRequest(method, url, status) {
       tags: {
         statusCode: String(status),
         method,
+        retryable: String(retryable),
         ...provider ? { provider } : {}
+      },
+      context: {
+        request: { method, url: cleanUrl, status, retryable }
       }
     }
   };

package/dist/index.cjs

@@ -27,7 +27,7 @@ module.exports = __toCommonJS(index_exports);
 // src/shared.ts
 var import_error_mom_protocol = require("@kenkaiiii/error-mom-protocol");
 var SDK_NAME = "@kenkaiiii/error-mom";
-var SDK_VERSION = "0.3.3";
+var SDK_VERSION = "0.3.5";
 var MAX_BREADCRUMBS = 50;
 var SECRET_KEY = /authorization|cookie|password|passwd|secret|token|api[-_]?key|session/i;
 function wrapFunction(capture, fn, context) {
@@ -180,6 +180,7 @@ function describeFailedRequest(method, url, status) {
   const relevant = status >= 500 || provider !== void 0 && status >= 400;
   if (!relevant) return void 0;
   const cleanUrl = redactString(url);
+  const retryable = status === 408 || status === 429 || status >= 500;
   const error = new Error(`${method} ${cleanUrl} returned ${status}`);
   if (provider) {
     const label = provider.charAt(0).toUpperCase() + provider.slice(1);
@@ -192,7 +193,11 @@ function describeFailedRequest(method, url, status) {
       tags: {
         statusCode: String(status),
         method,
+        retryable: String(retryable),
         ...provider ? { provider } : {}
+      },
+      context: {
+        request: { method, url: cleanUrl, status, retryable }
       }
     }
   };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   printable,
   redactString,
   wrapFunction
-} from "./chunk-UNG24UNX.js";
+} from "./chunk-OWVVPGEQ.js";
 
 // src/index.ts
 var clients = /* @__PURE__ */ new Map();

package/dist/node.cjs

@@ -32,7 +32,7 @@ var import_node_path = require("path");
 // src/shared.ts
 var import_error_mom_protocol = require("@kenkaiiii/error-mom-protocol");
 var SDK_NAME = "@kenkaiiii/error-mom";
-var SDK_VERSION = "0.3.3";
+var SDK_VERSION = "0.3.5";
 var MAX_BREADCRUMBS = 50;
 var SECRET_KEY = /authorization|cookie|password|passwd|secret|token|api[-_]?key|session/i;
 function wrapFunction(capture, fn, context) {
@@ -185,6 +185,7 @@ function describeFailedRequest(method, url, status) {
   const relevant = status >= 500 || provider !== void 0 && status >= 400;
   if (!relevant) return void 0;
   const cleanUrl = redactString(url);
+  const retryable = status === 408 || status === 429 || status >= 500;
   const error = new Error(`${method} ${cleanUrl} returned ${status}`);
   if (provider) {
     const label = provider.charAt(0).toUpperCase() + provider.slice(1);
@@ -197,7 +198,11 @@ function describeFailedRequest(method, url, status) {
       tags: {
         statusCode: String(status),
         method,
+        retryable: String(retryable),
         ...provider ? { provider } : {}
+      },
+      context: {
+        request: { method, url: cleanUrl, status, retryable }
       }
     }
   };

package/dist/node.js

@@ -8,7 +8,7 @@ import {
   printable,
   redactString,
   wrapFunction
-} from "./chunk-UNG24UNX.js";
+} from "./chunk-OWVVPGEQ.js";
 
 // src/node.ts
 import { createHash } from "crypto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kenkaiiii/error-mom",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Automatic browser and Node.js error capture for self-hosted Error Mom",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,7 +22,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@kenkaiiii/error-mom-protocol": "0.1.1"
+    "@kenkaiiii/error-mom-protocol": "0.1.3"
   },
   "devDependencies": {
     "tsup": "^8.5.1",