@chaja/sdk-node 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @chaja/sdk-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Error tracking for Node.js 22+, reporting to a self-hosted [Chajá](https://github.com/emiliodominguez/chaja) server.
+
+```sh
+pnpm add @chaja/sdk-node
+```
+
+```ts
+import { expressErrorHandler, init } from "@chaja/sdk-node";
+
+init({ endpoint: process.env.CHAJA_URL!, key: process.env.CHAJA_KEY!, service: "api", release: process.env.RELEASE });
+
+app.use(expressErrorHandler());
+```
+
+Uncaught exceptions and unhandled rejections are reported with source context. Events that cannot be delivered can be kept on
+disk (`offlineDirectory`) and resent on the next start. For Hono, Next.js route handlers and other Fetch-API servers, use
+`captureRequestError(error, request)`. A desktop app's main process passes `sessionId` for its run, and events or errors
+recorded while offline keep their time with `timestamp`. All options: [docs/sdk.md](https://github.com/emiliodominguez/chaja/blob/main/docs/sdk.md).

package/dist/index.d.mts

@@ -0,0 +1,176 @@
+import { BreadcrumbInput, CaptureContext, CaptureContext as CaptureContext$1, Client, Client as Client$1, ClientOptions, ClientOptions as ClientOptions$1 } from "@chaja/sdk-core";
+//#region ../protocol/src/wire.d.ts
+type AttributeScalar = string | number | boolean;
+type AttributeValue = AttributeScalar | AttributeScalar[];
+type Attributes = Record<string, AttributeValue>;
+interface RequestInfo {
+  url?: string;
+  method?: string;
+  headers?: Record<string, string>;
+}
+//#endregion
+//#region src/index.d.ts
+export interface NodeOptions extends ClientOptions$1 {
+  /**
+   * Capture `uncaughtException` and `unhandledRejection`. Default true.
+   */
+  processHandlers?: boolean;
+  /**
+   * Exit with code 1 after reporting an uncaught exception (Node's default behaviour). Default true.
+   */
+  exitOnUncaught?: boolean;
+  /**
+   * Directory where envelopes that could not be delivered are kept and retried on the next start.
+   */
+  offlineDirectory?: string;
+  /**
+   * Lines of source code around in-app frames. Default 5; 0 disables.
+   */
+  contextLines?: number;
+  /**
+   * HTTP client (tests inject one). Defaults to global fetch.
+   */
+  fetch?: typeof fetch;
+  /**
+   * Session of this process's run, for apps where one run is one session (a desktop app's main process). Events carry it
+   * and errors carry it as `session.id`, so release health counts sessions and crashes. Servers acting for many people
+   * leave it unset.
+   */
+  sessionId?: string;
+}
+export interface NodeClient extends Client$1 {
+  close(timeoutMs?: number): Promise<boolean>;
+  /**
+   * The HTTP client the SDK sends with.
+   */
+  readonly fetch: typeof fetch;
+}
+/**
+ * Start the Node SDK.
+ *
+ * @param options - SDK options.
+ * @returns The client; calling `init` again replaces it.
+ */
+export declare function init(options: NodeOptions): NodeClient;
+/**
+ * The parts of an Express, Fastify or `http.IncomingMessage` request the SDK reads.
+ */
+export interface NodeRequestLike {
+  method?: string;
+  url?: string;
+  originalUrl?: string;
+  headers?: Record<string, string | string[] | undefined>;
+}
+/**
+ * Request details from a Node-style request object, without the body.
+ *
+ * @param request - Incoming request.
+ * @returns Request info.
+ */
+export declare function requestInfo(request: NodeRequestLike): RequestInfo;
+export type ExpressErrorHandler = (error: unknown, request: NodeRequestLike, response: unknown, next: (error?: unknown) => void) => void;
+/**
+ * Express error middleware: reports the error with request details, then passes it on.
+ *
+ * @param client - Client; defaults to the one from `init`.
+ * @returns Express error handler.
+ */
+export declare function expressErrorHandler(client?: Client$1): ExpressErrorHandler;
+/**
+ * Report an error from a Fetch-API style request (Hono, Next.js route handlers, Bun, Deno).
+ *
+ * @param error - Thrown value.
+ * @param request - Web request.
+ * @param context - Extra context.
+ * @returns Event id, if sent.
+ */
+export declare function captureRequestError(error: unknown, request: Request, context?: CaptureContext$1): string | undefined;
+/**
+ * Capture an error with the client from `init`.
+ *
+ * @param error - Thrown value.
+ * @param context - Extra context.
+ * @returns Event id, if sent.
+ */
+export declare function captureException(error: unknown, context?: CaptureContext$1): string | undefined;
+/**
+ * Capture a message with the client from `init`.
+ *
+ * @param message - Message.
+ * @param level - Level.
+ * @param context - Extra context.
+ * @returns Event id, if sent.
+ */
+export declare function captureMessage(message: string, level?: Parameters<Client$1["captureMessage"]>[1], context?: CaptureContext$1): string | undefined;
+export interface ServerEvent {
+  /**
+   * Your id for the person who did it, the same one the browser SDK passes to `identify`.
+   */
+  distinctId: string;
+  /**
+   * Event name, such as `subscription_renewed`.
+   */
+  name: string;
+  properties?: Attributes;
+  /**
+   * Person properties to set.
+   */
+  set?: Attributes;
+  /**
+   * Person properties to set only when the person does not have them yet.
+   */
+  setOnce?: Attributes;
+  /**
+   * When it happened, in epoch milliseconds, if earlier than now.
+   */
+  timestamp?: number;
+  /**
+   * The session it belongs to.
+   */
+  sessionId?: string;
+}
+/**
+ * Record a product analytics event for a person with the client from `init`. Servers act for many people, so every event
+ * names its person.
+ *
+ * @param event - Person, name and properties.
+ * @returns Event id, if sent.
+ * @example
+ * capture({ distinctId: user.id, name: "subscription_renewed", properties: { plan: "pro" } });
+ */
+export declare function capture(event: ServerEvent): string | undefined;
+/**
+ * Send queued events.
+ *
+ * @param timeoutMs - Maximum wait.
+ * @returns Whether everything was sent.
+ */
+export declare function flush(timeoutMs?: number): Promise<boolean>;
+/**
+ * The client created by `init`, if any.
+ *
+ * @returns Current client.
+ */
+export declare function getClient(): NodeClient | undefined;
+/**
+ * Feature flags for a person, with the client from `init`, cached for 30 seconds per person and properties.
+ *
+ * @param distinctId - Your id for the person.
+ * @param properties - Properties the flags' conditions may test, on top of what product analytics knows about them.
+ * @returns Flag values: `false`, `true` or a variant key; empty when the server cannot be reached.
+ * @example
+ * const flags = await getFeatureFlags(user.id, { plan: user.plan });
+ * if (flags["new-checkout"]) { ... }
+ */
+export declare function getFeatureFlags(distinctId: string, properties?: Attributes): Promise<Record<string, boolean | string>>;
+/**
+ * Whether a flag is on for a person (a variant counts as on), with the client from `init`.
+ *
+ * @param key - Flag key.
+ * @param distinctId - Your id for the person.
+ * @param properties - Properties for the flag's conditions.
+ * @returns True when on.
+ */
+export declare function isFeatureEnabled(key: string, distinctId: string, properties?: Attributes): Promise<boolean>;
+//#endregion
+export type { BreadcrumbInput, CaptureContext, Client, ClientOptions };

package/dist/index.mjs

@@ -0,0 +1,431 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SDK_VERSION, createClient, parseRetryAfter } from "@chaja/sdk-core";
+//#region src/index.ts
+const SOURCE_CACHE_LIMIT = 100;
+const MAX_LINE = 300;
+let current;
+/**
+* Shorten long source lines.
+*
+* @param text - Source line.
+* @returns Clipped line.
+*/
+function clip(text) {
+	return text.slice(0, MAX_LINE);
+}
+/**
+* Whether a scheduled handle is a Node timer.
+*
+* @param handle - Handle from `schedule`.
+* @returns True for timers.
+*/
+function isTimer(handle) {
+	return typeof handle === "object" && handle !== null && "unref" in handle;
+}
+/**
+* Read source lines for frames, caching files and skipping dependencies.
+*
+* @param lines - Context lines per side.
+* @returns Frame enricher.
+*/
+function sourceContext(lines) {
+	const cache = /* @__PURE__ */ new Map();
+	/**
+	* Lines of a file, or null when unreadable.
+	*
+	* @param filename - Absolute path or file URL.
+	* @returns Lines.
+	*/
+	function read(filename) {
+		if (cache.has(filename)) return cache.get(filename) ?? null;
+		let content = null;
+		try {
+			const path = filename.startsWith("file://") ? fileURLToPath(filename) : filename;
+			content = readFileSync(path, "utf8").split(/\r?\n/u);
+		} catch {
+			content = null;
+		}
+		if (cache.size >= SOURCE_CACHE_LIMIT) cache.clear();
+		cache.set(filename, content);
+		return content;
+	}
+	return function withContext(frame) {
+		const { filename, lineno } = frame;
+		if (lines <= 0 || !filename || !lineno || filename.includes("node_modules") || filename.startsWith("node:") || !/^(?:\/|file:\/\/|[a-z]:\\)/iu.test(filename)) return frame;
+		const source = read(filename);
+		const line = source?.[lineno - 1];
+		if (!source || line === void 0) return frame;
+		return {
+			...frame,
+			contextLine: clip(line),
+			preContext: source.slice(Math.max(0, lineno - 1 - lines), lineno - 1).map(clip),
+			postContext: source.slice(lineno, lineno + lines).map(clip)
+		};
+	};
+}
+/**
+* Whether a frame is application code.
+*
+* @param frame - Frame.
+* @returns In-app flag.
+*/
+function inApp(frame) {
+	const filename = frame.filename ?? "";
+	return !filename.includes("node_modules") && !filename.startsWith("node:") && !filename.startsWith("internal/");
+}
+/**
+* Start the Node SDK.
+*
+* @param options - SDK options.
+* @returns The client; calling `init` again replaces it.
+*/
+function init(options) {
+	current?.close(0);
+	const send = options.fetch ?? fetch;
+	const envelopeUrl = `${options.endpoint.replace(/\/+$/u, "")}/api/v1/envelope`;
+	const withContext = sourceContext(options.contextLines ?? 5);
+	const cleanups = [];
+	const transport = { async send(body) {
+		try {
+			const response = await send(envelopeUrl, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					"x-chaja-key": options.key
+				},
+				body,
+				signal: AbortSignal.timeout(1e4)
+			});
+			const retry = parseRetryAfter(response.headers.get("retry-after"));
+			return {
+				status: response.status,
+				...retry === void 0 ? {} : { retryAfterSeconds: retry }
+			};
+		} catch {
+			return { status: 0 };
+		}
+	} };
+	const client = createClient(options, {
+		sdk: {
+			name: "chaja.javascript.node",
+			version: SDK_VERSION
+		},
+		platform: "node",
+		transport,
+		eventId() {
+			return randomUUID().replaceAll("-", "");
+		},
+		now: Date.now,
+		random: Math.random,
+		...options.sessionId === void 0 ? {} : { session: runSession(options.sessionId) },
+		schedule(callback, delayMs) {
+			const handle = setTimeout(callback, delayMs);
+			handle.unref();
+			return handle;
+		},
+		cancel(handle) {
+			if (isTimer(handle)) clearTimeout(handle);
+		},
+		enrich(item) {
+			return {
+				...item,
+				...item.exceptions ? { exceptions: item.exceptions.map(function exception(entry) {
+					return {
+						...entry,
+						frames: entry.frames.map(function frame(value) {
+							return withContext({
+								...value,
+								inApp: value.inApp ?? inApp(value)
+							});
+						})
+					};
+				}) } : {},
+				attributes: {
+					"process.runtime.version": process.version,
+					"host.arch": process.arch,
+					"os.type": process.platform,
+					...item.attributes
+				}
+			};
+		},
+		...options.offlineDirectory ? { onUndeliverable: persist(options.offlineDirectory) } : {}
+	});
+	if (options.processHandlers !== false) {
+		/**
+		* Report an uncaught exception, flush and exit like Node would.
+		*
+		* @param error - Uncaught error.
+		*/
+		function onUncaught(error) {
+			client.captureException(error, {
+				level: "fatal",
+				mechanism: {
+					type: "uncaughtException",
+					handled: false
+				}
+			});
+			if (options.exitOnUncaught !== false) client.flush(2e3).finally(function exit() {
+				process.exit(1);
+			});
+		}
+		/**
+		* Report an unhandled promise rejection.
+		*
+		* @param reason - Rejection reason.
+		*/
+		function onRejection(reason) {
+			client.captureException(reason, { mechanism: {
+				type: "unhandledRejection",
+				handled: false
+			} });
+		}
+		process.on("uncaughtException", onUncaught);
+		process.on("unhandledRejection", onRejection);
+		cleanups.push(function remove() {
+			process.off("uncaughtException", onUncaught);
+			process.off("unhandledRejection", onRejection);
+		});
+	}
+	if (options.offlineDirectory) replay(options.offlineDirectory, transport);
+	const instance = {
+		...client,
+		fetch: send,
+		async close(timeoutMs = 2e3) {
+			for (const cleanup of cleanups.splice(0)) cleanup();
+			if (current === instance) current = void 0;
+			return client.flush(timeoutMs);
+		}
+	};
+	current = instance;
+	return instance;
+}
+/**
+* A session that lasts the whole run: `reset` (sign-out) keeps it, since the run goes on.
+*
+* @param id - Session id.
+* @returns The platform's session hooks.
+*/
+function runSession(id) {
+	return {
+		current() {
+			return id;
+		},
+		reset() {}
+	};
+}
+/**
+* Persist undeliverable envelopes as files.
+*
+* @param directory - Offline directory.
+* @returns Callback for the queue.
+*/
+function persist(directory) {
+	return function save(body) {
+		try {
+			mkdirSync(directory, { recursive: true });
+			writeFileSync(join(directory, `${Date.now()}-${randomUUID()}.json`), body);
+		} catch {}
+	};
+}
+/**
+* Resend envelopes saved by a previous run, deleting the ones the server accepted or rejected for good.
+*
+* @param directory - Offline directory.
+* @param transport - Transport.
+*/
+function replay(directory, transport) {
+	if (!existsSync(directory)) return;
+	(async function resend() {
+		for (const name of readdirSync(directory).filter(isEnvelopeFile).toSorted()) {
+			const path = join(directory, name);
+			const result = await transport.send(readFileSync(path, "utf8"));
+			if (result.status === 0 || result.status === 429 || result.status >= 500) return;
+			rmSync(path, { force: true });
+		}
+	})();
+}
+/**
+* Whether a file name looks like a saved envelope.
+*
+* @param name - File name.
+* @returns True for `.json` files.
+*/
+function isEnvelopeFile(name) {
+	return name.endsWith(".json");
+}
+/**
+* Request details from a Node-style request object, without the body.
+*
+* @param request - Incoming request.
+* @returns Request info.
+*/
+function requestInfo(request) {
+	const headers = {};
+	for (const [key, value] of Object.entries(request.headers ?? {})) if (value !== void 0) headers[key] = Array.isArray(value) ? value.join(", ") : value;
+	return {
+		...request.method ? { method: request.method } : {},
+		...request.originalUrl ?? request.url ? { url: request.originalUrl ?? request.url } : {},
+		headers
+	};
+}
+/**
+* Express error middleware: reports the error with request details, then passes it on.
+*
+* @param client - Client; defaults to the one from `init`.
+* @returns Express error handler.
+*/
+function expressErrorHandler(client) {
+	return function chajaErrorHandler(error, request, _response, next) {
+		(client ?? current)?.captureException(error, {
+			request: requestInfo(request),
+			mechanism: {
+				type: "express",
+				handled: false
+			}
+		});
+		next(error);
+	};
+}
+/**
+* Report an error from a Fetch-API style request (Hono, Next.js route handlers, Bun, Deno).
+*
+* @param error - Thrown value.
+* @param request - Web request.
+* @param context - Extra context.
+* @returns Event id, if sent.
+*/
+function captureRequestError(error, request, context = {}) {
+	const headers = {};
+	request.headers.forEach(function copy(value, key) {
+		headers[key] = value;
+	});
+	return current?.captureException(error, {
+		...context,
+		request: {
+			method: request.method,
+			url: request.url,
+			headers
+		},
+		mechanism: context.mechanism ?? {
+			type: "request",
+			handled: false
+		}
+	});
+}
+/**
+* Capture an error with the client from `init`.
+*
+* @param error - Thrown value.
+* @param context - Extra context.
+* @returns Event id, if sent.
+*/
+function captureException(error, context) {
+	return current?.captureException(error, context);
+}
+/**
+* Capture a message with the client from `init`.
+*
+* @param message - Message.
+* @param level - Level.
+* @param context - Extra context.
+* @returns Event id, if sent.
+*/
+function captureMessage(message, level, context) {
+	return current?.captureMessage(message, level, context);
+}
+/**
+* Record a product analytics event for a person with the client from `init`. Servers act for many people, so every event
+* names its person.
+*
+* @param event - Person, name and properties.
+* @returns Event id, if sent.
+* @example
+* capture({ distinctId: user.id, name: "subscription_renewed", properties: { plan: "pro" } });
+*/
+function capture(event) {
+	return current?.capture(event.name, event.properties, {
+		distinctId: event.distinctId,
+		...event.set ? { set: event.set } : {},
+		...event.setOnce ? { setOnce: event.setOnce } : {},
+		...event.timestamp === void 0 ? {} : { timestamp: event.timestamp },
+		...event.sessionId === void 0 ? {} : { sessionId: event.sessionId }
+	});
+}
+/**
+* Send queued events.
+*
+* @param timeoutMs - Maximum wait.
+* @returns Whether everything was sent.
+*/
+async function flush(timeoutMs) {
+	return current ? current.flush(timeoutMs) : true;
+}
+/**
+* The client created by `init`, if any.
+*
+* @returns Current client.
+*/
+function getClient() {
+	return current;
+}
+const FLAG_CACHE_MS = 3e4;
+const flagCache = /* @__PURE__ */ new Map();
+/**
+* Feature flags for a person, with the client from `init`, cached for 30 seconds per person and properties.
+*
+* @param distinctId - Your id for the person.
+* @param properties - Properties the flags' conditions may test, on top of what product analytics knows about them.
+* @returns Flag values: `false`, `true` or a variant key; empty when the server cannot be reached.
+* @example
+* const flags = await getFeatureFlags(user.id, { plan: user.plan });
+* if (flags["new-checkout"]) { ... }
+*/
+async function getFeatureFlags(distinctId, properties = {}) {
+	const client = current;
+	if (!client) return {};
+	const cacheKey = JSON.stringify([distinctId, properties]);
+	const cached = flagCache.get(cacheKey);
+	if (cached && Date.now() - cached.at < FLAG_CACHE_MS) return cached.flags;
+	try {
+		const response = await client.fetch(`${client.options.endpoint.replace(/\/+$/u, "")}/api/v1/flags`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"x-chaja-key": client.options.key
+			},
+			body: JSON.stringify({
+				distinctId,
+				properties
+			}),
+			signal: AbortSignal.timeout(5e3)
+		});
+		const body = response.ok ? await response.json() : void 0;
+		const raw = typeof body === "object" && body !== null && "flags" in body && typeof body.flags === "object" && body.flags !== null ? body.flags : {};
+		const flags = {};
+		for (const [key, value] of Object.entries(raw)) if (typeof value === "boolean" || typeof value === "string") flags[key] = value;
+		flagCache.set(cacheKey, {
+			at: Date.now(),
+			flags
+		});
+		return flags;
+	} catch {
+		return cached?.flags ?? {};
+	}
+}
+/**
+* Whether a flag is on for a person (a variant counts as on), with the client from `init`.
+*
+* @param key - Flag key.
+* @param distinctId - Your id for the person.
+* @param properties - Properties for the flag's conditions.
+* @returns True when on.
+*/
+async function isFeatureEnabled(key, distinctId, properties = {}) {
+	const value = (await getFeatureFlags(distinctId, properties))[key];
+	return value !== void 0 && value !== false;
+}
+//#endregion
+export { capture, captureException, captureMessage, captureRequestError, expressErrorHandler, flush, getClient, getFeatureFlags, init, isFeatureEnabled, requestInfo };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@chaja/sdk-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Chajá error tracking for Node.js: process handlers, source context, offline buffer, Express and Fetch helpers.",
+  "keywords": [
+    "chaja",
+    "error-tracking",
+    "observability",
+    "node",
+    "sdk"
+  ],
+  "homepage": "https://github.com/emiliodominguez/chaja#readme",
+  "bugs": "https://github.com/emiliodominguez/chaja/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emiliodominguez/chaja.git",
+    "directory": "packages/sdk-node"
+  },
+  "type": "module",
+  "nx": {
+    "tags": [
+      "scope:sdk",
+      "type:sdk"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@chaja/protocol": "0.0.0",
+    "tsdown": "0.23.0"
+  },
+  "dependencies": {
+    "@chaja/sdk-core": "0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean --out-dir dist",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }