@hellsoft/vaka-node 0.0.0-stage → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+import { parseStack, type Frame } from './stack';
+import { currentScope, globalScope, withScope, type Breadcrumb, type Level, type User, type Scope } from './scope';
+import { type Item } from './transport';
+import { vakaLogRecordProcessor, vakaSpanExporter, VakaScopeSpanProcessor } from './otel';
+export type { Frame, Breadcrumb, Level, User, Scope, Item };
+export type { ReqLike } from "./integrations";
+export { parseStack, withScope, currentScope, vakaSpanExporter, vakaLogRecordProcessor, VakaScopeSpanProcessor };
+export type Props = Record<string, string | number | boolean | null | undefined>;
+export type FlagValue = boolean | string;
+export interface Options {
+    /** Project ingest key (vk_...). Default: `VAKA_KEY` or `VAKA_INGEST_KEY`. */
+    key?: string;
+    /** Vaka server URL, e.g. https://vaka.example.com. Default: `VAKA_ENDPOINT`. */
+    endpoint?: string;
+    /** App version. Default: `VAKA_RELEASE`, else `npm_package_version`. */
+    release?: string;
+    /** Default: `VAKA_ENVIRONMENT`, else `NODE_ENV`, else `production`. */
+    environment?: string;
+    /** OpenTelemetry `service.name`. Default: `OTEL_SERVICE_NAME`, else `npm_package_name`. */
+    serviceName?: string;
+    /**
+     * Start the OpenTelemetry Node SDK and export traces and logs to Vaka (default true). Set false
+     * when you run your own NodeSDK; add `vakaSpanExporter()` and `vakaLogRecordProcessor()` to it.
+     */
+    otel?: boolean;
+    /** Fraction of new traces to record, 0..1 (default 1). Incoming `traceparent` decisions win. */
+    tracesSampleRate?: number;
+    /** Export OpenTelemetry log records to Vaka (default true). */
+    logs?: boolean;
+    /**
+     * OpenTelemetry instrumentations (default: HTTP server and client only). Pass
+     * `getNodeAutoInstrumentations()` from `@opentelemetry/auto-instrumentations-node` for Express,
+     * Fastify, databases, queues and more.
+     */
+    instrumentations?: (Instrumentation | Instrumentation[])[];
+    /** Extra OpenTelemetry resource attributes. */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Report uncaught exceptions and unhandled rejections (default true). */
+    captureUnhandled?: boolean;
+    /**
+     * After an unhandled rejection: `strict` exits with code 1 like Node does by default, `warn`
+     * prints a warning and keeps running, `none` only reports. Default: follows
+     * `--unhandled-rejections`, else `strict`.
+     */
+    unhandledRejection?: 'strict' | 'warn' | 'none';
+    /** Exit with code 1 after reporting an uncaught exception, as Node does (default true). */
+    exitOnUncaught?: boolean;
+    /** How long to wait for delivery before exiting on a crash (default 2000 ms). */
+    shutdownTimeoutMs?: number;
+    /** Record console.warn/error and outgoing HTTP requests as breadcrumbs (default true). */
+    breadcrumbs?: boolean;
+    /** Maximum breadcrumbs kept per scope (default 100). */
+    maxBreadcrumbs?: number;
+    /** Read source lines around in-app frames from disk (default true). */
+    sourceContext?: boolean;
+    /** Fraction of errors to send, 0..1 (default 1). */
+    errorSampleRate?: number;
+    /** Errors whose message matches are dropped. */
+    ignoreErrors?: (string | RegExp)[];
+    /** Capture errors with these HTTP statuses from the middleware (default: status >= 500). */
+    shouldCaptureStatus?: (status: number) => boolean;
+    /** Cache flag evaluations per identity for this long (default 30000 ms; 0 disables). */
+    flagsCacheTtlMs?: number;
+    /** Modify or drop (return null) an item before it is sent. */
+    beforeSend?: (item: Item) => Item | null;
+    /** How often queued items are sent (default 2000 ms). Errors go out at once. */
+    flushIntervalMs?: number;
+    /** Log SDK activity to stderr. */
+    debug?: boolean;
+}
+export interface CaptureContext {
+    level?: Level;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    handled?: boolean;
+    fingerprint?: string[];
+    user?: User;
+}
+export interface FlagContext {
+    /** Stable id for bucketing; defaults to the scope's user id. */
+    distinctId?: string;
+    userId?: string;
+    /** Properties targeting rules can match, e.g. `{ plan: 'pro' }`. */
+    properties?: Props;
+}
+export declare const SDK: {
+    name: string;
+    version: string;
+};
+/** Initialize the SDK. Call once, as early as possible (before importing your HTTP framework). */
+export declare function init(options?: Options): void;
+/** True after a successful init(). */
+export declare function isInitialized(): boolean;
+/** Set the user for the current scope (request inside middleware, else global). Opt-in. */
+export declare function setUser(user: User | string | null): void;
+export declare function setTag(key: string, value: string): void;
+export declare function setTags(tags: Record<string, string>): void;
+/** Attach structured context (e.g. `setContext('order', { id: 42 })`) to errors in this scope. */
+export declare function setContext(name: string, value: Record<string, unknown> | null): void;
+export declare function addBreadcrumb(b: Breadcrumb): void;
+/** The active OpenTelemetry trace id, if any. */
+export declare function traceId(): string | undefined;
+/**
+ * Report an error. Returns the event id, or undefined when it was dropped. `fatal` marks a crash
+ * (the process is about to exit).
+ */
+export declare function captureException(error: unknown, ctx?: CaptureContext, fatal?: boolean): string | undefined;
+/** Alias of captureException, matching the browser SDK. */
+export declare const captureError: typeof captureException;
+/** Report a message as an error-like event. */
+export declare function captureMessage(message: string, level?: Level, ctx?: CaptureContext): string | undefined;
+/** A file attached to feedback: PNG, JPEG or WebP, at most 5 MB. */
+export interface FeedbackAttachment {
+    filename: string;
+    data: Uint8Array | ArrayBuffer;
+    /** Default: guessed from the file name. */
+    contentType?: string;
+}
+export interface Feedback {
+    /** What the user wrote (required). Longer than 5000 characters is cut. */
+    message: string;
+    /** Contact email, only when the user gave it. */
+    email?: string;
+    name?: string;
+    /** The error event this feedback is about (the id captureException returned). */
+    eventId?: string;
+    /** The issue this feedback is about: id or short id like `API-12`. */
+    issue?: string;
+    /** Default: the current scope's user. */
+    userId?: string;
+    /** The end user's session id, when your app has one. */
+    sessionId?: string;
+    /** Page or screen the feedback is about. Default: the current request's URL. */
+    url?: string;
+    /**
+     * The end user's IP address (e.g. `req.ip`). Feedback is rate limited per address, so without it
+     * all feedback from this server shares one limit.
+     */
+    ip?: string;
+    tags?: Record<string, string>;
+    /** Up to 3 images. */
+    attachments?: FeedbackAttachment[];
+}
+export interface FeedbackResult {
+    id: string;
+    /** e.g. `API-F12` */
+    shortId: string;
+}
+/** Thrown by captureFeedback when the server rejects the feedback or cannot be reached. */
+export declare class FeedbackError extends Error {
+    /** HTTP status, or 0 when nothing was sent. 429 means a rate limit was hit. */
+    status: number;
+    constructor(message: string, status?: number);
+}
+/**
+ * Forward feedback your users wrote (a support form, in-app chat) to Vaka, with the current
+ * scope's user, release, environment, tags and flags. Sent right away, not batched.
+ * Rejects with a FeedbackError when the server refuses it (e.g. 429 for a rate limit).
+ */
+export declare function captureFeedback(f: Feedback): Promise<FeedbackResult>;
+/** Record a custom server-side event (e.g. `track('order_paid', { amount: 49 })`). */
+export declare function track(name: string, props?: Props, o?: {
+    userId?: string;
+    url?: string;
+}): void;
+/**
+ * Evaluate all flags for one person. The values are also attached to the current scope, so
+ * errors, events and spans in this request carry them as exposures.
+ */
+export declare function getFlags(ctx?: FlagContext): Promise<Record<string, FlagValue>>;
+/** One flag's value: `true`/`false`, or the variant key. Returns `fallback` when unknown or on failure. */
+export declare function getFlag(key: string, fallback?: FlagValue, ctx?: FlagContext): Promise<FlagValue>;
+/** True when a flag is on (any variant). */
+export declare function isEnabled(key: string, ctx?: FlagContext): Promise<boolean>;
+/** Express/Connect: isolates breadcrumbs, user and tags per request. `app.use(Vaka.requestHandler())` first. */
+export declare function requestHandler(): (req: import("./integrations").ReqLike, _res: unknown, next: (err?: unknown) => void) => void;
+/** Express: reports errors passed to `next(err)`. `app.use(Vaka.errorHandler())` after your routes. */
+export declare function errorHandler(): (err: unknown, req: import("./integrations").ReqLike, res: {
+    statusCode?: number;
+}, next: (err?: unknown) => void) => void;
+/** Express: add both middlewares' error half to an existing app (call after routes). */
+export declare function setupExpressErrorHandler(app: {
+    use: (...a: unknown[]) => unknown;
+}): void;
+/** Fastify: `await app.register(Vaka.fastifyPlugin)`. */
+export declare const fastifyPlugin: any;
+/** Wrap any `(req, res)` handler (node:http, serverless) so it gets a scope and errors are reported. */
+export declare function wrapHandler<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+/** Send queued items. Resolves true when everything was delivered within `timeoutMs`. */
+export declare function flush(timeoutMs?: number): Promise<boolean>;
+/** Flush errors and events, then shut down OpenTelemetry (flushing spans and logs). */
+export declare function close(timeoutMs?: number): Promise<boolean>;
+/** For tests: reset all state and remove hooks. */
+export declare function _reset(): Promise<void>;
+export { globalScope as _globalScope };