posthog-node 4.4.0 → 4.5.0

package/lib/posthog-core/src/index.d.ts

@@ -183,6 +183,12 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     onFeatureFlags(cb: (flags: PostHogDecideResponse['featureFlags']) => void): () => void;
     onFeatureFlag(key: string, cb: (value: string | boolean) => void): () => void;
     overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): Promise<void>;
+    /***
+     *** ERROR TRACKING
+     ***/
+    captureException(error: Error, additionalProperties?: {
+        [key: string]: any;
+    }): void;
 }
 export * from './types';
 export { LZString };

package/lib/posthog-core/src/types.d.ts

@@ -130,3 +130,4 @@ export type PostHogFlagsAndPayloadsResponse = {
 export type JsonType = string | number | boolean | null | {
     [key: string]: JsonType;
 } | Array<JsonType>;
+export type FetchLike = (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;

package/lib/posthog-core/src/utils.d.ts

@@ -1,3 +1,4 @@
+import { FetchLike } from './types';
 export declare function assert(truthyValue: any, message: string): void;
 export declare function removeTrailingSlash(url: string): string;
 export interface RetriableOptions {
@@ -10,3 +11,4 @@ export declare function currentTimestamp(): number;
 export declare function currentISOTime(): string;
 export declare function safeSetTimeout(fn: () => void, timeout: number): any;
 export declare const isPromise: (obj: any) => obj is Promise<any>;
+export declare function getFetch(): FetchLike | undefined;

package/lib/posthog-node/index.d.ts

@@ -1,2 +1,3 @@
 export * from './src/posthog-node';
 export * from './src/extensions/sentry-integration';
+export * from './src/extensions/express';

package/lib/posthog-node/src/error-tracking.d.ts

@@ -0,0 +1,12 @@
+import { EventHint } from './extensions/error-tracking/types';
+import { PostHog, PostHogOptions } from './posthog-node';
+export default class ErrorTracking {
+    private client;
+    private _exceptionAutocaptureEnabled;
+    static captureException(client: PostHog, error: unknown, distinctId: string, hint: EventHint, additionalProperties?: Record<string | number, any>): Promise<void>;
+    constructor(client: PostHog, options: PostHogOptions);
+    private startAutocaptureIfEnabled;
+    private onException;
+    private onFatalError;
+    isEnabled(): boolean;
+}

package/lib/posthog-node/src/extensions/error-tracking/autocapture.d.ts

@@ -0,0 +1,3 @@
+import { EventHint } from 'posthog-node/src/extensions/error-tracking/types';
+export declare function addUncaughtExceptionListener(captureFn: (exception: Error, hint: EventHint) => void, onFatalFn: () => void): void;
+export declare function addUnhandledRejectionListener(captureFn: (exception: unknown, hint: EventHint) => void): void;

package/lib/posthog-node/src/extensions/error-tracking/context-lines.d.ts

@@ -0,0 +1,4 @@
+import { StackFrame } from './types';
+export declare const MAX_CONTEXTLINES_COLNO: number;
+export declare const MAX_CONTEXTLINES_LINENO: number;
+export declare function addSourceContext(frames: StackFrame[]): Promise<StackFrame[]>;

package/lib/posthog-node/src/extensions/error-tracking/error-conversion.d.ts

@@ -0,0 +1,5 @@
+import { ErrorProperties, EventHint, StackParser } from './types';
+/**
+ * based on the very wonderful MIT licensed Sentry SDK
+ */
+export declare function propertiesFromUnknownInput(stackParser: StackParser, input: unknown, hint?: EventHint): Promise<ErrorProperties>;

package/lib/posthog-node/src/extensions/error-tracking/reduceable-cache.d.ts

@@ -0,0 +1,12 @@
+/** A simple Least Recently Used map */
+export declare class ReduceableCache<K, V> {
+    private readonly _maxSize;
+    private readonly _cache;
+    constructor(_maxSize: number);
+    /** Get an entry or undefined if it was not in the cache. Re-inserts to update the recently used order */
+    get(key: K): V | undefined;
+    /** Insert an entry and evict an older entry if we've reached maxSize */
+    set(key: K, value: V): void;
+    /** Remove an entry and return the entry if it was in the cache */
+    reduce(): void;
+}

package/lib/posthog-node/src/extensions/error-tracking/stack-trace.d.ts

@@ -0,0 +1,15 @@
+import { StackFrame, StackLineParser, StackLineParserFn, StackParser } from './types';
+type GetModuleFn = (filename: string | undefined) => string | undefined;
+/** Node Stack line parser */
+export declare function node(getModule?: GetModuleFn): StackLineParserFn;
+/**
+ * Does this filename look like it's part of the app code?
+ */
+export declare function filenameIsInApp(filename: string, isNative?: boolean): boolean;
+export declare function nodeStackLineParser(getModule?: GetModuleFn): StackLineParser;
+export declare const defaultStackParser: StackParser;
+/** Creates a function that gets the module name from a filename */
+export declare function createGetModuleFromFilename(basePath?: string, isWindows?: boolean): (filename: string | undefined) => string | undefined;
+export declare function createStackParser(...parsers: StackLineParser[]): StackParser;
+export declare function reverseAndStripFrames(stack: ReadonlyArray<StackFrame>): StackFrame[];
+export {};

package/lib/posthog-node/src/extensions/error-tracking/type-checking.d.ts

@@ -0,0 +1,7 @@
+import { PolymorphicEvent } from './types';
+export declare function isEvent(candidate: unknown): candidate is PolymorphicEvent;
+export declare function isPlainObject(candidate: unknown): candidate is Record<string, unknown>;
+export declare function isError(candidate: unknown): candidate is Error;
+export declare function isInstanceOf(candidate: unknown, base: any): boolean;
+export declare function isErrorEvent(event: unknown): boolean;
+export declare function isBuiltin(candidate: unknown, className: string): boolean;

package/lib/posthog-node/src/extensions/error-tracking/types.d.ts

@@ -0,0 +1,57 @@
+export declare const severityLevels: readonly ["fatal", "error", "warning", "log", "info", "debug"];
+export declare type SeverityLevel = (typeof severityLevels)[number];
+export interface PolymorphicEvent {
+    [key: string]: unknown;
+    readonly type: string;
+    readonly target?: unknown;
+    readonly currentTarget?: unknown;
+}
+export interface EventHint {
+    mechanism?: Partial<Mechanism>;
+    syntheticException?: Error | null;
+}
+export interface ErrorProperties {
+    $exception_list: Exception[];
+    $exception_level?: SeverityLevel;
+    $exception_DOMException_code?: string;
+    $exception_personURL?: string;
+}
+export interface Exception {
+    type?: string;
+    value?: string;
+    mechanism?: Mechanism;
+    module?: string;
+    thread_id?: number;
+    stacktrace?: {
+        frames?: StackFrame[];
+        type: 'raw';
+    };
+}
+export interface Mechanism {
+    handled?: boolean;
+    type?: string;
+    source?: string;
+    synthetic?: boolean;
+}
+export type StackParser = (stack: string, skipFirstLines?: number) => StackFrame[];
+export type StackLineParserFn = (line: string) => StackFrame | undefined;
+export type StackLineParser = [number, StackLineParserFn];
+export interface StackFrame {
+    platform: string;
+    filename?: string;
+    function?: string;
+    module?: string;
+    lineno?: number;
+    colno?: number;
+    abs_path?: string;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+    in_app?: boolean;
+    instruction_addr?: string;
+    addr_mode?: string;
+    vars?: {
+        [key: string]: any;
+    };
+    debug_id?: string;
+}

package/lib/posthog-node/src/extensions/express.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="node" />
+import type * as http from 'node:http';
+import { PostHog } from '../posthog-node';
+type ExpressMiddleware = (req: http.IncomingMessage, res: http.ServerResponse, next: () => void) => void;
+type ExpressErrorMiddleware = (error: MiddlewareError, req: http.IncomingMessage, res: http.ServerResponse, next: (error: MiddlewareError) => void) => void;
+interface MiddlewareError extends Error {
+    status?: number | string;
+    statusCode?: number | string;
+    status_code?: number | string;
+    output?: {
+        statusCode?: number | string;
+    };
+}
+export declare function setupExpressErrorHandler(_posthog: PostHog, app: {
+    use: (middleware: ExpressMiddleware | ExpressErrorMiddleware) => unknown;
+}): void;
+export {};

package/lib/posthog-node/src/extensions/sentry-integration.d.ts

@@ -21,9 +21,8 @@
  * @param {string} [prefix] Optional: Url of a self-hosted sentry instance (default: https://sentry.io/organizations/)
  * @param {SeverityLevel[] | '*'} [severityAllowList] Optional: send events matching the provided levels. Use '*' to send all events (default: ['error'])
  */
+import { SeverityLevel } from 'posthog-node/src/extensions/error-tracking/types';
 import { type PostHog } from '../posthog-node';
-export declare const severityLevels: readonly ["fatal", "error", "warning", "log", "info", "debug"];
-export declare type SeverityLevel = (typeof severityLevels)[number];
 type _SentryEvent = any;
 type _SentryEventProcessor = any;
 type _SentryHub = any;

package/lib/posthog-node/src/fetch.d.ts

@@ -6,7 +6,6 @@
  * This is currently solved by using the global fetch if available instead.
  * See https://github.com/PostHog/posthog-js-lite/issues/127 for more info
  */
-import { PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src';
-type FetchLike = (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
+import { FetchLike } from 'posthog-core/src';
 declare const _default: FetchLike;
 export default _default;

package/lib/posthog-node/src/posthog-node.d.ts

@@ -1,8 +1,11 @@
 import { JsonType, PostHogCoreOptions, PostHogCoreStateless, PostHogFetchOptions, PostHogFetchResponse, PostHogFlagsAndPayloadsResponse, PostHogPersistedProperty } from '../../posthog-core/src';
 import { EventMessage, GroupIdentifyMessage, IdentifyMessage, PostHogNodeV1 } from './types';
+import ErrorTracking from './error-tracking';
 export type PostHogOptions = PostHogCoreOptions & {
     persistence?: 'memory';
     personalApiKey?: string;
+    privacyMode?: boolean;
+    enableExceptionAutocapture?: boolean;
     featureFlagsPollingInterval?: number;
     maxCacheSize?: number;
     fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
@@ -10,6 +13,7 @@ export type PostHogOptions = PostHogCoreOptions & {
 export declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     private _memoryStorage;
     private featureFlagsPoller?;
+    protected errorTracking: ErrorTracking;
     private maxCacheSize;
     readonly options: PostHogOptions;
     distinctIdHasSentFlagCalls: Record<string, string[]>;
@@ -72,4 +76,5 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     reloadFeatureFlags(): Promise<void>;
     shutdown(shutdownTimeoutMs?: number): Promise<void>;
     private addLocalPersonAndGroupProperties;
+    captureException(error: unknown, distinctId: string, additionalProperties?: Record<string | number, any>): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",

package/src/error-tracking.ts

@@ -0,0 +1,66 @@
+import { EventHint } from './extensions/error-tracking/types'
+import { addUncaughtExceptionListener, addUnhandledRejectionListener } from './extensions/error-tracking/autocapture'
+import { PostHog, PostHogOptions } from './posthog-node'
+import { uuidv7 } from 'posthog-core/src/vendor/uuidv7'
+import { propertiesFromUnknownInput } from './extensions/error-tracking/error-conversion'
+import { EventMessage } from './types'
+import { defaultStackParser } from './extensions/error-tracking/stack-trace'
+
+const SHUTDOWN_TIMEOUT = 2000
+
+export default class ErrorTracking {
+  private client: PostHog
+  private _exceptionAutocaptureEnabled: boolean
+
+  static async captureException(
+    client: PostHog,
+    error: unknown,
+    distinctId: string,
+    hint: EventHint,
+    additionalProperties?: Record<string | number, any>
+  ): Promise<void> {
+    const properties: EventMessage['properties'] = { ...additionalProperties }
+    if (!distinctId) {
+      properties.$process_person_profile = false
+    }
+
+    const exceptionProperties = await propertiesFromUnknownInput(defaultStackParser, error, hint)
+
+    client.capture({
+      event: '$exception',
+      distinctId: distinctId || uuidv7(),
+      properties: {
+        ...exceptionProperties,
+        ...properties,
+      },
+    })
+  }
+
+  constructor(client: PostHog, options: PostHogOptions) {
+    this.client = client
+    this._exceptionAutocaptureEnabled = options.enableExceptionAutocapture || false
+
+    this.startAutocaptureIfEnabled()
+  }
+
+  private startAutocaptureIfEnabled(): void {
+    if (this.isEnabled()) {
+      addUncaughtExceptionListener(this.onException.bind(this), this.onFatalError.bind(this))
+      addUnhandledRejectionListener(this.onException.bind(this))
+    }
+  }
+
+  private onException(exception: unknown, hint: EventHint): void {
+    // Given stateless nature of Node SDK we capture exceptions using personless processing
+    // when no user can be determined e.g. in the case of exception autocapture
+    ErrorTracking.captureException(this.client, exception, uuidv7(), hint, { $process_person_profile: false })
+  }
+
+  private async onFatalError(): Promise<void> {
+    await this.client.shutdown(SHUTDOWN_TIMEOUT)
+  }
+
+  isEnabled(): boolean {
+    return !this.client.isDisabled && this._exceptionAutocaptureEnabled
+  }
+}

package/src/extensions/error-tracking/autocapture.ts

@@ -0,0 +1,62 @@
+import { EventHint } from 'posthog-node/src/extensions/error-tracking/types'
+
+type ErrorHandler = { _posthogErrorHandler: boolean } & ((error: Error) => void)
+
+function makeUncaughtExceptionHandler(
+  captureFn: (exception: Error, hint: EventHint) => void,
+  onFatalFn: () => void
+): ErrorHandler {
+  let calledFatalError: boolean = false
+
+  return Object.assign(
+    (error: Error): void => {
+      // Attaching a listener to `uncaughtException` will prevent the node process from exiting. We generally do not
+      // want to alter this behaviour so we check for other listeners that users may have attached themselves and adjust
+      // exit behaviour of the SDK accordingly:
+      // - If other listeners are attached, do not exit.
+      // - If the only listener attached is ours, exit.
+      const userProvidedListenersCount = global.process.listeners('uncaughtException').filter((listener) => {
+        // There are 2 listeners we ignore:
+        return (
+          // as soon as we're using domains this listener is attached by node itself
+          listener.name !== 'domainUncaughtExceptionClear' &&
+          // the handler we register in this integration
+          (listener as ErrorHandler)._posthogErrorHandler !== true
+        )
+      }).length
+
+      const processWouldExit = userProvidedListenersCount === 0
+
+      captureFn(error, {
+        mechanism: {
+          type: 'onuncaughtexception',
+          handled: false,
+        },
+      })
+
+      if (!calledFatalError && processWouldExit) {
+        calledFatalError = true
+        onFatalFn()
+      }
+    },
+    { _posthogErrorHandler: true }
+  )
+}
+
+export function addUncaughtExceptionListener(
+  captureFn: (exception: Error, hint: EventHint) => void,
+  onFatalFn: () => void
+): void {
+  global.process.on('uncaughtException', makeUncaughtExceptionHandler(captureFn, onFatalFn))
+}
+
+export function addUnhandledRejectionListener(captureFn: (exception: unknown, hint: EventHint) => void): void {
+  global.process.on('unhandledRejection', (reason: unknown) => {
+    captureFn(reason, {
+      mechanism: {
+        type: 'onunhandledrejection',
+        handled: false,
+      },
+    })
+  })
+}