@ogcio/o11y-sdk-react 0.1.0-beta.7 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.3.0](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-react@v0.2.0...@ogcio/o11y-sdk-react@v0.3.0) (2025-07-31)
+
+
+### Features
+
+* **sdk-react:** pii detection ([#180](https://github.com/ogcio/o11y/issues/180)) ([57ddf2f](https://github.com/ogcio/o11y/commit/57ddf2f4792207e62ea6bf9ea797bc652942db06))
+* update AWS secrets manager connection AB[#29565](https://github.com/ogcio/o11y/issues/29565) ([#166](https://github.com/ogcio/o11y/issues/166)) ([962c03d](https://github.com/ogcio/o11y/commit/962c03de2da4060a81aa603c355f3d60cafe3c30))
+
+## [0.2.0](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-react@v0.1.0-beta.7...@ogcio/o11y-sdk-react@v0.2.0) (2025-06-24)
+
+
+### Features
+
+* late june deps update ([#154](https://github.com/ogcio/o11y/issues/154)) ([a772622](https://github.com/ogcio/o11y/commit/a7726225a59b2dbcd4326919323d935843b2f93f))
+
+
+### Miscellaneous Chores
+
+* **deps-dev:** bump @types/node to `24` AB[#29294](https://github.com/ogcio/o11y/issues/29294) ([3c74c28](https://github.com/ogcio/o11y/commit/3c74c28af41af8403220368ac72a90e40c3e15ae))
+* **deps-dev:** bump the root-deps group across 1 directory with 3 updates ([#150](https://github.com/ogcio/o11y/issues/150)) ([9d574d1](https://github.com/ogcio/o11y/commit/9d574d1af0964fc4af991d677b443015921d93f6))
+
 ## [0.1.0-beta.7](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-react@v0.1.0-beta.6...@ogcio/o11y-sdk-react@v0.1.0-beta.7) (2025-06-04)
 
 

package/dist/lib/index.d.ts

@@ -33,6 +33,16 @@ export interface FaroSDKConfig extends SDKConfig {
      * @example http://localhost:9000
      */
     corsTraceHeaders?: string;
+    /**
+     * Enable/Disable PII detection for GDPR data
+     */
+    detection?: {
+        /**
+         * Redact email address
+         * @default true
+         */
+        email?: boolean;
+    };
 }
 export type SDKCollectorMode = "single" | "batch";
 export type SDKLogLevel = "NONE" | "ERROR" | "WARN" | "INFO" | "DEBUG" | "VERBOSE" | "ALL";

package/dist/lib/instrumentation.faro.d.ts

@@ -1,3 +1,3 @@
-import type { FaroSDKConfig } from "./index.js";
 import { type Faro } from "@grafana/faro-react";
+import type { FaroSDKConfig } from "./index.js";
 export default function buildFaroInstrumentation(config?: FaroSDKConfig): Faro | undefined;

package/dist/lib/instrumentation.faro.js

@@ -1,10 +1,11 @@
 import { ErrorsInstrumentation, getWebInstrumentations, initializeFaro, WebVitalsInstrumentation, } from "@grafana/faro-react";
+import { TracingInstrumentation } from "@grafana/faro-web-tracing";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
 import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
 import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
-import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
-import { TracingInstrumentation } from "@grafana/faro-web-tracing";
+import { _beforeSend } from "./internals/hooks.js";
 export default function buildFaroInstrumentation(config) {
     if (!config) {
         console.warn("observability config not set. Skipping Faro OpenTelemetry instrumentation.");
@@ -18,6 +19,14 @@ export default function buildFaroInstrumentation(config) {
         console.error("collectorUrl does not use a valid format. Skipping Faro OpenTelemetry instrumentation.");
         return;
     }
+    if (!config.detection) {
+        config.detection = {
+            email: true,
+        };
+    }
+    if (config.detection.email === undefined) {
+        config.detection.email = true;
+    }
     try {
         diag.setLogger(new DiagConsoleLogger(), config.diagLogLevel
             ? DiagLogLevel[config.diagLogLevel]
@@ -30,6 +39,7 @@ export default function buildFaroInstrumentation(config) {
             batching: {
                 enabled: !(config.collectorMode === "single"),
             },
+            beforeSend: config.detection.email ? _beforeSend : undefined,
             instrumentations: [
                 ...getWebInstrumentations({
                     captureConsole: true,

package/dist/lib/internals/hooks.d.ts

@@ -0,0 +1,2 @@
+import { APIEvent, TransportItem } from "@grafana/faro-web-sdk";
+export declare function _beforeSend(item: TransportItem<APIEvent>): TransportItem<APIEvent> | null;

package/dist/lib/internals/hooks.js

@@ -0,0 +1,32 @@
+import { _cleanStringPII } from "./pii-detection.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function _cleanObjectPII(data, type) {
+    if (!data) {
+        return;
+    }
+    if (Array.isArray(data)) {
+        data.forEach((item, index) => {
+            if (typeof item === "string") {
+                data[index] = _cleanStringPII(data[index], type);
+                return;
+            }
+            if (typeof item === "object") {
+                _cleanObjectPII(item, type);
+            }
+        });
+    }
+    if (typeof data === "object") {
+        for (const key in data) {
+            if (typeof data[key] === "string") {
+                data[key] = _cleanStringPII(data[key], type);
+            }
+            if (typeof data[key] === "object") {
+                _cleanObjectPII(data[key], type);
+            }
+        }
+    }
+}
+export function _beforeSend(item) {
+    _cleanObjectPII(item, item.type);
+    return item;
+}

package/dist/lib/internals/pii-detection.d.ts

@@ -0,0 +1,12 @@
+import { TransportItemType } from "@grafana/faro-web-sdk";
+/**
+ * Cleans a string by redacting email addresses and emitting metrics for PII.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ * Metrics are emitted for each domain found in redacted email addresses.
+ *
+ * @param {string} value - The input string to sanitize.
+ * @param {TransportItemType} source - The source context of the input.
+ * @returns {string} The cleaned string with any email addresses replaced by `[REDACTED EMAIL]`.
+ */
+export declare function _cleanStringPII(value: string, source: TransportItemType): string;

package/dist/lib/internals/pii-detection.js

@@ -0,0 +1,78 @@
+import { faro } from "@grafana/faro-web-sdk";
+const EMAIL_REGEX = /[a-zA-Z0-9._%+-]+@([a-zA-Z0-9.-]+\.[a-z]{2,})/gi;
+/**
+ * Redacts all email addresses in the input string and collects metadata.
+ *
+ * @param {string} value The input string potentially containing email addresses.
+ * @returns {{
+ *   redacted: string,
+ *   count: number,
+ *   domains: Record<string, number>
+ * }}
+ *
+ * An object containing:
+ *   - `redacted`: the string with email addresses replaced by `[REDACTED EMAIL]`
+ *   - `count`: total number of email addresses redacted
+ *   - `domains`: a map of domain names to the number of times they were redacted
+ */
+function _redactEmails(value) {
+    let count = 0;
+    const domains = {};
+    const redacted = value.replace(EMAIL_REGEX, (_, domain) => {
+        count++;
+        domains[domain] = (domains[domain] || 0) + 1;
+        return "[REDACTED EMAIL]";
+    });
+    return { redacted, count, domains };
+}
+/**
+ * Checks whether a string contains URI-encoded components.
+ *
+ * @param {string} value - The string to inspect.
+ * @returns {boolean} `true` if the string is encoded, `false` otherwise.
+ */
+function _containsEncodedComponents(value) {
+    try {
+        return decodeURI(value) !== decodeURIComponent(value);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cleans a string by redacting email addresses and emitting metrics for PII.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ * Metrics are emitted for each domain found in redacted email addresses.
+ *
+ * @param {string} value - The input string to sanitize.
+ * @param {TransportItemType} source - The source context of the input.
+ * @returns {string} The cleaned string with any email addresses replaced by `[REDACTED EMAIL]`.
+ */
+export function _cleanStringPII(value, source) {
+    let kind = "string";
+    let decodedValue = value;
+    if (_containsEncodedComponents(value)) {
+        decodedValue = decodeURIComponent(value);
+        kind = "url";
+    }
+    const { redacted, count, domains } = _redactEmails(decodedValue);
+    if (count > 0) {
+        for (const [domain, domainCount] of Object.entries(domains)) {
+            faro.api.pushMeasurement({
+                type: "faro_o11y_pii_redaction",
+                values: {
+                    redacted: domainCount,
+                },
+            }, {
+                context: {
+                    pii_type: "email",
+                    redaction_source: source,
+                    pii_email_domain: domain,
+                    pii_format: kind,
+                },
+            });
+        }
+    }
+    return redacted;
+}

package/dist/vitest.config.js

@@ -3,7 +3,7 @@ export default defineConfig({
     test: {
         globals: true,
         watch: false,
-        include: ["**/test/*.test.ts"],
+        include: ["**/*.test.ts"],
         exclude: ["**/fixtures/**", "**/dist/**"],
         poolOptions: {
             threads: {

package/lib/index.ts

@@ -34,6 +34,16 @@ export interface FaroSDKConfig extends SDKConfig {
    * @example http://localhost:9000
    */
   corsTraceHeaders?: string;
+  /**
+   * Enable/Disable PII detection for GDPR data
+   */
+  detection?: {
+    /**
+     * Redact email address
+     * @default true
+     */
+    email?: boolean;
+  };
 }
 
 export type SDKCollectorMode = "single" | "batch";

package/lib/instrumentation.faro.ts

@@ -1,4 +1,3 @@
-import type { FaroSDKConfig } from "./index.js";
 import {
   ErrorsInstrumentation,
   getWebInstrumentations,
@@ -6,12 +5,14 @@ import {
   WebVitalsInstrumentation,
   type Faro,
 } from "@grafana/faro-react";
+import { TracingInstrumentation } from "@grafana/faro-web-tracing";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
 import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
 import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
-import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
-import { TracingInstrumentation } from "@grafana/faro-web-tracing";
+import type { FaroSDKConfig } from "./index.js";
+import { _beforeSend } from "./internals/hooks.js";
 
 export default function buildFaroInstrumentation(
   config?: FaroSDKConfig,
@@ -37,6 +38,16 @@ export default function buildFaroInstrumentation(
     return;
   }
 
+  if (!config.detection) {
+    config.detection = {
+      email: true,
+    };
+  }
+
+  if (config.detection.email === undefined) {
+    config.detection.email = true;
+  }
+
   try {
     diag.setLogger(
       new DiagConsoleLogger(),
@@ -53,11 +64,11 @@ export default function buildFaroInstrumentation(
       batching: {
         enabled: !(config.collectorMode === "single"),
       },
+      beforeSend: config.detection.email ? _beforeSend : undefined,
       instrumentations: [
         ...getWebInstrumentations({
           captureConsole: true,
         }),
-
         new ErrorsInstrumentation(),
         new WebVitalsInstrumentation(),
         new TracingInstrumentation({

package/lib/internals/hooks.ts

@@ -0,0 +1,45 @@
+import {
+  APIEvent,
+  TransportItem,
+  TransportItemType,
+} from "@grafana/faro-web-sdk";
+import { _cleanStringPII } from "./pii-detection.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function _cleanObjectPII(data: any, type: TransportItemType) {
+  if (!data) {
+    return;
+  }
+
+  if (Array.isArray(data)) {
+    data.forEach((item, index) => {
+      if (typeof item === "string") {
+        data[index] = _cleanStringPII(data[index], type);
+        return;
+      }
+
+      if (typeof item === "object") {
+        _cleanObjectPII(item, type);
+      }
+    });
+  }
+
+  if (typeof data === "object") {
+    for (const key in data) {
+      if (typeof data[key] === "string") {
+        data[key] = _cleanStringPII(data[key], type);
+      }
+
+      if (typeof data[key] === "object") {
+        _cleanObjectPII(data[key], type);
+      }
+    }
+  }
+}
+
+export function _beforeSend(
+  item: TransportItem<APIEvent>,
+): TransportItem<APIEvent> | null {
+  _cleanObjectPII(item, item.type);
+  return item;
+}

package/lib/internals/pii-detection.ts

@@ -0,0 +1,96 @@
+import { faro, TransportItemType } from "@grafana/faro-web-sdk";
+
+const EMAIL_REGEX = /[a-zA-Z0-9._%+-]+@([a-zA-Z0-9.-]+\.[a-z]{2,})/gi;
+
+/**
+ * Redacts all email addresses in the input string and collects metadata.
+ *
+ * @param {string} value The input string potentially containing email addresses.
+ * @returns {{
+ *   redacted: string,
+ *   count: number,
+ *   domains: Record<string, number>
+ * }}
+ *
+ * An object containing:
+ *   - `redacted`: the string with email addresses replaced by `[REDACTED EMAIL]`
+ *   - `count`: total number of email addresses redacted
+ *   - `domains`: a map of domain names to the number of times they were redacted
+ */
+function _redactEmails(value: string): {
+  redacted: string;
+  count: number;
+  domains: Record<string, number>;
+} {
+  let count = 0;
+  const domains: Record<string, number> = {};
+
+  const redacted = value.replace(EMAIL_REGEX, (_, domain) => {
+    count++;
+    domains[domain] = (domains[domain] || 0) + 1;
+    return "[REDACTED EMAIL]";
+  });
+
+  return { redacted, count, domains };
+}
+
+/**
+ * Checks whether a string contains URI-encoded components.
+ *
+ * @param {string} value - The string to inspect.
+ * @returns {boolean} `true` if the string is encoded, `false` otherwise.
+ */
+function _containsEncodedComponents(value: string) {
+  try {
+    return decodeURI(value) !== decodeURIComponent(value);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Cleans a string by redacting email addresses and emitting metrics for PII.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ * Metrics are emitted for each domain found in redacted email addresses.
+ *
+ * @param {string} value - The input string to sanitize.
+ * @param {TransportItemType} source - The source context of the input.
+ * @returns {string} The cleaned string with any email addresses replaced by `[REDACTED EMAIL]`.
+ */
+export function _cleanStringPII(
+  value: string,
+  source: TransportItemType,
+): string {
+  let kind: "string" | "url" = "string";
+  let decodedValue = value;
+
+  if (_containsEncodedComponents(value)) {
+    decodedValue = decodeURIComponent(value);
+    kind = "url";
+  }
+
+  const { redacted, count, domains } = _redactEmails(decodedValue);
+
+  if (count > 0) {
+    for (const [domain, domainCount] of Object.entries(domains)) {
+      faro.api.pushMeasurement(
+        {
+          type: "faro_o11y_pii_redaction",
+          values: {
+            redacted: domainCount,
+          },
+        },
+        {
+          context: {
+            pii_type: "email",
+            redaction_source: source,
+            pii_email_domain: domain,
+            pii_format: kind,
+          },
+        },
+      );
+    }
+  }
+  return redacted;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogcio/o11y-sdk-react",
-  "version": "0.1.0-beta.7",
+  "version": "0.3.0",
   "description": "Opentelemetry standard instrumentation SDK for React based project",
   "main": "dist/index.js",
   "type": "module",
@@ -29,11 +29,11 @@
     "@opentelemetry/instrumentation-user-interaction": "^0.47.0"
   },
   "devDependencies": {
-    "@types/node": "^22.15.29",
-    "@vitest/coverage-v8": "^3.2.1",
-    "tsx": "^4.19.4",
+    "@types/node": "^24.0.10",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.1"
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",

package/test/config.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import buildFaroInstrumentation from "../lib/instrumentation.faro";
+import { initializeFaro } from "@grafana/faro-react";
+import { _beforeSend } from "../lib/internals/hooks";
+import { FaroSDKConfig } from "../lib";
+
+// Mock dependencies
+vi.mock("@grafana/faro-react", async () => {
+  const actual = await vi.importActual<any>("@grafana/faro-react");
+  return {
+    ...actual,
+    initializeFaro: vi.fn(() => ({ fakeFaro: true })),
+    getWebInstrumentations: vi.fn(() => ["webInstrumentation"]),
+    ErrorsInstrumentation: vi.fn(() => "errorsInstrumentation"),
+    WebVitalsInstrumentation: vi.fn(() => "webVitalsInstrumentation"),
+  };
+});
+
+vi.mock("@grafana/faro-web-tracing", () => ({
+  TracingInstrumentation: vi.fn(() => "tracingInstrumentation"),
+}));
+
+vi.mock("@opentelemetry/core", () => ({
+  W3CTraceContextPropagator: vi.fn(() => "tracePropagator"),
+}));
+
+vi.mock("@opentelemetry/instrumentation-document-load", () => ({
+  DocumentLoadInstrumentation: vi.fn(() => "docLoadInstrumentation"),
+}));
+
+vi.mock("@opentelemetry/instrumentation-fetch", () => ({
+  FetchInstrumentation: vi.fn((opts) => ({
+    ...opts,
+    name: "fetchInstrumentation",
+  })),
+}));
+
+vi.mock("@opentelemetry/instrumentation-user-interaction", () => ({
+  UserInteractionInstrumentation: vi.fn(() => "userInteractionInstrumentation"),
+}));
+
+vi.mock("./internals/hooks", () => ({
+  _beforeSend: vi.fn(() => "hooked"),
+}));
+
+describe("buildFaroInstrumentation", () => {
+  const validConfig = {
+    collectorUrl: "https://valid-url.com",
+    serviceName: "test-app",
+    detection: {
+      email: true,
+    },
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    console.warn = vi.fn();
+    console.error = vi.fn();
+    console.log = vi.fn();
+  });
+
+  it("returns undefined and warns if config is not provided", () => {
+    const result = buildFaroInstrumentation();
+    expect(console.warn).toHaveBeenCalledWith(
+      "observability config not set. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined and warns if collectorUrl is missing", () => {
+    const result = buildFaroInstrumentation({
+      ...validConfig,
+      collectorUrl: undefined!,
+    });
+    expect(console.warn).toHaveBeenCalledWith(
+      "collectorUrl not set. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined and errors if collectorUrl is invalid", () => {
+    const result = buildFaroInstrumentation({
+      ...validConfig,
+      collectorUrl: "not-a-url",
+    });
+    expect(console.error).toHaveBeenCalledWith(
+      "collectorUrl does not use a valid format. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it("defaults detection.email to true if not provided", () => {
+    const config = {
+      ...validConfig,
+      detection: {},
+    };
+    buildFaroInstrumentation(config);
+    expect(initializeFaro).toHaveBeenCalled();
+    expect(config.detection.email).toBe(true);
+  });
+
+  it("sets beforeSend if detection.email is true", () => {
+    buildFaroInstrumentation({ ...validConfig, detection: { email: true } });
+    expect(initializeFaro).toHaveBeenCalledWith(
+      expect.objectContaining({
+        beforeSend: _beforeSend,
+      }),
+    );
+  });
+
+  it("does not set beforeSend if detection.email is false", () => {
+    buildFaroInstrumentation({ ...validConfig, detection: { email: false } });
+    expect(initializeFaro).toHaveBeenCalledWith(
+      expect.not.objectContaining({
+        beforeSend: expect.any(Function),
+      }),
+    );
+  });
+
+  it("disables batching when collectorMode is 'single'", () => {
+    buildFaroInstrumentation({ ...validConfig, collectorMode: "single" });
+    expect(initializeFaro).toHaveBeenCalledWith(
+      expect.objectContaining({
+        batching: {
+          enabled: false,
+        },
+      }),
+    );
+  });
+
+  it("sets diagLogLevel if provided", async () => {
+    const { DiagLogLevel } = await import("@opentelemetry/api");
+    const setLoggerSpy = vi
+      .spyOn(await import("@opentelemetry/api"), "diag", "get")
+      .mockReturnValue({
+        setLogger: vi.fn(),
+      });
+
+    buildFaroInstrumentation({ ...validConfig, diagLogLevel: "DEBUG" });
+
+    expect(setLoggerSpy().setLogger).toHaveBeenCalledWith(
+      expect.anything(),
+      DiagLogLevel.DEBUG,
+    );
+  });
+
+  it("handles initialization failure and logs error", () => {
+    (initializeFaro as any).mockImplementationOnce(() => {
+      throw new Error("init failed");
+    });
+
+    const result = buildFaroInstrumentation(validConfig);
+    expect(console.error).toHaveBeenCalledWith(
+      "Error starting Faro OpenTelemetry instrumentation:",
+      expect.any(Error),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it("returns the faro object on successful initialization", () => {
+    const result = buildFaroInstrumentation(validConfig);
+    expect(console.log).toHaveBeenCalledWith(
+      "Faro OpenTelemetry instrumentation started successfully.",
+    );
+    expect(result).toEqual({ fakeFaro: true });
+  });
+
+  it("sets default detection config if detection is not provided", () => {
+    const config = {
+      ...validConfig,
+      detection: undefined,
+    };
+
+    buildFaroInstrumentation(config);
+
+    expect(config.detection).toEqual({ email: true });
+    expect(initializeFaro).toHaveBeenCalledWith(
+      expect.objectContaining({
+        beforeSend: _beforeSend,
+      }),
+    );
+  });
+
+  it("handles comma-separated corsTraceHeaders", async () => {
+    buildFaroInstrumentation({
+      ...validConfig,
+      corsTraceHeaders: "https://site1.com,https://site2.com",
+    });
+
+    const { FetchInstrumentation } = await import(
+      "@opentelemetry/instrumentation-fetch"
+    );
+    expect(FetchInstrumentation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        propagateTraceHeaderCorsUrls: [
+          new RegExp("https://site1.com"),
+          new RegExp("https://site2.com"),
+        ],
+      }),
+    );
+  });
+});

package/test/lib/hooks.test.ts

@@ -0,0 +1,149 @@
+import {
+  LogEvent,
+  LogLevel,
+  TransportItem,
+  TransportItemType,
+} from "@grafana/faro-web-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { _beforeSend } from "../../lib/internals/hooks";
+
+// Mock faro.api.pushMeasurement
+vi.mock("@grafana/faro-web-sdk", async () => {
+  const actual = await vi.importActual<any>("@grafana/faro-web-sdk");
+  return {
+    ...actual,
+    faro: {
+      api: {
+        pushMeasurement: vi.fn(),
+      },
+    },
+  };
+});
+
+import { faro } from "@grafana/faro-web-sdk";
+
+describe("_beforeSend", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should deeply redact PII in object", () => {
+    const item = {
+      type: TransportItemType.LOG,
+      payload: {
+        level: LogLevel.INFO,
+        context: {},
+        timestamp: Date.now().toString(),
+        message: "my email is bob@abc.com",
+      },
+      meta: {
+        user: {
+          email: "carol@abc.com",
+          attributes: {
+            alternative_email: "foo@xyz.org",
+          },
+        },
+      },
+    } satisfies TransportItem<LogEvent>;
+
+    const redacted: TransportItem<LogEvent> = _beforeSend(
+      item,
+    ) as TransportItem<LogEvent>;
+
+    expect(redacted.payload.message).toBe("my email is [REDACTED EMAIL]");
+    expect(redacted.meta.user).not.toBeNull();
+    expect(redacted.meta.user!.email).toBe("[REDACTED EMAIL]");
+    expect(redacted.meta.user!.attributes).toBeDefined();
+    expect(redacted.meta.user!.attributes!["alternative_email"]).toBe(
+      "[REDACTED EMAIL]",
+    );
+    expect(faro.api.pushMeasurement).toHaveBeenCalledTimes(3);
+  });
+
+  it("should redact email inside arrays of primitives", () => {
+    const item: TransportItem<LogEvent> = {
+      type: TransportItemType.LOG,
+      payload: {
+        message: "start",
+        context: {
+          messages: ["hello", "email: test@abc.com", "ok"],
+        },
+        timestamp: "123",
+        level: LogLevel.INFO,
+      },
+    };
+
+    const redacted = _beforeSend(item)!;
+
+    expect(redacted.payload.context.messages[1]).toBe(
+      "email: [REDACTED EMAIL]",
+    );
+    expect(faro.api.pushMeasurement).toHaveBeenCalledOnce();
+  });
+
+  it("should redact emails in arrays of objects", () => {
+    const item: TransportItem<LogEvent> = {
+      type: TransportItemType.LOG,
+      payload: {
+        message: "checking",
+        context: {
+          events: [
+            { message: "contact a@b.com" },
+            { message: "nothing here" },
+            { note: "try c@d.net" },
+          ],
+        },
+        timestamp: "123",
+        level: LogLevel.INFO,
+      },
+    };
+
+    const redacted = _beforeSend(item)!;
+
+    expect(redacted.payload.context.events[0].message).toBe(
+      "contact [REDACTED EMAIL]",
+    );
+    expect(redacted.payload.context.events[2].note).toBe(
+      "try [REDACTED EMAIL]",
+    );
+    expect(faro.api.pushMeasurement).toHaveBeenCalledTimes(2);
+  });
+
+  it("should not break on nulls, undefined, numbers, booleans", () => {
+    const item: TransportItem<LogEvent> = {
+      type: TransportItemType.LOG,
+      payload: {
+        message: null as any,
+        count: 123,
+        active: true,
+        description: undefined,
+      } as any,
+      meta: null,
+    };
+
+    const redacted = _beforeSend(item)!;
+
+    expect(redacted.payload.message).toBeNull();
+    expect(redacted.payload.count).toBe(123);
+    expect(redacted.payload.active).toBe(true);
+    expect("description" in redacted.payload).toBe(true); // still defined as undefined
+    expect(faro.api.pushMeasurement).not.toHaveBeenCalled();
+  });
+
+  it("should decode and redact encoded emails", () => {
+    const item: TransportItem<LogEvent> = {
+      type: TransportItemType.LOG,
+      payload: {
+        message: "contact%20user%40domain.com",
+        level: LogLevel.INFO,
+        context: {},
+        timestamp: "now",
+      },
+    };
+
+    const redacted = _beforeSend(item)!;
+
+    expect(redacted.payload.message).toBe("contact [REDACTED EMAIL]");
+    expect(faro.api.pushMeasurement).toHaveBeenCalledOnce();
+  });
+});

package/test/lib/pii-detection.test.ts

@@ -0,0 +1,70 @@
+import { TransportItemType } from "@grafana/faro-web-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { _cleanStringPII } from "../../lib/internals/pii-detection";
+
+// Mock faro.api.pushMeasurement
+vi.mock("@grafana/faro-web-sdk", async () => {
+  const actual = await vi.importActual<any>("@grafana/faro-web-sdk");
+  return {
+    ...actual,
+    faro: {
+      api: {
+        pushMeasurement: vi.fn(),
+      },
+    },
+  };
+});
+
+import { faro } from "@grafana/faro-web-sdk";
+
+describe("_cleanStringPII", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should redact email and call pushMeasurement", () => {
+    const input = "Contact me at alice@example.com.";
+    const result = _cleanStringPII(input, TransportItemType.LOG);
+
+    expect(result).toBe("Contact me at [REDACTED EMAIL].");
+    expect(faro.api.pushMeasurement).toHaveBeenCalledOnce();
+    expect(faro.api.pushMeasurement).toHaveBeenCalledWith(
+      {
+        type: "faro_o11y_pii_redaction",
+        values: { redacted: 1 },
+      },
+      {
+        context: {
+          pii_type: "email",
+          redaction_source: TransportItemType.LOG,
+          pii_email_domain: "example.com",
+          pii_format: "string",
+        },
+      },
+    );
+  });
+
+  it("should decode and redact URI-encoded emails", () => {
+    const encoded = "mailto%3Ajohn.doe%40gmail.com";
+    const result = _cleanStringPII(encoded, TransportItemType.EXCEPTION);
+
+    expect(result).toBe("mailto:[REDACTED EMAIL]");
+    expect(faro.api.pushMeasurement).toHaveBeenCalledOnce();
+  });
+
+  it("should return same string when no email present", () => {
+    const input = "Just a normal message.";
+    const result = _cleanStringPII(input, TransportItemType.LOG);
+
+    expect(result).toBe(input);
+    expect(faro.api.pushMeasurement).not.toHaveBeenCalled();
+  });
+
+  it("should return same string when decodeURIComponent fail", () => {
+    const input = "mailto%john.doe%4gmail.com";
+    const result = _cleanStringPII(input, TransportItemType.LOG);
+
+    expect(result).toBe(input);
+    expect(faro.api.pushMeasurement).not.toHaveBeenCalled();
+  });
+});

package/vitest.config.ts

@@ -4,7 +4,7 @@ export default defineConfig({
   test: {
     globals: true,
     watch: false,
-    include: ["**/test/*.test.ts"],
+    include: ["**/*.test.ts"],
     exclude: ["**/fixtures/**", "**/dist/**"],
     poolOptions: {
       threads: {

package/test/index.test.ts

@@ -1,28 +0,0 @@
-import { describe, test, expect, vi } from "vitest";
-import { FaroSDKConfig } from "../lib";
-import { instrumentFaro } from "../index";
-
-vi.mock("../lib/instrumentation.faro", () => ({
-  default: vi.fn(),
-}));
-
-describe("instrumentFaro", () => {
-  test("should call buildFaroInstrumentation with the provided config", async () => {
-    const config: FaroSDKConfig = {
-      serviceName: "custom-service",
-      collectorUrl: "http://custom-collector.com",
-    };
-
-    const buildFaroInstrumentation = await import(
-      "../lib/instrumentation.faro"
-    );
-
-    instrumentFaro(config);
-
-    expect(buildFaroInstrumentation.default).toHaveBeenCalledWith(config);
-  });
-
-  test("should not throw when called without arguments", () => {
-    expect(() => instrumentFaro()).not.toThrow();
-  });
-});