@pmate/log-sdk 0.1.0 → 0.2.1

package/README.md

@@ -53,3 +53,26 @@ Use authenticatedProfile from server authentication, never a client body/header.
 
 ## Counting
 The envelope `id` is the event deduplication key. PV counts pv events; sessions deduplicate `(appId, accessId)`; Profile UV deduplicates `(appId, profileId)` in a defined time window/topic. Missing identifiers are reported separately. Never count HTTP requests or vitals as page views, or infer first-ever visits from a limited retention window.
+
+## Error and crash diagnostics
+
+Caught exceptions need explicit reporting; a global rejection listener cannot see
+an exception already handled by application code. Use `log.captureError(error,
+{ operation: 'chat.send' })` on browser, React and Node loggers. Error records use
+the `error` topic and include bounded message/stack diagnostics with URL queries
+removed. Applications must redact domain-specific sensitive strings before
+calling this method.
+
+Inside `LogProvider`, wrap the application in `LogErrorBoundary` with a `fallback`
+React node. It reports descendant render/lifecycle failures with component stacks.
+Event handlers, asynchronous operations and errors above the boundary require
+separate reporting. Explicitly allowlisted `log.fetch` requests report non-2xx and
+network failures without bodies or request URLs.
+
+Node exports `installCrashReporter({ directory, send })`. Install it before
+starting the service. It monitors fatal exceptions without suppressing Node's
+fatal exit, persists up to 20 records, and exposes `replay()` for startup recovery.
+The `send(entry)` callback must resolve only after server acknowledgement, retain
+entry ID/time, and route records to the service's `crash` topic. Failed uploads
+remain on disk. Use a service-specific private persistent directory. It cannot
+capture SIGKILL, OOM kills, native faults, or failures before installation.

package/dist/browser.d.ts

@@ -1,3 +1,4 @@
+import { errorInput } from "./errors.js";
 import { type BrowserLogOptions } from "@pmate/log";
 import { type LogContext, type LogInput } from "./shared.js";
 export type BrowserLoggerOptions = BrowserLogOptions & {
@@ -8,6 +9,7 @@ export type BrowserLoggerOptions = BrowserLogOptions & {
 export type BrowserLogger = ReturnType<typeof createLogger>;
 /** Own one instance per application document. Server imports never touch window. */
 export declare function createLogger(options: BrowserLoggerOptions): {
+    captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
     getContext: () => LogContext;
     setProfileId(value?: string | null): void;
     append(topic: string, input: LogInput | string): void;

package/dist/browser.js

@@ -1,3 +1,4 @@
+import { errorInput } from "./errors.js";
 import { createLogger as createTransport } from "@pmate/log";
 import { createAccessSession } from "./access.js";
 import { ACCESS_HEADER, PROFILE_HEADER, REQUEST_HEADER, validId, validateAppId, withContext } from "./shared.js";
@@ -61,6 +62,9 @@ export function createLogger(options) {
         throw error;
     }
     return {
+        captureError(error, context) {
+            this.append("error", errorInput(error, context));
+        },
         getContext: context,
         setProfileId(value) {
             if (closed)
@@ -93,7 +97,14 @@ export function createLogger(options) {
                 if (!validId(headers.get(REQUEST_HEADER)))
                     headers.set(REQUEST_HEADER, crypto.randomUUID());
                 // Refuse redirects so correlation headers cannot leak to another origin.
-                return fetch(input, { ...init, headers, redirect: "error" });
+                return fetch(input, { ...init, headers, redirect: "error" }).then(response => {
+                    if (!response.ok)
+                        transport.append("error", { data: { event: "http.client.failed", origin: url.origin, status: response.status, requestId: headers.get(REQUEST_HEADER), serverRequestId: response.headers.get(REQUEST_HEADER) } });
+                    return response;
+                }, error => {
+                    transport.append("error", errorInput(error, { operation: "http.fetch" }));
+                    throw error;
+                });
             }
             return fetch(input, init);
         },

package/dist/crash.d.ts

@@ -0,0 +1,9 @@
+import type { LogEntry } from "./shared.js";
+/** Monitor (never swallow) fatal exceptions. Replay requires an acknowledged sink. */
+export declare function installCrashReporter(options: {
+    directory: string;
+    send: (entry: LogEntry) => Promise<void>;
+}): {
+    replay(): Promise<void>;
+    close(): void;
+};

package/dist/crash.js

@@ -0,0 +1,34 @@
+import { mkdirSync, writeFileSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { errorInput } from "./errors.js";
+/** Monitor (never swallow) fatal exceptions. Replay requires an acknowledged sink. */
+export function installCrashReporter(options) {
+    mkdirSync(options.directory, { recursive: true, mode: 0o700 });
+    const files = () => readdirSync(options.directory).filter(name => /^crash-[a-f0-9-]+\.json$/.test(name)).sort();
+    const monitor = (error, origin) => {
+        try {
+            const id = randomUUID();
+            const entry = { id, time: Date.now(), ...errorInput(error, { operation: origin, fatal: true }) };
+            // Bound on-disk admission while preserving the newest fatal diagnostic.
+            for (const name of files().slice(0, Math.max(0, files().length - 19)))
+                unlinkSync(join(options.directory, name));
+            writeFileSync(join(options.directory, `crash-${id}.json`), JSON.stringify(entry), { mode: 0o600, flag: "wx" });
+        }
+        catch {
+            process.stderr.write("PMate crash persistence failed\n");
+        }
+    };
+    process.on("uncaughtExceptionMonitor", monitor);
+    return {
+        async replay() {
+            for (const name of files()) {
+                const file = join(options.directory, name);
+                const entry = JSON.parse(readFileSync(file, "utf8"));
+                await options.send(entry);
+                unlinkSync(file); // Only after explicit acknowledgement; keep ID/time on retry.
+            }
+        },
+        close() { process.off("uncaughtExceptionMonitor", monitor); },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import { type LogInput } from "./shared.js";
+/** Bound diagnostic strings and strip URL parameters before transport. */
+export declare function errorInput(error: unknown, context?: {
+    operation?: string;
+    componentStack?: string;
+    fatal?: boolean;
+}): LogInput;

package/dist/errors.js

@@ -0,0 +1,22 @@
+import { redact } from "./shared.js";
+/** Bound diagnostic strings and strip URL parameters before transport. */
+export function errorInput(error, context = {}) {
+    const clean = (value) => String(redact(value)).replace(/https?:\/\/[^\s)]+/g, value => {
+        try {
+            const url = new URL(value);
+            return `${url.origin}${url.pathname}`;
+        }
+        catch {
+            return "[url]";
+        }
+    }).slice(0, 4000);
+    const value = error instanceof Error ? error : new Error("Non-Error exception");
+    return { data: {
+            event: context.fatal ? "runtime.crash" : "runtime.error",
+            errorName: clean(value.name), message: clean(value.message),
+            ...(value.stack ? { stack: clean(value.stack) } : {}),
+            ...(context.operation ? { operation: context.operation } : {}),
+            ...(context.componentStack ? { componentStack: clean(context.componentStack) } : {}),
+            fatal: context.fatal ?? false,
+        } };
+}

package/dist/node.d.ts

@@ -1,3 +1,4 @@
+import { errorInput } from "./errors.js";
 import { type LogContext, type LogEntry, type LogInput } from "./shared.js";
 export type LogBatch = {
     serviceId: string;
@@ -21,6 +22,7 @@ export type NodeLoggerOptions = {
     }) => void;
 };
 export declare function createLogger(options: NodeLoggerOptions): {
+    captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
     getContext: () => LogContext;
     /** verifiedProfile comes from server authentication, never request headers/body. */
     withRequest<T>(request: Request, verifiedProfile: {
@@ -30,3 +32,4 @@ export declare function createLogger(options: NodeLoggerOptions): {
     flush: () => Promise<void>;
     close(): Promise<void>;
 };
+export { installCrashReporter } from "./crash.js";

package/dist/node.js

@@ -1,3 +1,4 @@
+import { errorInput } from "./errors.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { ACCESS_HEADER, REQUEST_HEADER, redact, validId, validateAppId, withContext } from "./shared.js";
@@ -83,6 +84,9 @@ export function createLogger(options) {
     const timer = setInterval(() => { void flush(); }, Math.max(1000, options.flushIntervalMs ?? 5000));
     timer.unref();
     return {
+        captureError(error, context) {
+            this.append("error", errorInput(error, context));
+        },
         getContext: () => context.getStore() ?? anonymous,
         /** verifiedProfile comes from server authentication, never request headers/body. */
         withRequest(request, verifiedProfile, run) {
@@ -126,3 +130,4 @@ export function createLogger(options) {
         } },
     };
 }
+export { installCrashReporter } from "./crash.js";

package/dist/react.d.ts

@@ -1,6 +1,6 @@
-import { type ReactNode } from "react";
+import { Component, type ErrorInfo, type ReactNode } from "react";
 import { type BrowserLogger, type BrowserLoggerOptions } from "./browser.js";
-export type ReactLogger = Pick<BrowserLogger, "append" | "fetch" | "flush">;
+export type ReactLogger = Pick<BrowserLogger, "append" | "fetch" | "flush" | "captureError">;
 /** Keep options stable for the Provider's lifetime. Update identity through profileId. */
 export declare function LogProvider({ options, profileId, children }: {
     options: Omit<BrowserLoggerOptions, "profileId">;
@@ -8,3 +8,21 @@ export declare function LogProvider({ options, profileId, children }: {
     children: ReactNode;
 }): import("react").FunctionComponentElement<import("react").ProviderProps<ReactLogger | null>>;
 export declare function useLog(): ReactLogger;
+/** Place inside LogProvider; catches render/lifecycle failures of descendants. */
+export declare class LogErrorBoundary extends Component<{
+    children: ReactNode;
+    fallback: ReactNode;
+}, {
+    failed: boolean;
+}> {
+    static contextType: import("react").Context<ReactLogger | null>;
+    context: ReactLogger | null;
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}

package/dist/react.js

@@ -1,5 +1,6 @@
-import { createContext, createElement, useContext, useEffect, useMemo, useRef } from "react";
+import { Component, createContext, createElement, useContext, useEffect, useMemo, useRef } from "react";
 import { createLogger } from "./browser.js";
+import { errorInput } from "./errors.js";
 const Context = createContext(null);
 /** Keep options stable for the Provider's lifetime. Update identity through profileId. */
 export function LogProvider({ options, profileId, children }) {
@@ -15,6 +16,7 @@ export function LogProvider({ options, profileId, children }) {
     const buffered = useRef([]);
     identity.current = profileId;
     const value = useMemo(() => ({
+        captureError(error, context) { value.append("error", errorInput(error, context)); },
         append(topic, input) {
             if (logger.current) {
                 logger.current.setProfileId(identity.current);
@@ -78,3 +80,17 @@ export function useLog() {
         throw Error("useLog requires LogProvider");
     return logger;
 }
+/** Place inside LogProvider; catches render/lifecycle failures of descendants. */
+export class LogErrorBoundary extends Component {
+    static contextType = Context;
+    state = { failed: false };
+    static getDerivedStateFromError() { return { failed: true }; }
+    componentDidCatch(error, info) {
+        try {
+            this.context?.append("error", errorInput(error, { operation: "react.render", componentStack: info.componentStack ?? undefined, fatal: true }));
+            void this.context?.flush().catch(() => { });
+        }
+        catch { /* Reporting must not crash the fallback. */ }
+    }
+    render() { return this.state.failed ? this.props.fallback : this.props.children; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/log-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "PMate browser, React and Node logs with access and profile context",
   "type": "module",
   "sideEffects": false,