@hellsoft/vaka-node 0.0.0-stage → 0.2.0

package/dist/integrations.d.ts

@@ -0,0 +1,45 @@
+import { Scope, type RequestInfo } from './scope';
+type Crumb = Parameters<Scope['addBreadcrumb']>[0];
+/** Breadcrumbs for console.warn/error and outgoing HTTP (fetch/undici and node:http). */
+export declare function installBreadcrumbs(endpoint: string, add: (b: Crumb) => void): void;
+export declare function uninstallIntegrations(): void;
+export interface ProcessHooks {
+    capture: (err: unknown, fatal: boolean, mechanism: string) => void;
+    flush: (ms: number) => Promise<unknown>;
+    /** 'strict' exits like Node's default; 'warn' logs and keeps running; 'none' only reports. */
+    unhandledRejection: 'strict' | 'warn' | 'none';
+    exitOnUncaught: boolean;
+    shutdownTimeoutMs: number;
+}
+export declare function installProcessHandlers(h: ProcessHooks): void;
+/** Node's own --unhandled-rejections setting, mapped to ours. */
+export declare function nodeRejectionMode(): 'strict' | 'warn' | 'none';
+export interface ReqLike {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    route?: {
+        path?: string;
+    };
+    routeOptions?: {
+        url?: string;
+    };
+    routerPath?: string;
+    protocol?: string;
+}
+export declare function requestInfo(req: ReqLike): RequestInfo;
+type Capture = (err: unknown, ctx: {
+    handled: boolean;
+    mechanism: string;
+    status?: number;
+}) => void;
+/** Express/Connect middleware: one scope per request. Mount it before your routes. */
+export declare function makeRequestHandler(): (req: ReqLike, _res: unknown, next: (err?: unknown) => void) => void;
+/** Express error middleware. Mount it after your routes and before other error handlers. */
+export declare function makeErrorHandler(capture: Capture, shouldCapture: (status: number) => boolean): (err: unknown, req: ReqLike, res: {
+    statusCode?: number;
+}, next: (err?: unknown) => void) => void;
+/** Fastify plugin: a scope per request and capture of errors from handlers and hooks. */
+export declare function makeFastifyPlugin(capture: Capture, shouldCapture: (status: number) => boolean): any;
+export {};

package/dist/otel.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from '@opentelemetry/api';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { type LogRecordProcessor } from '@opentelemetry/sdk-logs';
+import { type Span, type SpanProcessor } from '@opentelemetry/sdk-trace';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+export interface OtelConfig {
+    endpoint: string;
+    key: string;
+    serviceName?: string;
+    release?: string;
+    environment?: string;
+    tracesSampleRate: number;
+    logs: boolean;
+    instrumentations?: (Instrumentation | Instrumentation[])[];
+    resourceAttributes?: Record<string, string | number | boolean>;
+}
+/** An OTLP/HTTP (protobuf) span exporter that sends to Vaka. Use it with your own NodeSDK. */
+export declare function vakaSpanExporter(o: {
+    endpoint: string;
+    key: string;
+}): OTLPTraceExporter;
+/** A batching log record processor that sends OpenTelemetry logs to Vaka. */
+export declare function vakaLogRecordProcessor(o: {
+    endpoint: string;
+    key: string;
+}): LogRecordProcessor;
+/**
+ * Copies the current Vaka scope (user id, flags) onto every span as it starts, so traces can be
+ * filtered by user and split by flag variant.
+ */
+export declare class VakaScopeSpanProcessor implements SpanProcessor {
+    onStart(span: Span, _ctx: Context): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare function startOtel(c: OtelConfig): NodeSDK;

package/dist/register.cjs

@@ -0,0 +1,41 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/register.ts
+var nodeModule = __toESM(require("node:module"));
+var import_node_url = require("node:url");
+var import_index = require("./index.cjs");
+var import_meta = {};
+var register2 = nodeModule.register;
+if (register2 && process.env.VAKA_ESM_HOOK !== "0") {
+  try {
+    const parent = typeof __filename !== "undefined" ? (0, import_node_url.pathToFileURL)(__filename).href : import_meta.url;
+    register2("@opentelemetry/instrumentation/hook.mjs", parent);
+  } catch {
+  }
+}
+(0, import_index.init)({
+  tracesSampleRate: process.env.VAKA_TRACES_SAMPLE_RATE ? Number(process.env.VAKA_TRACES_SAMPLE_RATE) : void 0,
+  debug: process.env.VAKA_DEBUG === "1" || process.env.VAKA_DEBUG === "true"
+});

package/dist/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/register.mjs

@@ -0,0 +1,16 @@
+// src/register.ts
+import * as nodeModule from "node:module";
+import { pathToFileURL } from "node:url";
+import { init } from "./index.mjs";
+var register2 = nodeModule.register;
+if (register2 && process.env.VAKA_ESM_HOOK !== "0") {
+  try {
+    const parent = typeof __filename !== "undefined" ? pathToFileURL(__filename).href : import.meta.url;
+    register2("@opentelemetry/instrumentation/hook.mjs", parent);
+  } catch {
+  }
+}
+init({
+  tracesSampleRate: process.env.VAKA_TRACES_SAMPLE_RATE ? Number(process.env.VAKA_TRACES_SAMPLE_RATE) : void 0,
+  debug: process.env.VAKA_DEBUG === "1" || process.env.VAKA_DEBUG === "true"
+});

package/dist/scope.d.ts

@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export type Level = 'fatal' | 'error' | 'warning' | 'info';
+export interface Breadcrumb {
+    timestamp?: string;
+    category?: string;
+    type?: string;
+    message?: string;
+    level?: Level;
+    data?: Record<string, unknown>;
+}
+export interface User {
+    id: string;
+    [k: string]: unknown;
+}
+export interface RequestInfo {
+    method?: string;
+    url?: string;
+    route?: string;
+    query_string?: string;
+    headers?: Record<string, string>;
+}
+export declare const MAX_BREADCRUMBS = 100;
+/** Per-request (or global) state attached to everything captured while it is active. */
+export declare class Scope {
+    user?: User;
+    tags: Record<string, string>;
+    contexts: Record<string, Record<string, unknown>>;
+    breadcrumbs: Breadcrumb[];
+    flags: Record<string, string>;
+    request?: RequestInfo;
+    transaction?: string;
+    clone(): Scope;
+    addBreadcrumb(b: Breadcrumb, max?: number): void;
+}
+export declare const storage: AsyncLocalStorage<Scope>;
+export declare let globalScope: Scope;
+/** The scope of the current request, or the global scope outside one. */
+export declare function currentScope(): Scope;
+/**
+ * Run `fn` with a fresh scope that starts as a copy of the current one. Tags, user, breadcrumbs
+ * and flags set inside stay inside (per request when used in middleware).
+ */
+export declare function withScope<T>(fn: (scope: Scope) => T): T;
+export declare function _resetScopes(): void;

package/dist/stack.d.ts

@@ -0,0 +1,16 @@
+export interface Frame {
+    function?: string;
+    module?: string;
+    abs_path?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+}
+/** Parse a V8 (Node) stack string into frames, crash site first. */
+export declare function parseStack(stack: string | undefined, cwd?: string): Frame[];
+/** Add `context_line`, `pre_context` and `post_context` from disk to the first in-app frames. */
+export declare function addSourceContext(frames: Frame[], maxFrames?: number): Frame[];

package/dist/transport.d.ts

@@ -0,0 +1,33 @@
+export interface Item {
+    type: 'error' | 'event' | 'session' | 'span';
+    [k: string]: unknown;
+}
+export interface TransportOptions {
+    endpoint: string;
+    key: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    flushIntervalMs: number;
+    log: (...a: unknown[]) => void;
+}
+/** Batches items to `POST /ingest/v1/batch`, with backoff on 429/5xx and shutdown on 401. */
+export declare class Transport {
+    private o;
+    private queue;
+    private timer;
+    private backoffUntil;
+    private backoffMs;
+    private inflight;
+    disabled: boolean;
+    constructor(o: TransportOptions);
+    send(item: Item, urgent?: boolean): void;
+    private schedule;
+    private drain;
+    private post;
+    private retry;
+    /** Send everything queued now, waiting at most `timeoutMs`. Resolves true when all was sent. */
+    flush(timeoutMs?: number): Promise<boolean>;
+    pending(): number;
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@hellsoft/vaka-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "publishConfig": {"access": "public"},
+  "version": "0.2.0",
+  "description": "Vaka Node.js SDK: crash reporting, OpenTelemetry tracing and logs, feature flags",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ErikHellman/vaka",
+    "directory": "sdks/node"
+  },
+  "homepage": "https://vaka.hellsoft.se/sdk-node",
+  "keywords": [
+    "vaka",
+    "crash-reporting",
+    "error-tracking",
+    "opentelemetry",
+    "feature-flags",
+    "analytics"
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.mjs",
+      "require": "./dist/register.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.10.0",
+    "@opentelemetry/core": "^3.1.1",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.301.2",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.301.2",
+    "@opentelemetry/instrumentation": "^0.301.2",
+    "@opentelemetry/instrumentation-http": "^0.301.2",
+    "@opentelemetry/resources": "^3.1.1",
+    "@opentelemetry/sdk-logs": "^3.1.1",
+    "@opentelemetry/sdk-node": "^0.301.2",
+    "@opentelemetry/sdk-trace": "^3.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "esbuild": "^0.24.2",
+    "express": "^4.22.3",
+    "fastify": "^5.12.8",
+    "typescript": "^5.9.3"
+  }
+}