@flareapp/node 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,138 @@
+import { AttributeValue, Attributes, Config, ContextCollector, DEFAULT_URL_DENYLIST, EntryPointHandler, FileReader, Flare, Flare as Flare$1, FlushFn, FlushScheduler, Framework, GlobalScopeProvider, Glow, Logger, MessageLevel, NullFileReader, OverriddenGrouping, Report, Scope, Scope as Scope$1, ScopeProvider, SdkInfo, SpanEvent, StackFrame, convertToError, redactUrlQuery, resolveDenylist } from "@flareapp/core";
+
+//#region src/types.d.ts
+type RequestContext = {
+  method?: string;
+  path?: string;
+  url?: string;
+  headers?: Record<string, string | string[] | undefined>;
+  body?: unknown;
+};
+type User = {
+  id?: string | number;
+  email?: string;
+  username?: string;
+  ipAddress?: string;
+};
+type FatalMode = 'off' | 'report' | 'report-and-exit';
+type NodeOptions = {
+  uncaughtExceptionMode?: FatalMode;
+  unhandledRejectionMode?: FatalMode;
+  shutdownTimeoutMs?: number;
+  headerDenylist?: RegExp;
+  headerAllowlist?: RegExp | null;
+  replaceDefaultHeaderDenylist?: boolean;
+  captureRequestBody?: boolean;
+  bodyMaxBytes?: number;
+  bodyAllowedContentTypes?: RegExp;
+  bodyKeyDenylist?: RegExp;
+};
+//#endregion
+//#region src/scope/NodeScope.d.ts
+declare class NodeScope extends Scope$1 {
+  request: RequestContext;
+  user: User | null;
+}
+//#endregion
+//#region src/Flare.d.ts
+/**
+ * Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
+ *
+ * Subclasses core's `Flare` and wires the Node-only seams in its constructor:
+ *
+ * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
+ *   gets its own `NodeScope` (glows, attributes, user, entry-point, request),
+ *   isolated from concurrent requests.
+ * - `makeNodeContextCollector(...)` to project the current `NodeScope` and
+ *   process info into report attributes (http.request.*, url.path, etc).
+ * - `DiskFileReader` to read source files for stack-trace snippets via
+ *   `node:fs/promises` instead of the browser's `fetch`.
+ * - `ProcessHandlerManager` to attach/detach `uncaughtException` and
+ *   `unhandledRejection` listeners based on the current `NodeOptions`.
+ *
+ * Also adds Node-only API surface on top of core: `configureNode(...)`,
+ * `runWithContext(...)`, `mergeContext(...)`, `setUser(...)`, `getContext()`,
+ * `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
+ * `addContext`, `glow`, etc.) return `this`, so chaining keeps the
+ * `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+ */
+declare class NodeFlare extends Flare$1 {
+  private nodeOptions;
+  private isLit;
+  private nodeScopeProvider;
+  private handlerManager;
+  constructor();
+  /**
+   * Set the API key (and optional debug flag), then reconcile process
+   * listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
+   * not just the first, so `light()` is the right escape hatch to re-attach
+   * after `removeProcessListeners()`.
+   */
+  light(key?: string, debug?: boolean): this;
+  /**
+   * Merge Node-only options (fatal-handler modes, header/body redaction
+   * config, shutdown timeout) into the active configuration. Safe to call
+   * before or after `light()`:
+   *
+   * - Before `light()`: options are stored; listeners are attached when
+   *   `light()` runs.
+   * - After `light()`: options are stored AND listeners are reconciled
+   *   immediately, so flipping a mode to `'off'` detaches the handler and
+   *   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
+   *
+   * Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
+   * `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
+   * `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
+   * across keys.
+   */
+  configureNode(partial: Partial<NodeOptions>): NodeFlare;
+  /**
+   * Run `fn` inside a fresh `NodeScope` carrying the supplied request
+   * metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
+   * `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
+   * see a scope that is isolated from other concurrent requests.
+   *
+   * Mirrors a typical web-framework middleware: call once per request,
+   * wrapping the request handler, and the SDK will attribute any error
+   * reported inside the chain to the right request.
+   */
+  runWithContext<T>(request: RequestContext, fn: () => T): T;
+  /**
+   * Patch the request metadata on the active scope after `runWithContext(...)`
+   * has already started. Useful when fields become known partway through a
+   * request (e.g., the resolved absolute URL after proxy headers are parsed).
+   *
+   * Outside any `runWithContext(...)` callback, this writes to the fallback
+   * scope; the patch is visible to subsequent reports issued from outside a
+   * request scope but is NOT inherited by future `runWithContext(...)` calls.
+   */
+  mergeContext(partial: Partial<RequestContext>): void;
+  /**
+   * Attach an authenticated user to the active scope. Inside a request scope
+   * this is per-request; outside it lands on the fallback scope. The fields
+   * are projected to OTel-style keys (`enduser.id`, `enduser.email`,
+   * `enduser.username`, `client.address`) by the Node context collector.
+   */
+  setUser(user: User | null): void;
+  /**
+   * Returns the request scope when called inside `runWithContext(...)`, or
+   * `null` outside. Intentionally returns `null` (not the fallback scope)
+   * when no request is active, so callers can distinguish "we are inside a
+   * request" from "we are not". Primarily useful for debugging.
+   */
+  getContext(): NodeScope | null;
+  /**
+   * Detach the `uncaughtException` and `unhandledRejection` listeners
+   * without changing `nodeOptions`. Intended for tests and for graceful
+   * shutdown paths where you want to take ownership of process exit
+   * yourself.
+   *
+   * Calling `light()` afterwards re-attaches based on the current options.
+   */
+  removeProcessListeners(): void;
+}
+//#endregion
+//#region src/index.d.ts
+declare const flare: NodeFlare;
+//#endregion
+export { type AttributeValue, type Attributes, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FatalMode, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, Logger, type MessageLevel, NodeFlare, type NodeOptions, NodeScope, NullFileReader, type OverriddenGrouping, type Report, type RequestContext, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, type User, convertToError, flare, redactUrlQuery, resolveDenylist };

package/dist/index.d.mts

@@ -0,0 +1,138 @@
+import { AttributeValue, Attributes, Config, ContextCollector, DEFAULT_URL_DENYLIST, EntryPointHandler, FileReader, Flare, Flare as Flare$1, FlushFn, FlushScheduler, Framework, GlobalScopeProvider, Glow, Logger, MessageLevel, NullFileReader, OverriddenGrouping, Report, Scope, Scope as Scope$1, ScopeProvider, SdkInfo, SpanEvent, StackFrame, convertToError, redactUrlQuery, resolveDenylist } from "@flareapp/core";
+
+//#region src/types.d.ts
+type RequestContext = {
+  method?: string;
+  path?: string;
+  url?: string;
+  headers?: Record<string, string | string[] | undefined>;
+  body?: unknown;
+};
+type User = {
+  id?: string | number;
+  email?: string;
+  username?: string;
+  ipAddress?: string;
+};
+type FatalMode = 'off' | 'report' | 'report-and-exit';
+type NodeOptions = {
+  uncaughtExceptionMode?: FatalMode;
+  unhandledRejectionMode?: FatalMode;
+  shutdownTimeoutMs?: number;
+  headerDenylist?: RegExp;
+  headerAllowlist?: RegExp | null;
+  replaceDefaultHeaderDenylist?: boolean;
+  captureRequestBody?: boolean;
+  bodyMaxBytes?: number;
+  bodyAllowedContentTypes?: RegExp;
+  bodyKeyDenylist?: RegExp;
+};
+//#endregion
+//#region src/scope/NodeScope.d.ts
+declare class NodeScope extends Scope$1 {
+  request: RequestContext;
+  user: User | null;
+}
+//#endregion
+//#region src/Flare.d.ts
+/**
+ * Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
+ *
+ * Subclasses core's `Flare` and wires the Node-only seams in its constructor:
+ *
+ * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
+ *   gets its own `NodeScope` (glows, attributes, user, entry-point, request),
+ *   isolated from concurrent requests.
+ * - `makeNodeContextCollector(...)` to project the current `NodeScope` and
+ *   process info into report attributes (http.request.*, url.path, etc).
+ * - `DiskFileReader` to read source files for stack-trace snippets via
+ *   `node:fs/promises` instead of the browser's `fetch`.
+ * - `ProcessHandlerManager` to attach/detach `uncaughtException` and
+ *   `unhandledRejection` listeners based on the current `NodeOptions`.
+ *
+ * Also adds Node-only API surface on top of core: `configureNode(...)`,
+ * `runWithContext(...)`, `mergeContext(...)`, `setUser(...)`, `getContext()`,
+ * `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
+ * `addContext`, `glow`, etc.) return `this`, so chaining keeps the
+ * `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+ */
+declare class NodeFlare extends Flare$1 {
+  private nodeOptions;
+  private isLit;
+  private nodeScopeProvider;
+  private handlerManager;
+  constructor();
+  /**
+   * Set the API key (and optional debug flag), then reconcile process
+   * listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
+   * not just the first, so `light()` is the right escape hatch to re-attach
+   * after `removeProcessListeners()`.
+   */
+  light(key?: string, debug?: boolean): this;
+  /**
+   * Merge Node-only options (fatal-handler modes, header/body redaction
+   * config, shutdown timeout) into the active configuration. Safe to call
+   * before or after `light()`:
+   *
+   * - Before `light()`: options are stored; listeners are attached when
+   *   `light()` runs.
+   * - After `light()`: options are stored AND listeners are reconciled
+   *   immediately, so flipping a mode to `'off'` detaches the handler and
+   *   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
+   *
+   * Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
+   * `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
+   * `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
+   * across keys.
+   */
+  configureNode(partial: Partial<NodeOptions>): NodeFlare;
+  /**
+   * Run `fn` inside a fresh `NodeScope` carrying the supplied request
+   * metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
+   * `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
+   * see a scope that is isolated from other concurrent requests.
+   *
+   * Mirrors a typical web-framework middleware: call once per request,
+   * wrapping the request handler, and the SDK will attribute any error
+   * reported inside the chain to the right request.
+   */
+  runWithContext<T>(request: RequestContext, fn: () => T): T;
+  /**
+   * Patch the request metadata on the active scope after `runWithContext(...)`
+   * has already started. Useful when fields become known partway through a
+   * request (e.g., the resolved absolute URL after proxy headers are parsed).
+   *
+   * Outside any `runWithContext(...)` callback, this writes to the fallback
+   * scope; the patch is visible to subsequent reports issued from outside a
+   * request scope but is NOT inherited by future `runWithContext(...)` calls.
+   */
+  mergeContext(partial: Partial<RequestContext>): void;
+  /**
+   * Attach an authenticated user to the active scope. Inside a request scope
+   * this is per-request; outside it lands on the fallback scope. The fields
+   * are projected to OTel-style keys (`enduser.id`, `enduser.email`,
+   * `enduser.username`, `client.address`) by the Node context collector.
+   */
+  setUser(user: User | null): void;
+  /**
+   * Returns the request scope when called inside `runWithContext(...)`, or
+   * `null` outside. Intentionally returns `null` (not the fallback scope)
+   * when no request is active, so callers can distinguish "we are inside a
+   * request" from "we are not". Primarily useful for debugging.
+   */
+  getContext(): NodeScope | null;
+  /**
+   * Detach the `uncaughtException` and `unhandledRejection` listeners
+   * without changing `nodeOptions`. Intended for tests and for graceful
+   * shutdown paths where you want to take ownership of process exit
+   * yourself.
+   *
+   * Calling `light()` afterwards re-attaches based on the current options.
+   */
+  removeProcessListeners(): void;
+}
+//#endregion
+//#region src/index.d.ts
+declare const flare: NodeFlare;
+//#endregion
+export { type AttributeValue, type Attributes, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FatalMode, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, Logger, type MessageLevel, NodeFlare, type NodeOptions, NodeScope, NullFileReader, type OverriddenGrouping, type Report, type RequestContext, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, type User, convertToError, flare, redactUrlQuery, resolveDenylist };