@drakkar.software/sunglasses-core 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -1203,6 +1203,71 @@ interface CaptureExceptionOptions {
  */
 declare function captureException(client: ISunglassesClient, error: unknown, options?: CaptureExceptionOptions): void;
 
+/** Console methods that can be captured. */
+type ConsoleLevel = 'error' | 'warn';
+/**
+ * Options for {@link patchConsole}.
+ */
+interface ConsoleCaptureOptions {
+    /** Console methods to capture. Default: `['error']`. */
+    levels?: ConsoleLevel[];
+    /**
+     * Skip console output whose composed message matches any of these patterns.
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /** Truncate the composed message to this many characters. Default: `200`. */
+    maxMessageLength?: number;
+    /** Include a stack trace in `$error_stack`. Default: `false` (privacy-safe). */
+    includeStack?: boolean;
+    /** Extra properties merged into every captured `$error` event. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for the providers' `autoCaptureErrors` option. Extends
+ * {@link CaptureExceptionOptions} (applied to unhandled global errors) with
+ * toggles for the global handlers and console capture.
+ */
+interface AutoCaptureErrorsOptions extends CaptureExceptionOptions {
+    /**
+     * Install the platform global error handlers (web `window` `error` /
+     * `unhandledrejection`, React Native `ErrorUtils`). Default: `true`.
+     */
+    globalHandlers?: boolean;
+    /**
+     * Also capture console output as `$error` events. `true` captures
+     * `console.error`; pass {@link ConsoleCaptureOptions} to configure levels.
+     * Default: off.
+     */
+    console?: boolean | ConsoleCaptureOptions;
+}
+/**
+ * Patch the global `console` so that `console.error` / `console.warn` (per
+ * `levels`) are also captured as SunGlasses `$error` events
+ * (`$error_handled: false`, `$error_source: 'console'`).
+ *
+ * Works identically on web and React Native — both expose a global `console`.
+ * The original method is always called first, so logs still appear in the
+ * console. Returns an unpatch function that restores the original methods.
+ *
+ * Guards against infinite recursion: SunGlasses' own logger writes to
+ * `console.error`/`console.warn` (prefixed with `[SunGlasses]`), and
+ * `client.capture()` may log on failure. A re-entrancy flag plus a prefix skip
+ * prevent a capture -> log -> capture loop.
+ *
+ * @param client - SunGlasses client instance.
+ * @param options - Optional capture configuration.
+ * @returns A function that restores the original console methods.
+ *
+ * @example
+ * ```ts
+ * const unpatch = patchConsole(client, { levels: ['error', 'warn'] });
+ * // ... later
+ * unpatch();
+ * ```
+ */
+declare function patchConsole(client: ISunglassesClient, options?: ConsoleCaptureOptions): () => void;
+
 /**
  * A typed analytics stub that is safe to use before the SDK initialises.
  *
@@ -1275,4 +1340,4 @@ declare function sha256Hex(input: string): Promise<string>;
  */
 declare function nowISO(): string;
 
-export { type AppMetadata, type AppUpdateInfo, type CaptureExceptionOptions, type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, captureException, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };
+export { type AppMetadata, type AppUpdateInfo, type AutoCaptureErrorsOptions, type CaptureExceptionOptions, type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ConsoleCaptureOptions, type ConsoleLevel, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, captureException, createLazyClient, createLogger, generateUUID, nowISO, patchConsole, sha256Hex };

package/dist/index.d.ts

@@ -1203,6 +1203,71 @@ interface CaptureExceptionOptions {
  */
 declare function captureException(client: ISunglassesClient, error: unknown, options?: CaptureExceptionOptions): void;
 
+/** Console methods that can be captured. */
+type ConsoleLevel = 'error' | 'warn';
+/**
+ * Options for {@link patchConsole}.
+ */
+interface ConsoleCaptureOptions {
+    /** Console methods to capture. Default: `['error']`. */
+    levels?: ConsoleLevel[];
+    /**
+     * Skip console output whose composed message matches any of these patterns.
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /** Truncate the composed message to this many characters. Default: `200`. */
+    maxMessageLength?: number;
+    /** Include a stack trace in `$error_stack`. Default: `false` (privacy-safe). */
+    includeStack?: boolean;
+    /** Extra properties merged into every captured `$error` event. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for the providers' `autoCaptureErrors` option. Extends
+ * {@link CaptureExceptionOptions} (applied to unhandled global errors) with
+ * toggles for the global handlers and console capture.
+ */
+interface AutoCaptureErrorsOptions extends CaptureExceptionOptions {
+    /**
+     * Install the platform global error handlers (web `window` `error` /
+     * `unhandledrejection`, React Native `ErrorUtils`). Default: `true`.
+     */
+    globalHandlers?: boolean;
+    /**
+     * Also capture console output as `$error` events. `true` captures
+     * `console.error`; pass {@link ConsoleCaptureOptions} to configure levels.
+     * Default: off.
+     */
+    console?: boolean | ConsoleCaptureOptions;
+}
+/**
+ * Patch the global `console` so that `console.error` / `console.warn` (per
+ * `levels`) are also captured as SunGlasses `$error` events
+ * (`$error_handled: false`, `$error_source: 'console'`).
+ *
+ * Works identically on web and React Native — both expose a global `console`.
+ * The original method is always called first, so logs still appear in the
+ * console. Returns an unpatch function that restores the original methods.
+ *
+ * Guards against infinite recursion: SunGlasses' own logger writes to
+ * `console.error`/`console.warn` (prefixed with `[SunGlasses]`), and
+ * `client.capture()` may log on failure. A re-entrancy flag plus a prefix skip
+ * prevent a capture -> log -> capture loop.
+ *
+ * @param client - SunGlasses client instance.
+ * @param options - Optional capture configuration.
+ * @returns A function that restores the original console methods.
+ *
+ * @example
+ * ```ts
+ * const unpatch = patchConsole(client, { levels: ['error', 'warn'] });
+ * // ... later
+ * unpatch();
+ * ```
+ */
+declare function patchConsole(client: ISunglassesClient, options?: ConsoleCaptureOptions): () => void;
+
 /**
  * A typed analytics stub that is safe to use before the SDK initialises.
  *
@@ -1275,4 +1340,4 @@ declare function sha256Hex(input: string): Promise<string>;
  */
 declare function nowISO(): string;
 
-export { type AppMetadata, type AppUpdateInfo, type CaptureExceptionOptions, type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, captureException, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };
+export { type AppMetadata, type AppUpdateInfo, type AutoCaptureErrorsOptions, type CaptureExceptionOptions, type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ConsoleCaptureOptions, type ConsoleLevel, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, captureException, createLazyClient, createLogger, generateUUID, nowISO, patchConsole, sha256Hex };

package/dist/index.js

@@ -38,6 +38,7 @@ __export(index_exports, {
   createLogger: () => createLogger,
   generateUUID: () => generateUUID,
   nowISO: () => nowISO,
+  patchConsole: () => patchConsole,
   sha256Hex: () => sha256Hex
 });
 module.exports = __toCommonJS(index_exports);
@@ -1645,6 +1646,65 @@ function captureException(client, error, options = {}) {
   }
 }
 
+// src/patchConsole.ts
+var SELF_LOG_PREFIX = "[SunGlasses]";
+var LEVEL_TO_SEVERITY = {
+  error: "error",
+  warn: "warning"
+};
+function composeMessage(args) {
+  return args.map((arg) => {
+    if (typeof arg === "string") return arg;
+    if (arg instanceof Error) return arg.message;
+    try {
+      return typeof arg === "object" && arg !== null ? JSON.stringify(arg) : String(arg);
+    } catch {
+      return "[object]";
+    }
+  }).join(" ");
+}
+function patchConsole(client, options = {}) {
+  const {
+    levels = ["error"],
+    ignorePatterns = [],
+    maxMessageLength = 200,
+    includeStack = false,
+    properties
+  } = options;
+  const uniqueLevels = Array.from(new Set(levels));
+  const originals = /* @__PURE__ */ new Map();
+  let isCapturing = false;
+  for (const level of uniqueLevels) {
+    const original = console[level];
+    originals.set(level, original);
+    console[level] = (...args) => {
+      original.apply(console, args);
+      if (isCapturing) return;
+      if (typeof args[0] === "string" && args[0].startsWith(SELF_LOG_PREFIX)) return;
+      const rawMessage = composeMessage(args);
+      if (ignorePatterns.some((p) => p.test(rawMessage))) return;
+      const errorArg = args.find((a) => a instanceof Error);
+      isCapturing = true;
+      try {
+        captureException(client, errorArg ?? rawMessage, {
+          handled: false,
+          level: LEVEL_TO_SEVERITY[level],
+          includeStack,
+          maxMessageLength,
+          properties: { ...properties, $error_source: "console" }
+        });
+      } finally {
+        isCapturing = false;
+      }
+    };
+  }
+  return () => {
+    for (const [level, original] of originals) {
+      console[level] = original;
+    }
+  };
+}
+
 // src/LazyClient.ts
 function createLazyClient() {
   let _inner = null;
@@ -1782,5 +1842,6 @@ function createLazyClient() {
   createLogger,
   generateUUID,
   nowISO,
+  patchConsole,
   sha256Hex
 });

package/dist/index.mjs

@@ -1601,6 +1601,65 @@ function captureException(client, error, options = {}) {
   }
 }
 
+// src/patchConsole.ts
+var SELF_LOG_PREFIX = "[SunGlasses]";
+var LEVEL_TO_SEVERITY = {
+  error: "error",
+  warn: "warning"
+};
+function composeMessage(args) {
+  return args.map((arg) => {
+    if (typeof arg === "string") return arg;
+    if (arg instanceof Error) return arg.message;
+    try {
+      return typeof arg === "object" && arg !== null ? JSON.stringify(arg) : String(arg);
+    } catch {
+      return "[object]";
+    }
+  }).join(" ");
+}
+function patchConsole(client, options = {}) {
+  const {
+    levels = ["error"],
+    ignorePatterns = [],
+    maxMessageLength = 200,
+    includeStack = false,
+    properties
+  } = options;
+  const uniqueLevels = Array.from(new Set(levels));
+  const originals = /* @__PURE__ */ new Map();
+  let isCapturing = false;
+  for (const level of uniqueLevels) {
+    const original = console[level];
+    originals.set(level, original);
+    console[level] = (...args) => {
+      original.apply(console, args);
+      if (isCapturing) return;
+      if (typeof args[0] === "string" && args[0].startsWith(SELF_LOG_PREFIX)) return;
+      const rawMessage = composeMessage(args);
+      if (ignorePatterns.some((p) => p.test(rawMessage))) return;
+      const errorArg = args.find((a) => a instanceof Error);
+      isCapturing = true;
+      try {
+        captureException(client, errorArg ?? rawMessage, {
+          handled: false,
+          level: LEVEL_TO_SEVERITY[level],
+          includeStack,
+          maxMessageLength,
+          properties: { ...properties, $error_source: "console" }
+        });
+      } finally {
+        isCapturing = false;
+      }
+    };
+  }
+  return () => {
+    for (const [level, original] of originals) {
+      console[level] = original;
+    }
+  };
+}
+
 // src/LazyClient.ts
 function createLazyClient() {
   let _inner = null;
@@ -1737,5 +1796,6 @@ export {
   createLogger,
   generateUUID,
   nowISO,
+  patchConsole,
   sha256Hex
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/sunglasses-core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Platform-agnostic event tracking engine for SunGlasses",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",