@aidenappleby/monitor-js 1.1.0 → 1.2.1

package/README.md

@@ -0,0 +1,109 @@
+# monitor-js
+
+Lightweight JavaScript/TypeScript client for the Monitor platform — ships structured
+events (and auto-captured browser errors) as NDJSON to `monitor-core`.
+
+> **Monitor platform** · TypeScript SDK · `@aidenappleby/monitor-js` (npm)
+
+---
+
+## Overview
+
+`monitor-js` is the browser/Node SDK for Monitor, the counterpart to `go-monitor`. It
+queues and batches events, ships them to a zone's ingest endpoint over `fetch`, and can
+auto-capture uncaught errors and unhandled promise rejections (browser and Node). It keeps
+the same wire format as the Go SDK — including its rules for surviving ingest's
+all-or-nothing validation: invalid ids are cleared before sending, a rejected batch is
+split until only the malformed event is dropped, and transient failures are retried with
+backoff instead of discarded.
+
+## Install
+
+```bash
+npm install @aidenappleby/monitor-js
+```
+
+## Usage
+
+```ts
+import { Monitor } from "@aidenappleby/monitor-js";
+
+const monitor = new Monitor({
+  service: "my-web-app",
+  ingestUrl: "https://appleby-monitor-api.appleby.cloud/v1/events", // one zone's ingest endpoint
+  apiKey: process.env.MONITOR_API_KEY!,   // ingest-scoped key minted on that zone
+  env: "production",
+  onDrop: (total) => droppedEvents.set(total), // optional: be told about loss
+});
+
+monitor.setUser("user_123");
+monitor.info("checkout.start.success", { data: { cartTotal: 4200 } });
+monitor.error("checkout.payment.failed", { data: { reason: "card_declined" } });
+
+monitor.stats(); // { enqueued, flushed, dropped, quarantined, queued }
+
+// on teardown
+monitor.shutdown();
+```
+
+> **In a browser, `apiKey` is public** — anyone who loads the page can read it. Prefer
+> pointing `ingestUrl` at a route on your own origin that forwards to Monitor server-side.
+
+Uncaught errors and unhandled rejections are captured automatically in **both** the
+browser (`window`) and Node (`process.on`) — disable with `captureErrors: false` /
+`captureUnhandledRejections: false`. Filter noise with
+`ignoreErrors: [/extension/i, "ResizeObserver"]`.
+
+In Node, installing a process listener would normally stop an uncaught exception from
+crashing the process. The SDK keeps Node's behavior: when it is the **only**
+`uncaughtException` listener, it reports, prints the error, waits up to 1.5s for the batch
+to leave, and exits 1; an unhandled rejection with no other listener is re-raised as an
+uncaught exception, exactly as Node does by default. If your app has its own listener, the
+SDK only reports. Server code that manages its own crash handling (e.g. a Next.js
+`instrumentation.ts`) should pass `captureErrors: false, captureUnhandledRejections: false`.
+
+### Correlation ids
+
+`request_id`, `trace_id` and `job_id` must be a UUID or 8–64 hex characters — anything
+else is cleared before sending and kept in `data.invalid_<field>`. Each `Monitor` mints a
+session `job_id`; mint the others with the helpers:
+
+```ts
+import { newRequestId, newTraceId, isValidCorrelationId } from "@aidenappleby/monitor-js";
+
+monitor.info("upload.start.success", { requestId: newRequestId(), traceId: newTraceId() });
+```
+
+### Axios integration
+
+```ts
+import axios from "axios";
+import { attachAxiosMonitor } from "@aidenappleby/monitor-js";
+
+const api = axios.create({ baseURL: "/api", validateStatus: () => true });
+attachAxiosMonitor(api, monitor, { ignorePaths: ["/health"] });
+```
+
+Reported URLs have their query string removed.
+
+## Role in the Monitor ecosystem
+
+- **`monitor-core`** — ingestion target (`POST /v1/events`, `X-Api-Key`).
+- **`go-monitor`** — the Go SDK; shares the wire format and delivery rules.
+- **`monitor-web`** — displays the events (it does not use this SDK).
+
+## Development
+
+| Command | What it does |
+|---|---|
+| `npm run check` | `tsc --noEmit` |
+| `npm test` | vitest |
+| `npm run build` | tsup → `dist/` (CJS + ESM + d.ts) |
+
+Publishing to npm runs the build via `prepublishOnly` and requires 2FA.
+
+## Contributing & further reading
+
+Read **[AGENTS.md](./AGENTS.md)** before working here — it documents the event pipeline,
+the delivery rules, the exact wire contract (kept in lockstep with `go-monitor` /
+`monitor-core`), the config surface, and current known issues.

package/dist/index.d.mts

@@ -2,9 +2,13 @@ type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
 interface MonitorConfig {
     /** Service name reported with every event */
     service: string;
-    /** Monitor ingest URL (e.g. https://monitor-ingest.appleby.cloud/v1/events) */
+    /** Full ingest endpoint of one zone (e.g. https://appleby-monitor-api.appleby.cloud/v1/events) */
     ingestUrl: string;
-    /** API key for authentication */
+    /**
+     * Ingest-scoped API key, minted on the zone ingestUrl points at. In a
+     * browser bundle this value is public — anyone who loads the page can read
+     * it — so prefer posting to a same-origin route that forwards server-side.
+     */
     apiKey: string;
     /** Environment name (default: "production") */
     env?: string;
@@ -26,6 +30,12 @@ interface MonitorConfig {
      * and `client.error.unhandled_rejection`. Default: [] (no filtering).
      */
     ignoreErrors?: (string | RegExp)[];
+    /**
+     * Called with the running total whenever events are lost: queue overflow,
+     * data that cannot be serialized, events ingest rejected as malformed, or a
+     * refused API key. Keep it cheap — bump a counter. A throw is swallowed.
+     */
+    onDrop?: (total: number) => void;
 }
 interface MonitorEvent {
     timestamp: string;
@@ -49,21 +59,43 @@ interface EmitOptions {
     /** Arbitrary data payload */
     data?: Record<string, unknown>;
 }
+/** Lifetime counters for one Monitor instance. */
+interface MonitorStats {
+    /** Events accepted into the queue. */
+    enqueued: number;
+    /** Events the ingest endpoint accepted. */
+    flushed: number;
+    /** Events lost for good: overflow, unserializable, malformed, or refused credentials. */
+    dropped: number;
+    /** The part of `dropped` ingest refused as malformed even when sent alone. */
+    quarantined: number;
+    /** Events currently waiting in the queue. */
+    queued: number;
+}
 
 declare class Monitor {
     private config;
     private ignoreErrors;
+    private onDrop?;
     private queue;
     private timer;
     private userId;
     private jobId;
     private active;
+    private backoffUntil;
+    private failures;
+    private warnedMisconfigured;
+    private counters;
     constructor(config: MonitorConfig);
     /** Set a persistent user ID for all subsequent events */
     setUser(userId: string): void;
     /** Clear the user ID */
     clearUser(): void;
-    /** Set a persistent job ID (session-level identifier) */
+    /**
+     * Set a persistent job ID (session-level identifier). It must be a UUID or
+     * 8-64 hex characters — see `isValidCorrelationId`; anything else is
+     * cleared from each event and kept in data.invalid_job_id.
+     */
     setJobId(jobId: string): void;
     /** Emit an event at a specific level */
     emit(name: string, level: LogLevel, opts?: EmitOptions): void;
@@ -77,16 +109,61 @@ declare class Monitor {
     error(name: string, opts?: EmitOptions): void;
     /** Emit a fatal event */
     fatal(name: string, opts?: EmitOptions): void;
+    /**
+     * Lifetime counters. Surface them wherever loss would otherwise go
+     * unnoticed: the system that would report dropped telemetry is the one
+     * dropping it.
+     */
+    stats(): MonitorStats;
     /** Flush all queued events to the ingest endpoint */
     flush(): void;
     /** Stop the monitor and flush remaining events */
     shutdown(): void;
+    /**
+     * @param unloading the page (or process) is going away: ignore the backoff,
+     * since this is the last chance these events get.
+     */
+    private flushQueue;
+    private send;
+    private handleResponse;
+    /** Put events back at the front of the queue and back off before retrying. */
+    private retryLater;
+    /**
+     * One NDJSON line for e, or null if it cannot be serialized. Never throws:
+     * flush runs inside emit's auto-flush, and emit must never throw into the
+     * caller.
+     */
+    private serialize;
+    private recordDrop;
     private start;
     private handleVisibilityChange;
     private handlePageHide;
     private shouldIgnoreError;
+    /**
+     * The route a browser error happened on.
+     *
+     * Deliberately `pathname` only — never the search string or hash. Query
+     * parameters routinely carry tokens, emails and other personal data, and this
+     * value is both stored on the event and folded into the server-side issue
+     * fingerprint, so anything included here is retained and grouped on.
+     *
+     * Returns undefined outside a browser so the Node handlers stay unaffected.
+     */
+    private currentPath;
     private errorHandler;
     private rejectionHandler;
+    /** Grace for the final batch to leave before a Node-style crash exits. */
+    private static readonly NODE_CRASH_GRACE_MS;
+    /** Rejections already reported, so the re-raise below is not reported twice. */
+    private reportedRejections;
+    private nodeExceptionHandler;
+    private nodeRejectionHandler;
+    /** Hand an unhandled rejection back to Node as an uncaught exception. */
+    private reraise;
+    /** True when this instance's own handler is the only listener for the event. */
+    private isSoleListener;
+    /** Print the error as Node would, give the batch a moment to leave, exit 1. */
+    private crashLikeNode;
     private installErrorHandler;
     private installRejectionHandler;
     private removeListeners;
@@ -119,4 +196,16 @@ interface AxiosMonitorOptions {
  */
 declare function attachAxiosMonitor(axiosInstance: AxiosInstance, monitor: Monitor, opts?: AxiosMonitorOptions): void;
 
-export { type AxiosMonitorOptions, type EmitOptions, type LogLevel, Monitor, type MonitorConfig, type MonitorEvent, attachAxiosMonitor };
+/**
+ * Whether monitor-core would accept `id` as a job_id, request_id or trace_id.
+ * The empty string is valid: the server skips empty ids.
+ */
+declare function isValidCorrelationId(id: string): boolean;
+/** A request_id monitor-core accepts: 16 hex characters. */
+declare function newRequestId(): string;
+/** A job_id monitor-core accepts: 16 hex characters. */
+declare function newJobId(): string;
+/** A trace_id monitor-core accepts: a hyphenated UUID v4. */
+declare function newTraceId(): string;
+
+export { type AxiosMonitorOptions, type EmitOptions, type LogLevel, Monitor, type MonitorConfig, type MonitorEvent, type MonitorStats, attachAxiosMonitor, isValidCorrelationId, newJobId, newRequestId, newTraceId };

package/dist/index.d.ts

@@ -2,9 +2,13 @@ type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
 interface MonitorConfig {
     /** Service name reported with every event */
     service: string;
-    /** Monitor ingest URL (e.g. https://monitor-ingest.appleby.cloud/v1/events) */
+    /** Full ingest endpoint of one zone (e.g. https://appleby-monitor-api.appleby.cloud/v1/events) */
     ingestUrl: string;
-    /** API key for authentication */
+    /**
+     * Ingest-scoped API key, minted on the zone ingestUrl points at. In a
+     * browser bundle this value is public — anyone who loads the page can read
+     * it — so prefer posting to a same-origin route that forwards server-side.
+     */
     apiKey: string;
     /** Environment name (default: "production") */
     env?: string;
@@ -26,6 +30,12 @@ interface MonitorConfig {
      * and `client.error.unhandled_rejection`. Default: [] (no filtering).
      */
     ignoreErrors?: (string | RegExp)[];
+    /**
+     * Called with the running total whenever events are lost: queue overflow,
+     * data that cannot be serialized, events ingest rejected as malformed, or a
+     * refused API key. Keep it cheap — bump a counter. A throw is swallowed.
+     */
+    onDrop?: (total: number) => void;
 }
 interface MonitorEvent {
     timestamp: string;
@@ -49,21 +59,43 @@ interface EmitOptions {
     /** Arbitrary data payload */
     data?: Record<string, unknown>;
 }
+/** Lifetime counters for one Monitor instance. */
+interface MonitorStats {
+    /** Events accepted into the queue. */
+    enqueued: number;
+    /** Events the ingest endpoint accepted. */
+    flushed: number;
+    /** Events lost for good: overflow, unserializable, malformed, or refused credentials. */
+    dropped: number;
+    /** The part of `dropped` ingest refused as malformed even when sent alone. */
+    quarantined: number;
+    /** Events currently waiting in the queue. */
+    queued: number;
+}
 
 declare class Monitor {
     private config;
     private ignoreErrors;
+    private onDrop?;
     private queue;
     private timer;
     private userId;
     private jobId;
     private active;
+    private backoffUntil;
+    private failures;
+    private warnedMisconfigured;
+    private counters;
     constructor(config: MonitorConfig);
     /** Set a persistent user ID for all subsequent events */
     setUser(userId: string): void;
     /** Clear the user ID */
     clearUser(): void;
-    /** Set a persistent job ID (session-level identifier) */
+    /**
+     * Set a persistent job ID (session-level identifier). It must be a UUID or
+     * 8-64 hex characters — see `isValidCorrelationId`; anything else is
+     * cleared from each event and kept in data.invalid_job_id.
+     */
     setJobId(jobId: string): void;
     /** Emit an event at a specific level */
     emit(name: string, level: LogLevel, opts?: EmitOptions): void;
@@ -77,16 +109,61 @@ declare class Monitor {
     error(name: string, opts?: EmitOptions): void;
     /** Emit a fatal event */
     fatal(name: string, opts?: EmitOptions): void;
+    /**
+     * Lifetime counters. Surface them wherever loss would otherwise go
+     * unnoticed: the system that would report dropped telemetry is the one
+     * dropping it.
+     */
+    stats(): MonitorStats;
     /** Flush all queued events to the ingest endpoint */
     flush(): void;
     /** Stop the monitor and flush remaining events */
     shutdown(): void;
+    /**
+     * @param unloading the page (or process) is going away: ignore the backoff,
+     * since this is the last chance these events get.
+     */
+    private flushQueue;
+    private send;
+    private handleResponse;
+    /** Put events back at the front of the queue and back off before retrying. */
+    private retryLater;
+    /**
+     * One NDJSON line for e, or null if it cannot be serialized. Never throws:
+     * flush runs inside emit's auto-flush, and emit must never throw into the
+     * caller.
+     */
+    private serialize;
+    private recordDrop;
     private start;
     private handleVisibilityChange;
     private handlePageHide;
     private shouldIgnoreError;
+    /**
+     * The route a browser error happened on.
+     *
+     * Deliberately `pathname` only — never the search string or hash. Query
+     * parameters routinely carry tokens, emails and other personal data, and this
+     * value is both stored on the event and folded into the server-side issue
+     * fingerprint, so anything included here is retained and grouped on.
+     *
+     * Returns undefined outside a browser so the Node handlers stay unaffected.
+     */
+    private currentPath;
     private errorHandler;
     private rejectionHandler;
+    /** Grace for the final batch to leave before a Node-style crash exits. */
+    private static readonly NODE_CRASH_GRACE_MS;
+    /** Rejections already reported, so the re-raise below is not reported twice. */
+    private reportedRejections;
+    private nodeExceptionHandler;
+    private nodeRejectionHandler;
+    /** Hand an unhandled rejection back to Node as an uncaught exception. */
+    private reraise;
+    /** True when this instance's own handler is the only listener for the event. */
+    private isSoleListener;
+    /** Print the error as Node would, give the batch a moment to leave, exit 1. */
+    private crashLikeNode;
     private installErrorHandler;
     private installRejectionHandler;
     private removeListeners;
@@ -119,4 +196,16 @@ interface AxiosMonitorOptions {
  */
 declare function attachAxiosMonitor(axiosInstance: AxiosInstance, monitor: Monitor, opts?: AxiosMonitorOptions): void;
 
-export { type AxiosMonitorOptions, type EmitOptions, type LogLevel, Monitor, type MonitorConfig, type MonitorEvent, attachAxiosMonitor };
+/**
+ * Whether monitor-core would accept `id` as a job_id, request_id or trace_id.
+ * The empty string is valid: the server skips empty ids.
+ */
+declare function isValidCorrelationId(id: string): boolean;
+/** A request_id monitor-core accepts: 16 hex characters. */
+declare function newRequestId(): string;
+/** A job_id monitor-core accepts: 16 hex characters. */
+declare function newJobId(): string;
+/** A trace_id monitor-core accepts: a hyphenated UUID v4. */
+declare function newTraceId(): string;
+
+export { type AxiosMonitorOptions, type EmitOptions, type LogLevel, Monitor, type MonitorConfig, type MonitorEvent, type MonitorStats, attachAxiosMonitor, isValidCorrelationId, newJobId, newRequestId, newTraceId };