@guidelytech/node 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -27,6 +27,8 @@ interface TrackMessage {
     /** Links the user to this account. */
     accountId?: string | number | null;
     timestamp?: Timestamp;
+    /** Version of your app this event came from (default: the client's `appVersion` option). */
+    appVersion?: string | number | null;
 }
 interface GroupMessage {
     /** The account id (1–256 characters). */
@@ -38,10 +40,289 @@ interface GroupMessage {
     timestamp?: Timestamp;
 }
 
+/** The parts of `process` the handlers use (tests pass a fake). */
+interface ProcessLike {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    removeListener(event: string, listener: (...args: any[]) => void): unknown;
+    listeners(event: string): Array<(...args: any[]) => void>;
+    exit(code?: number): void;
+    exitCode?: number | string | null;
+    execArgv?: string[];
+    env?: Record<string, string | undefined>;
+}
+/** Node's `--unhandled-rejections` modes (`warn-with-error-code` warns and sets the exit code). */
+type UnhandledRejectionMode = "throw" | "strict" | "warn" | "warn-with-error-code" | "none";
+interface ProcessHandlerOptions {
+    /**
+     * After an uncaught exception (or a rejection Node would have crashed on): print it, flush, then
+     * `exit(1)`, as Node does (default true). It never exits while the app has its own
+     * `uncaughtException` listeners, since Node would not either. `false` keeps the process running,
+     * like any `uncaughtException` listener does, in whatever state the error left it.
+     */
+    exitOnUncaught?: boolean;
+    /** How unhandled rejections behave (default: Node's `--unhandled-rejections` flag, else `throw`). */
+    unhandledRejection?: UnhandledRejectionMode;
+    /** Most time spent sending before exiting (default 2000 ms). */
+    flushTimeoutMs?: number;
+    /** The process to listen on (default: `process`). */
+    process?: ProcessLike;
+}
+
+/**
+ * Error monitoring types. Event shapes use Sentry's names (https://develop.sentry.dev/sdk/data-model/),
+ * so code written for Sentry's `beforeSend` keeps working; see docs/error-monitoring/sdks.md.
+ */
+type SeverityLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";
+interface Breadcrumb {
+    /** `default`, `http`, `navigation`, `query`… */
+    type?: string;
+    /** `console`, `http`, `auth`, your own… */
+    category?: string;
+    message?: string;
+    level?: SeverityLevel;
+    data?: Record<string, unknown>;
+    /** Unix seconds (default: now). */
+    timestamp?: number;
+}
+/** What produced a breadcrumb, passed to `beforeBreadcrumb`. */
+interface BreadcrumbHint {
+    /** Console breadcrumbs: the arguments of the call. */
+    input?: unknown[];
+    level?: string;
+    /** HTTP breadcrumbs: the `ClientRequest` / undici request and its response. */
+    request?: unknown;
+    response?: unknown;
+    [key: string]: unknown;
+}
+interface User {
+    /** Becomes the event's `userId` (the id your frontend passes to `identify()`). */
+    id?: string | number;
+    email?: string;
+    username?: string;
+    ip_address?: string;
+    [key: string]: unknown;
+}
+/** One stack frame in Sentry's shape (frames are listed oldest call first). */
+interface StackFrame {
+    function?: string;
+    filename?: string;
+    abs_path?: string;
+    module?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+    pre_context?: string[];
+    context_line?: string;
+    post_context?: string[];
+    vars?: Record<string, unknown>;
+}
+interface Mechanism {
+    type: string;
+    handled: boolean;
+    exception_id?: number;
+    parent_id?: number;
+    /** `cause`, or `errors[i]` for an AggregateError's members. */
+    source?: string;
+    is_exception_group?: boolean;
+    synthetic?: boolean;
+    data?: Record<string, unknown>;
+}
+interface ExceptionValue {
+    type: string;
+    value: string;
+    module?: string;
+    mechanism: Mechanism;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+}
+interface RequestData {
+    method?: string;
+    /** Origin and path; the query string is in `query_string`. */
+    url?: string;
+    query_string?: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+}
+/** The Sentry-shaped event `beforeSend` receives and the `detail` part of an `exception` message. */
+interface ErrorEvent {
+    event_id: string;
+    /** Unix seconds. */
+    timestamp: number;
+    platform: "node";
+    level: SeverityLevel;
+    logger?: string;
+    release?: string;
+    environment?: string;
+    server_name?: string;
+    transaction?: string;
+    /** Set by `captureMessage`. */
+    logentry?: {
+        formatted: string;
+    };
+    /** Causes first, the thrown exception last. */
+    exception?: {
+        values: ExceptionValue[];
+    };
+    breadcrumbs?: {
+        values: Breadcrumb[];
+    };
+    contexts?: Record<string, Record<string, unknown>>;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    user?: User;
+    fingerprint?: string[];
+    request?: RequestData;
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    [key: string]: unknown;
+}
+interface EventHint {
+    /** What was passed to `captureException` (or the message of `captureMessage`). */
+    originalException: unknown;
+    event_id: string;
+}
+/** The second argument of `captureException` / third of `captureMessage`. */
+interface CaptureContext {
+    /** Your user id (default: the scope user's `id`). */
+    userId?: string | number;
+    /** The browser SDK's anonymous id, for visitors who have not signed in. */
+    anonymousId?: string | number;
+    accountId?: string | number;
+    tags?: Record<string, string | number | boolean | null | undefined>;
+    extra?: Record<string, unknown>;
+    level?: SeverityLevel;
+    /** Sentry fingerprint: `["{{ default }}", "checkout"]` extends the default grouping, other values replace it. */
+    fingerprint?: string[];
+    contexts?: Record<string, Record<string, unknown> | null>;
+    /** An incoming request (Express/Fastify/Koa/`http.IncomingMessage`) or Sentry-shaped request data. */
+    request?: unknown;
+    /** How an integration caught the error (default `{ type: "generic", handled: true }`). */
+    mechanism?: {
+        type: string;
+        handled?: boolean;
+    };
+    /** Transaction name (`POST /pay`), else the scope's or the request's. */
+    transaction?: string;
+    /** Merged into the scope's user. */
+    user?: User;
+    /** Any other key is kept as an event property. */
+    [property: string]: unknown;
+}
+type ConsoleLevel = "debug" | "info" | "log" | "warn" | "error";
+interface ErrorOptions {
+    /** Share of errors sent, 0–1 (default 1). */
+    sampleRate?: number;
+    /** Errors to drop: strings match `"<type>: <message>"` or the message as substrings, RegExps as patterns. */
+    ignoreErrors?: Array<string | RegExp>;
+    /** Edit or drop (`null`) an event before it is queued. A hook that throws leaves the event unchanged. */
+    beforeSend?: (event: ErrorEvent, hint: EventHint) => ErrorEvent | null | undefined | Promise<ErrorEvent | null | undefined>;
+    /** Edit or drop (`null`) a breadcrumb before it is recorded. */
+    beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null | undefined;
+    /** The release errors belong to (default: the client's `appVersion`). */
+    release?: string;
+    /** `server_name` (default: `os.hostname()`). */
+    serverName?: string;
+    /** Paths (substrings or RegExps) whose frames are not your code, besides `node_modules` and Node internals. */
+    inAppExclude?: Array<string | RegExp>;
+    /** Console breadcrumbs: `true` (default) records `warn` and `error`; a list picks the levels; `false` turns them off. */
+    captureConsole?: boolean | ConsoleLevel[];
+    /** Breadcrumbs for outgoing `http`/`https` requests and `fetch` (default true). */
+    captureHttp?: boolean;
+    /** Source lines read around each in-app frame (default 5 before and after; 0 turns it off). */
+    contextLines?: number;
+    /** Send the client IP of requests (`user.ip_address`, forwarding headers). Default false. */
+    sendDefaultPii?: boolean;
+    /** Breadcrumbs kept per scope, at most 100 (default 100). */
+    maxBreadcrumbs?: number;
+}
+
+/**
+ * Data applied to every error captured while the scope is current: tags, extras, contexts, the user
+ * and the last breadcrumbs. The client has one process-wide scope; `withScope()` (and the framework
+ * middlewares, once per request) run code with a copy of it, so concurrent requests never mix.
+ */
+declare class Scope {
+    private readonly max;
+    private readonly hook?;
+    private tags;
+    private extra;
+    private contexts;
+    private user;
+    private level;
+    private fingerprint;
+    private transaction;
+    private crumbs;
+    /** @internal The framework request this scope was opened for (read when an error is captured). */
+    request: unknown;
+    /** @internal `max`: breadcrumbs kept; `hook`: the client's breadcrumb pipeline (`beforeBreadcrumb`). */
+    constructor(max?: number, hook?: ((crumb: Breadcrumb, scope: Scope) => void) | undefined);
+    /** A tag (searchable, ≤ 50 per event; keys ≤ 32 and values ≤ 200 characters). `null` removes it. */
+    setTag(key: string, value: string | number | boolean | null | undefined): this;
+    setTags(tags: Record<string, string | number | boolean | null | undefined>): this;
+    /** Arbitrary data shown with the event. `undefined` removes it. */
+    setExtra(key: string, value: unknown): this;
+    setExtras(extras: Record<string, unknown>): this;
+    /** A named context (`{ name: "checkout", cartSize: 3 }`); `null` removes it. */
+    setContext(name: string, context: Record<string, unknown> | null): this;
+    /** The user errors are attributed to; `user.id` becomes the event's `userId`. `null` clears it. */
+    setUser(user: User | null): this;
+    /** Overrides the level of events captured in this scope. */
+    setLevel(level: SeverityLevel | undefined): this;
+    setFingerprint(fingerprint: string[] | undefined): this;
+    /** The transaction name (`GET /users/:id`); the request middlewares set it from the matched route. */
+    setTransactionName(name: string | undefined): this;
+    /** Records a breadcrumb through the client's `beforeBreadcrumb`. */
+    addBreadcrumb(crumb: Breadcrumb): this;
+    /** @internal Adds an already-filtered breadcrumb, dropping the oldest beyond the limit. */
+    pushBreadcrumb(crumb: Breadcrumb): void;
+    clearBreadcrumbs(): this;
+    /** Removes everything (tags, extras, contexts, user, breadcrumbs…). */
+    clear(): this;
+    /** A copy whose changes do not affect this scope. */
+    clone(): Scope;
+    /** @internal The scope's data at capture time. */
+    data(): {
+        tags: {
+            [x: string]: string;
+        };
+        extra: {
+            [x: string]: unknown;
+        };
+        contexts: {
+            [x: string]: Record<string, unknown>;
+        };
+        user: {
+            [key: string]: unknown;
+            id?: string | number;
+            email?: string;
+            username?: string;
+            ip_address?: string;
+        } | null;
+        level: SeverityLevel | undefined;
+        fingerprint: string[] | undefined;
+        transaction: string | undefined;
+        breadcrumbs: Breadcrumb[];
+        request: unknown;
+    };
+}
+
+/** Decides which errors a framework middleware reports (default: 5xx and errors without a status). */
+interface MiddlewareOptions {
+    shouldHandleError?: (error: unknown) => boolean;
+}
+/** The parts of a Fastify instance the plugin uses. */
+interface FastifyLike {
+    addHook(name: string, hook: (...args: any[]) => unknown): unknown;
+}
+
 declare const SDK_NAME = "guidely-node";
-declare const SDK_VERSION = "0.16.0";
+declare const SDK_VERSION = "0.17.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
-type Environment = "development" | "staging" | "production";
+/** `development`, `staging`, `production` or the key of an environment you added in Settings → Environments (`qa`, `uat`…). */
+type Environment = "development" | "staging" | "production" | (string & {});
 /** The subset of `fetch` the SDK uses, so any implementation (undici, node-fetch, a test fake) fits. */
 type FetchLike = (url: string, init: {
     method: "POST";
@@ -58,7 +339,7 @@ type FetchLike = (url: string, init: {
 type GuidelyErrorCode = 
 /** A call was invalid (missing userId, empty event…) and dropped. */
 "invalid_message"
-/** A message serialized to more than 32 KB and was dropped. */
+/** A message serialized to more than 32 KB (80 KB for an exception) and was dropped. */
  | "message_too_large"
 /** The queue was full (`maxQueueSize`); the oldest messages were dropped. */
  | "queue_full"
@@ -85,7 +366,7 @@ declare class GuidelyError extends Error {
 interface GuidelyOptions {
     /** A secret API key (`gly_sk_…`) with the `events:write` scope. Never ship it to a browser. */
     secretKey: string;
-    /** The environment events are written to. */
+    /** Key of the environment events are written to (`production`, or e.g. `qa` for one you added). */
     environment: Environment;
     /** API origin (default `https://guidelytech.com`). */
     apiUrl?: string;
@@ -107,6 +388,13 @@ interface GuidelyOptions {
     fetch?: FetchLike;
     /** Flush on the process's `beforeExit` event (default true). Signals and `process.exit()` skip it: call `shutdown()`. */
     handleExit?: boolean;
+    /** Your app's version, sent with every `track` (a message's own `appVersion` wins) and as the release of errors. */
+    appVersion?: string;
+    /**
+     * Error monitoring (`captureException`, breadcrumbs, process and framework hooks). `false` turns
+     * off the automatic console / HTTP breadcrumbs; manual captures still work.
+     */
+    errors?: ErrorOptions | false;
 }
 /**
  * Server-side Guidely client: `identify`, `track` and `group` from your backend.
@@ -132,6 +420,7 @@ declare class Guidely {
     private readonly timeoutMs;
     private readonly onError;
     private readonly fetch;
+    private readonly appVersion;
     private readonly sdkJson;
     private queue;
     private droppedSinceReport;
@@ -146,6 +435,9 @@ declare class Guidely {
     private shutdownPromise;
     private exitDrain;
     private readonly exitListener;
+    /** Set once `shutdown()` has finished: events still being prepared then are dropped, not sent. */
+    private finished;
+    private readonly monitor;
     constructor(options: GuidelyOptions);
     /** Who a user is: merges `traits` into the user (creating it if needed), optionally linking an account. */
     identify(message: IdentifyMessage): void;
@@ -153,14 +445,67 @@ declare class Guidely {
     track(message: TrackMessage): void;
     /** Account traits, and optionally adds `userId` to the account. */
     group(message: GroupMessage): void;
+    /**
+     * Reports an error as an `exception` event (grouped into an issue), with the current scope's tags,
+     * extras, contexts, user and breadcrumbs. Returns the event id. Never throws.
+     *
+     * ```ts
+     * guidely.captureException(err, { userId: "u_42", tags: { area: "billing" }, extra: { invoiceId } });
+     * ```
+     */
+    captureException(error: unknown, context?: CaptureContext): string;
+    /** Reports a message (level `info` unless given), grouped by its text. Returns the event id. */
+    captureMessage(message: string, level?: SeverityLevel | CaptureContext, context?: CaptureContext): string;
+    /** A tag on every later error of the current scope (`null` removes it). */
+    setTag(key: string, value: string | number | boolean | null | undefined): void;
+    setTags(tags: Record<string, string | number | boolean | null | undefined>): void;
+    setExtra(key: string, value: unknown): void;
+    setExtras(extras: Record<string, unknown>): void;
+    /** A named context on every later error of the current scope (`null` removes it). */
+    setContext(name: string, context: Record<string, unknown> | null): void;
+    /** The user later errors of the current scope belong to (`user.id` becomes `userId`); `null` clears it. */
+    setUser(user: User | null): void;
+    /** Adds a breadcrumb to the current scope (the last 100 ride along with each error). */
+    addBreadcrumb(breadcrumb: Breadcrumb, hint?: BreadcrumbHint): void;
+    /**
+     * Runs `fn` with a copy of the current scope: tags, user and breadcrumbs set inside (and in
+     * everything it starts, through AsyncLocalStorage) stay there. Returns what `fn` returns.
+     */
+    withScope<T>(fn: (scope: Scope) => T): T;
+    /**
+     * Reports `uncaughtException` (fatal) and `unhandledRejection`, keeping Node's behaviour: the error
+     * is printed, queued events are sent (at most `flushTimeoutMs`) and the process exits with code 1.
+     * Returns a function that removes the handlers (`shutdown()` removes them too).
+     */
+    installProcessHandlers(options?: ProcessHandlerOptions): () => void;
+    /** Express: `app.use(guidely.expressRequestHandler())` first, so each request gets its own scope. */
+    expressRequestHandler(): (req: unknown, res: unknown, next: (error?: unknown) => void) => void;
+    /** Express: `app.use(guidely.expressErrorHandler())` after your routes, before other error handlers. */
+    expressErrorHandler(options?: MiddlewareOptions): (error: unknown, req: unknown, res: unknown, next: (error?: unknown) => void) => void;
+    /** Fastify: `await app.register(guidely.fastifyPlugin())` (request scopes + the `onError` hook). */
+    fastifyPlugin(options?: MiddlewareOptions): (fastify: FastifyLike, opts: unknown, done?: (error?: Error) => void) => void;
+    /** Fastify: `app.addHook("onError", guidely.fastifyErrorHook())`, when you do not use the plugin. */
+    fastifyErrorHook(options?: MiddlewareOptions): (request: unknown, reply: unknown, error: unknown, done?: () => void) => void;
+    /** Koa: `app.use(guidely.koaMiddleware())` first: a scope per request; errors are reported and rethrown. */
+    koaMiddleware(options?: MiddlewareOptions): (ctx: {
+        req?: unknown;
+        res?: unknown;
+    }, next: () => Promise<unknown>) => Promise<unknown>;
     /** Sends everything queued; resolves once it has been delivered or dropped. Never rejects. */
     flush(): Promise<void>;
     /**
-     * Stops the timer and the exit hook, then flushes, waiting at most `shutdownTimeoutMs`. Later calls
-     * are dropped (and reported). Call it before your process exits. Never rejects.
+     * Stops the timer, the exit hook and the error hooks, then flushes, waiting at most
+     * `shutdownTimeoutMs`. Later calls are dropped (and reported). Call it before your process exits.
+     * Never rejects.
      */
     shutdown(): Promise<void>;
     private enqueue;
+    /**
+     * Queues a built `exception` message (it may finish preparing after `shutdown()` began, which
+     * still sends it) and starts sending right away: errors should not wait for the flush interval.
+     */
+    private enqueueException;
+    private push;
     private scheduleTimer;
     private clearTimer;
     /** Starts (or joins) the single sender. `all`: send everything, not only full batches. */
@@ -178,4 +523,20 @@ declare class Guidely {
     private report;
 }
 
-export { DEFAULT_API_URL, type Environment, type FetchLike, type GroupMessage, Guidely, GuidelyError, type GuidelyErrorCode, type GuidelyOptions, type IdentifyMessage, type JsonValue, type MessageType, type Properties, SDK_NAME, SDK_VERSION, type Timestamp, type TrackMessage };
+/** A frame as Guidely indexes it (`properties.frames`, innermost first). */
+interface GuidelyFrame {
+    fn?: string;
+    file?: string;
+    line?: number;
+    col?: number;
+    inApp?: boolean;
+}
+interface FrameOptions {
+    /** Directory module names are relative to (Sentry's `getModuleFromFilename` base). */
+    root?: string;
+    inAppExclude?: Array<string | RegExp>;
+}
+/** Parses a V8 `Error.stack` into Sentry frames, **oldest call first** (the throwing frame last). */
+declare function parseStack(stack: unknown, o?: FrameOptions): StackFrame[];
+
+export { type Breadcrumb, type BreadcrumbHint, type CaptureContext, type ConsoleLevel, DEFAULT_API_URL, type Environment, type ErrorEvent, type ErrorOptions, type EventHint, type ExceptionValue, type FastifyLike, type FetchLike, type GroupMessage, Guidely, GuidelyError, type GuidelyErrorCode, type GuidelyFrame, type GuidelyOptions, type IdentifyMessage, type JsonValue, type Mechanism, type MessageType, type MiddlewareOptions, type ProcessHandlerOptions, type ProcessLike, type Properties, type RequestData, SDK_NAME, SDK_VERSION, Scope, type SeverityLevel, type StackFrame, type Timestamp, type TrackMessage, type UnhandledRejectionMode, type User, parseStack };