@drakkar.software/sunglasses-adapter-sentry 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,156 @@
+import { ErrorEventProperties, ISunglassesClient } from '@drakkar.software/sunglasses-core';
+import React from 'react';
+
+/** Minimal mirror of the Sentry `Event` shape we care about. */
+interface SentryLikeEvent {
+    exception?: {
+        values?: Array<{
+            type?: string;
+            value?: string;
+            stacktrace?: {
+                frames?: Array<{
+                    filename?: string;
+                    lineno?: number;
+                    function?: string;
+                }>;
+            };
+        }>;
+    };
+    level?: string;
+    tags?: Record<string, string | number | boolean>;
+}
+type SentryBeforeSendResult = SentryLikeEvent | null | Promise<SentryLikeEvent | null>;
+/**
+ * Configuration for the Sentry → SunGlasses bridge.
+ */
+interface SentryBridgeConfig {
+    /**
+     * Include stack frames in `$error_stack`. Default: `false` (privacy-safe).
+     * Stack frames may expose internal file paths and function names.
+     */
+    includeStack?: boolean;
+    /**
+     * Maximum number of stack frames to include when `includeStack` is `true`.
+     * Default: `5`. Sentry stores frames innermost-last; we take the last N.
+     */
+    maxStackFrames?: number;
+    /**
+     * Truncate error messages to this many characters. Default: `200`.
+     * Error messages sometimes contain user data ("User foo@bar.com not found").
+     */
+    maxMessageLength?: number;
+    /**
+     * Skip errors whose message matches any of these patterns.
+     * Matched errors are not captured by SunGlasses (Sentry still receives them).
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /**
+     * Optional transform applied before `client.capture()`.
+     * Receives typed `ErrorEventProperties`; return a (possibly extended) props
+     * object to capture, or `null` to skip capture entirely.
+     */
+    beforeCapture?: (props: ErrorEventProperties) => Record<string, unknown> | null;
+    /**
+     * When `true`, the bridge returns `null` from `beforeSend`, instructing Sentry
+     * not to transmit the event to its servers. Useful when you want Sentry purely
+     * as a local error capture/parsing engine with no data leaving the device.
+     *
+     * Compatible with omitting the DSN entirely — Sentry initialises fine without
+     * one, still attaches global error handlers, and still fires `beforeSend`.
+     *
+     * Default: `false`.
+     */
+    suppressSentrySend?: boolean;
+}
+/**
+ * Creates a Sentry `beforeSend` callback that captures errors as SunGlasses
+ * `$error` events. Works with `@sentry/browser`, `@sentry/react`, and
+ * `@sentry/react-native` — any Sentry SDK that supports `beforeSend`.
+ *
+ * @param client - SunGlasses client instance.
+ * @param config - Optional bridge configuration.
+ * @param originalBeforeSend - Existing `beforeSend` callback to chain after this one.
+ *
+ * @example
+ * ```ts
+ * // Mode A — both Sentry and SunGlasses receive errors
+ * Sentry.init({
+ *   dsn: 'https://...',
+ *   beforeSend: createSentryBeforeSend(client),
+ * });
+ *
+ * // Mode B — SunGlasses only, nothing sent to Sentry servers
+ * Sentry.init({
+ *   beforeSend: createSentryBeforeSend(client, { suppressSentrySend: true }),
+ * });
+ * ```
+ */
+declare function createSentryBeforeSend(client: ISunglassesClient, config?: SentryBridgeConfig, originalBeforeSend?: (event: SentryLikeEvent, hint: unknown) => SentryBeforeSendResult): (event: SentryLikeEvent, hint: unknown) => SentryBeforeSendResult;
+
+/**
+ * Configuration for `SunglassesErrorBoundary`.
+ */
+interface ErrorBoundaryConfig {
+    /**
+     * Include the stack trace in `$error_stack`. Default: `false` (privacy-safe).
+     * Stack traces may expose internal file paths and function names.
+     */
+    includeStack?: boolean;
+    /**
+     * Maximum number of stack frames to include when `includeStack` is `true`.
+     * Default: `5`.
+     */
+    maxStackFrames?: number;
+    /**
+     * Truncate error messages to this many characters. Default: `200`.
+     * Error messages sometimes contain user data.
+     */
+    maxMessageLength?: number;
+    /**
+     * Skip errors whose message matches any of these patterns.
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /**
+     * Optional transform applied before `client.capture()`.
+     * Receives typed `ErrorEventProperties`; return a (possibly extended) props
+     * object to capture, or `null` to skip capture entirely.
+     */
+    beforeCapture?: (props: ErrorEventProperties) => Record<string, unknown> | null;
+}
+interface Props {
+    /** SunGlasses client instance that will receive `$error` capture events. */
+    client: ISunglassesClient;
+    /** Rendered when an error is caught. Defaults to rendering nothing. */
+    fallback?: React.ReactNode;
+    /** Error capture configuration. */
+    config?: ErrorBoundaryConfig;
+    children: React.ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+/**
+ * React error boundary that captures render-phase errors as SunGlasses events.
+ *
+ * Fires `client.capture('$error', { ..., $error_handled: true })` when a
+ * descendant component throws during rendering. Complements the Sentry bridge
+ * (which covers unhandled global errors) by catching errors at component
+ * boundaries before they propagate to the global handler.
+ *
+ * @example
+ * ```tsx
+ * <SunglassesErrorBoundary client={client} fallback={<ErrorPage />}>
+ *   <App />
+ * </SunglassesErrorBoundary>
+ * ```
+ */
+declare class SunglassesErrorBoundary extends React.Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error): void;
+    render(): React.ReactNode;
+}
+
+export { type ErrorBoundaryConfig, type SentryBridgeConfig, SunglassesErrorBoundary, createSentryBeforeSend };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { ErrorEventProperties, ISunglassesClient } from '@drakkar.software/sunglasses-core';
+import React from 'react';
+
+/** Minimal mirror of the Sentry `Event` shape we care about. */
+interface SentryLikeEvent {
+    exception?: {
+        values?: Array<{
+            type?: string;
+            value?: string;
+            stacktrace?: {
+                frames?: Array<{
+                    filename?: string;
+                    lineno?: number;
+                    function?: string;
+                }>;
+            };
+        }>;
+    };
+    level?: string;
+    tags?: Record<string, string | number | boolean>;
+}
+type SentryBeforeSendResult = SentryLikeEvent | null | Promise<SentryLikeEvent | null>;
+/**
+ * Configuration for the Sentry → SunGlasses bridge.
+ */
+interface SentryBridgeConfig {
+    /**
+     * Include stack frames in `$error_stack`. Default: `false` (privacy-safe).
+     * Stack frames may expose internal file paths and function names.
+     */
+    includeStack?: boolean;
+    /**
+     * Maximum number of stack frames to include when `includeStack` is `true`.
+     * Default: `5`. Sentry stores frames innermost-last; we take the last N.
+     */
+    maxStackFrames?: number;
+    /**
+     * Truncate error messages to this many characters. Default: `200`.
+     * Error messages sometimes contain user data ("User foo@bar.com not found").
+     */
+    maxMessageLength?: number;
+    /**
+     * Skip errors whose message matches any of these patterns.
+     * Matched errors are not captured by SunGlasses (Sentry still receives them).
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /**
+     * Optional transform applied before `client.capture()`.
+     * Receives typed `ErrorEventProperties`; return a (possibly extended) props
+     * object to capture, or `null` to skip capture entirely.
+     */
+    beforeCapture?: (props: ErrorEventProperties) => Record<string, unknown> | null;
+    /**
+     * When `true`, the bridge returns `null` from `beforeSend`, instructing Sentry
+     * not to transmit the event to its servers. Useful when you want Sentry purely
+     * as a local error capture/parsing engine with no data leaving the device.
+     *
+     * Compatible with omitting the DSN entirely — Sentry initialises fine without
+     * one, still attaches global error handlers, and still fires `beforeSend`.
+     *
+     * Default: `false`.
+     */
+    suppressSentrySend?: boolean;
+}
+/**
+ * Creates a Sentry `beforeSend` callback that captures errors as SunGlasses
+ * `$error` events. Works with `@sentry/browser`, `@sentry/react`, and
+ * `@sentry/react-native` — any Sentry SDK that supports `beforeSend`.
+ *
+ * @param client - SunGlasses client instance.
+ * @param config - Optional bridge configuration.
+ * @param originalBeforeSend - Existing `beforeSend` callback to chain after this one.
+ *
+ * @example
+ * ```ts
+ * // Mode A — both Sentry and SunGlasses receive errors
+ * Sentry.init({
+ *   dsn: 'https://...',
+ *   beforeSend: createSentryBeforeSend(client),
+ * });
+ *
+ * // Mode B — SunGlasses only, nothing sent to Sentry servers
+ * Sentry.init({
+ *   beforeSend: createSentryBeforeSend(client, { suppressSentrySend: true }),
+ * });
+ * ```
+ */
+declare function createSentryBeforeSend(client: ISunglassesClient, config?: SentryBridgeConfig, originalBeforeSend?: (event: SentryLikeEvent, hint: unknown) => SentryBeforeSendResult): (event: SentryLikeEvent, hint: unknown) => SentryBeforeSendResult;
+
+/**
+ * Configuration for `SunglassesErrorBoundary`.
+ */
+interface ErrorBoundaryConfig {
+    /**
+     * Include the stack trace in `$error_stack`. Default: `false` (privacy-safe).
+     * Stack traces may expose internal file paths and function names.
+     */
+    includeStack?: boolean;
+    /**
+     * Maximum number of stack frames to include when `includeStack` is `true`.
+     * Default: `5`.
+     */
+    maxStackFrames?: number;
+    /**
+     * Truncate error messages to this many characters. Default: `200`.
+     * Error messages sometimes contain user data.
+     */
+    maxMessageLength?: number;
+    /**
+     * Skip errors whose message matches any of these patterns.
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /**
+     * Optional transform applied before `client.capture()`.
+     * Receives typed `ErrorEventProperties`; return a (possibly extended) props
+     * object to capture, or `null` to skip capture entirely.
+     */
+    beforeCapture?: (props: ErrorEventProperties) => Record<string, unknown> | null;
+}
+interface Props {
+    /** SunGlasses client instance that will receive `$error` capture events. */
+    client: ISunglassesClient;
+    /** Rendered when an error is caught. Defaults to rendering nothing. */
+    fallback?: React.ReactNode;
+    /** Error capture configuration. */
+    config?: ErrorBoundaryConfig;
+    children: React.ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+/**
+ * React error boundary that captures render-phase errors as SunGlasses events.
+ *
+ * Fires `client.capture('$error', { ..., $error_handled: true })` when a
+ * descendant component throws during rendering. Complements the Sentry bridge
+ * (which covers unhandled global errors) by catching errors at component
+ * boundaries before they propagate to the global handler.
+ *
+ * @example
+ * ```tsx
+ * <SunglassesErrorBoundary client={client} fallback={<ErrorPage />}>
+ *   <App />
+ * </SunglassesErrorBoundary>
+ * ```
+ */
+declare class SunglassesErrorBoundary extends React.Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error): void;
+    render(): React.ReactNode;
+}
+
+export { type ErrorBoundaryConfig, type SentryBridgeConfig, SunglassesErrorBoundary, createSentryBeforeSend };

package/dist/index.js

@@ -0,0 +1,126 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SunglassesErrorBoundary: () => SunglassesErrorBoundary,
+  createSentryBeforeSend: () => createSentryBeforeSend
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/createSentryBeforeSend.ts
+function createSentryBeforeSend(client, config = {}, originalBeforeSend) {
+  const {
+    includeStack = false,
+    maxStackFrames = 5,
+    maxMessageLength = 200,
+    ignorePatterns = [],
+    beforeCapture,
+    suppressSentrySend = false
+  } = config;
+  return (event, hint) => {
+    const sentryResult = originalBeforeSend ? originalBeforeSend(event, hint) : event;
+    const result = suppressSentrySend ? null : sentryResult;
+    const exc = event.exception?.values?.[0];
+    const rawMessage = exc?.value ?? "";
+    const message = rawMessage.slice(0, maxMessageLength);
+    if (!ignorePatterns.some((p) => p.test(rawMessage))) {
+      let props = {
+        $error_message: message,
+        $error_type: exc?.type ?? "Error",
+        $error_handled: false,
+        $error_level: event.level ?? "error"
+      };
+      if (includeStack && exc?.stacktrace?.frames) {
+        const frames = exc.stacktrace.frames.slice(-maxStackFrames).map((f) => `${f.function ?? "?"} (${f.filename ?? "?"}:${f.lineno ?? "?"})`).join("\n");
+        props = { ...props, $error_stack: frames };
+      }
+      if (beforeCapture) {
+        const transformed = beforeCapture(props);
+        if (!transformed) return result;
+        client.capture("$error", transformed);
+      } else {
+        client.capture("$error", props);
+      }
+    }
+    return result;
+  };
+}
+
+// src/SunglassesErrorBoundary.tsx
+var import_react = __toESM(require("react"));
+var SunglassesErrorBoundary = class extends import_react.default.Component {
+  constructor() {
+    super(...arguments);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+  componentDidCatch(error) {
+    const { client, config = {} } = this.props;
+    const {
+      maxMessageLength = 200,
+      maxStackFrames = 5,
+      includeStack = false,
+      ignorePatterns = [],
+      beforeCapture
+    } = config;
+    const rawMessage = error.message;
+    const message = rawMessage.slice(0, maxMessageLength);
+    if (ignorePatterns.some((p) => p.test(rawMessage))) return;
+    let props = {
+      $error_message: message,
+      $error_type: error.name,
+      $error_handled: true,
+      $error_level: "error"
+    };
+    if (includeStack && error.stack) {
+      const frames = error.stack.split("\n").filter((line) => line.trim().startsWith("at ")).slice(0, maxStackFrames).join("\n");
+      props = { ...props, $error_stack: frames };
+    }
+    if (beforeCapture) {
+      const transformed = beforeCapture(props);
+      if (!transformed) return;
+      client.capture("$error", transformed);
+    } else {
+      client.capture("$error", props);
+    }
+  }
+  render() {
+    if (this.state.hasError) return this.props.fallback ?? null;
+    return this.props.children;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SunglassesErrorBoundary,
+  createSentryBeforeSend
+});

package/dist/index.mjs

@@ -0,0 +1,88 @@
+// src/createSentryBeforeSend.ts
+function createSentryBeforeSend(client, config = {}, originalBeforeSend) {
+  const {
+    includeStack = false,
+    maxStackFrames = 5,
+    maxMessageLength = 200,
+    ignorePatterns = [],
+    beforeCapture,
+    suppressSentrySend = false
+  } = config;
+  return (event, hint) => {
+    const sentryResult = originalBeforeSend ? originalBeforeSend(event, hint) : event;
+    const result = suppressSentrySend ? null : sentryResult;
+    const exc = event.exception?.values?.[0];
+    const rawMessage = exc?.value ?? "";
+    const message = rawMessage.slice(0, maxMessageLength);
+    if (!ignorePatterns.some((p) => p.test(rawMessage))) {
+      let props = {
+        $error_message: message,
+        $error_type: exc?.type ?? "Error",
+        $error_handled: false,
+        $error_level: event.level ?? "error"
+      };
+      if (includeStack && exc?.stacktrace?.frames) {
+        const frames = exc.stacktrace.frames.slice(-maxStackFrames).map((f) => `${f.function ?? "?"} (${f.filename ?? "?"}:${f.lineno ?? "?"})`).join("\n");
+        props = { ...props, $error_stack: frames };
+      }
+      if (beforeCapture) {
+        const transformed = beforeCapture(props);
+        if (!transformed) return result;
+        client.capture("$error", transformed);
+      } else {
+        client.capture("$error", props);
+      }
+    }
+    return result;
+  };
+}
+
+// src/SunglassesErrorBoundary.tsx
+import React from "react";
+var SunglassesErrorBoundary = class extends React.Component {
+  constructor() {
+    super(...arguments);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+  componentDidCatch(error) {
+    const { client, config = {} } = this.props;
+    const {
+      maxMessageLength = 200,
+      maxStackFrames = 5,
+      includeStack = false,
+      ignorePatterns = [],
+      beforeCapture
+    } = config;
+    const rawMessage = error.message;
+    const message = rawMessage.slice(0, maxMessageLength);
+    if (ignorePatterns.some((p) => p.test(rawMessage))) return;
+    let props = {
+      $error_message: message,
+      $error_type: error.name,
+      $error_handled: true,
+      $error_level: "error"
+    };
+    if (includeStack && error.stack) {
+      const frames = error.stack.split("\n").filter((line) => line.trim().startsWith("at ")).slice(0, maxStackFrames).join("\n");
+      props = { ...props, $error_stack: frames };
+    }
+    if (beforeCapture) {
+      const transformed = beforeCapture(props);
+      if (!transformed) return;
+      client.capture("$error", transformed);
+    } else {
+      client.capture("$error", props);
+    }
+  }
+  render() {
+    if (this.state.hasError) return this.props.fallback ?? null;
+    return this.props.children;
+  }
+};
+export {
+  SunglassesErrorBoundary,
+  createSentryBeforeSend
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@drakkar.software/sunglasses-adapter-sentry",
+  "version": "0.1.0",
+  "description": "Sentry bridge and React error boundary for SunGlasses — captures errors as analytics events",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@drakkar.software/sunglasses-core": "0.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@drakkar.software/sunglasses-tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}