feat: integrate observability

packages/observability/README.md

@@ -0,0 +1,123 @@
+# @mintel/observability
+
+Standardized observability package for the Mintel ecosystem, providing Umami analytics and Sentry/GlitchTip error tracking with a focus on privacy and ad-blocker resilience.
+
+## Features
+
+- **Umami Smart Proxy**: Track analytics without external scripts and hide your Website ID.
+- **Sentry Relay**: Bypass ad-blockers for error tracking by relaying envelopes through your own server.
+- **Unified API**: consistent interface for tracking across multiple projects.
+
+## Installation
+
+```bash
+pnpm add @mintel/observability @sentry/nextjs
+```
+
+## Usage
+
+### 1. Unified Environment (via @mintel/next-utils)
+
+Define the following environment variables:
+
+```bash
+# Analytics
+UMAMI_WEBSITE_ID=your-website-id
+UMAMI_API_ENDPOINT=https://analytics.infra.mintel.me
+
+# Error Tracking
+SENTRY_DSN=your-sentry-dsn
+```
+
+Note: No `NEXT_PUBLIC_` prefix is required for these anymore, as they are handled by server-side proxies.
+
+### 2. Analytics Setup
+
+In your root layout:
+
+```tsx
+import {
+  AnalyticsContextProvider,
+  AnalyticsAutoTracker,
+  UmamiAnalyticsService,
+} from "@mintel/observability";
+
+const analytics = new UmamiAnalyticsService({
+  enabled: true,
+  websiteId: process.env.UMAMI_WEBSITE_ID, // Server-side
+  apiEndpoint:
+    typeof window === "undefined" ? process.env.UMAMI_API_ENDPOINT : "/stats",
+});
+
+export default function Layout({ children }) {
+  return (
+    <AnalyticsContextProvider service={analytics}>
+      <AnalyticsAutoTracker />
+      {children}
+    </AnalyticsContextProvider>
+  );
+}
+```
+
+### 3. Route Handlers
+
+Create a proxy for Umami:
+`app/stats/api/send/route.ts`
+
+```ts
+import { createUmamiProxyHandler } from "@mintel/observability";
+export const POST = await createUmamiProxyHandler({
+  websiteId: process.env.UMAMI_WEBSITE_ID,
+  apiEndpoint: process.env.UMAMI_API_ENDPOINT,
+});
+```
+
+Create a relay for Sentry:
+`app/errors/api/relay/route.ts`
+
+```ts
+import { createSentryRelayHandler } from "@mintel/observability";
+export const POST = await createSentryRelayHandler({
+  dsn: process.env.SENTRY_DSN,
+});
+```
+
+### 4. Notification Setup (Server-side)
+
+```ts
+import { GotifyNotificationService } from "@mintel/observability";
+
+const notifications = new GotifyNotificationService({
+  enabled: true,
+  url: process.env.GOTIFY_URL,
+  token: process.env.GOTIFY_TOKEN,
+});
+
+await notifications.notify({
+  title: "Lead Capture",
+  message: "New contact form submission",
+  priority: 5,
+});
+```
+
+### 5. Sentry Configuration
+
+Use `initSentry` in your `sentry.server.config.ts` and `sentry.client.config.ts`.
+
+On the client, use the tunnel:
+
+```ts
+initSentry({
+  dsn: "https://public@errors.infra.mintel.me/1", // Placeholder
+  tunnel: "/errors/api/relay",
+});
+```
+
+## Architecture
+
+This package implements the **Smart Proxy** pattern:
+
+- The client NEVER knows the real `UMAMI_WEBSITE_ID`.
+- Tracking events are sent to your own domain (`/stats/api/send`).
+- Your server injects the secret ID and forwards to Umami.
+- This bypasses ad-blockers and keeps your configuration secure.

packages/observability/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mintel/observability",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npm.infra.mintel.me"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "lint": "eslint src/",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@mintel/eslint-config": "workspace:*",
+    "@mintel/tsconfig": "workspace:*",
+    "eslint": "^9.39.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}

packages/observability/src/analytics/noop.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { NoopAnalyticsService } from "./noop";
+
+describe("NoopAnalyticsService", () => {
+  it("should not throw on track", () => {
+    const service = new NoopAnalyticsService();
+    expect(() => service.track("test")).not.toThrow();
+  });
+
+  it("should not throw on trackPageview", () => {
+    const service = new NoopAnalyticsService();
+    expect(() => service.trackPageview()).not.toThrow();
+  });
+});

packages/observability/src/analytics/noop.ts

@@ -0,0 +1,15 @@
+import type { AnalyticsService, AnalyticsEventProperties } from "./service";
+
+/**
+ * No-operation analytics service.
+ * Used when analytics are disabled or for local development.
+ */
+export class NoopAnalyticsService implements AnalyticsService {
+  track(eventName: string, props?: AnalyticsEventProperties): void {
+    // Do nothing
+  }
+
+  trackPageview(url?: string): void {
+    // Do nothing
+  }
+}

packages/observability/src/analytics/service.ts

@@ -0,0 +1,31 @@
+/**
+ * Type definition for analytics event properties.
+ */
+export type AnalyticsEventProperties = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
+/**
+ * Interface for analytics service implementations.
+ *
+ * This interface defines the contract for all analytics services,
+ * allowing for different implementations (Umami, Google Analytics, etc.)
+ * while maintaining a consistent API.
+ */
+export interface AnalyticsService {
+  /**
+   * Track a custom event with optional properties.
+   *
+   * @param eventName - The name of the event to track
+   * @param props - Optional event properties (metadata)
+   */
+  track(eventName: string, props?: AnalyticsEventProperties): void;
+
+  /**
+   * Track a pageview.
+   *
+   * @param url - The URL to track (defaults to current location)
+   */
+  trackPageview(url?: string): void;
+}

packages/observability/src/analytics/umami.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { UmamiAnalyticsService } from "./umami";
+
+describe("UmamiAnalyticsService", () => {
+  const mockConfig = {
+    websiteId: "test-website-id",
+    apiEndpoint: "https://analytics.test",
+    enabled: true,
+  };
+
+  const mockLogger = {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    trace: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    global.fetch = vi.fn();
+  });
+
+  it("should not send payload if disabled", async () => {
+    const service = new UmamiAnalyticsService({
+      ...mockConfig,
+      enabled: false,
+    });
+    service.track("test-event");
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("should send payload with correct data for track", async () => {
+    const service = new UmamiAnalyticsService(mockConfig, mockLogger);
+
+    (global.fetch as any).mockResolvedValue({ ok: true });
+
+    service.track("test-event", { foo: "bar" });
+
+    // Wait for async sendPayload
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://analytics.test/api/send",
+      expect.objectContaining({
+        method: "POST",
+        body: expect.stringContaining('"type":"event"'),
+      }),
+    );
+
+    const callBody = JSON.parse((global.fetch as any).mock.calls[0][1].body);
+    expect(callBody.payload.name).toBe("test-event");
+    expect(callBody.payload.data.foo).toBe("bar");
+    expect(callBody.payload.website).toBe("test-website-id");
+  });
+
+  it("should log warning if send fails", async () => {
+    const service = new UmamiAnalyticsService(mockConfig, mockLogger);
+
+    (global.fetch as any).mockResolvedValue({
+      ok: false,
+      status: 500,
+      text: () => Promise.resolve("Internal error"),
+    });
+
+    service.track("test-event");
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      "Umami API responded with error",
+      expect.objectContaining({ status: 500 }),
+    );
+  });
+});

packages/observability/src/analytics/umami.ts

@@ -0,0 +1,115 @@
+import type { AnalyticsService, AnalyticsEventProperties } from "./service";
+
+export interface UmamiConfig {
+  websiteId?: string;
+  apiEndpoint: string; // The endpoint to send to (proxied or direct)
+  enabled: boolean;
+}
+
+export interface Logger {
+  debug(msg: string, data?: any): void;
+  warn(msg: string, data?: any): void;
+  error(msg: string, data?: any): void;
+  trace(msg: string, data?: any): void;
+}
+
+/**
+ * Umami Analytics Service Implementation (Script-less/Proxy edition).
+ */
+export class UmamiAnalyticsService implements AnalyticsService {
+  private logger?: Logger;
+
+  constructor(
+    private config: UmamiConfig,
+    logger?: Logger,
+  ) {
+    this.logger = logger;
+  }
+
+  private async sendPayload(type: "event", data: Record<string, any>) {
+    if (!this.config.enabled) return;
+
+    const isClient = typeof window !== "undefined";
+    const websiteId = this.config.websiteId;
+
+    if (!isClient && !websiteId) {
+      this.logger?.warn(
+        "Umami tracking called on server but no Website ID configured",
+      );
+      return;
+    }
+
+    try {
+      const payload = {
+        website: websiteId,
+        hostname: isClient ? window.location.hostname : "server",
+        screen: isClient
+          ? `${window.screen.width}x${window.screen.height}`
+          : undefined,
+        language: isClient ? navigator.language : undefined,
+        referrer: isClient ? document.referrer : undefined,
+        ...data,
+      };
+
+      this.logger?.trace("Sending analytics payload", { type, url: data.url });
+
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 10000);
+
+      try {
+        const response = await fetch(`${this.config.apiEndpoint}/api/send`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "User-Agent": isClient ? navigator.userAgent : "Mintel-Server",
+          },
+          body: JSON.stringify({ type, payload }),
+          keepalive: true,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          this.logger?.warn("Umami API responded with error", {
+            status: response.status,
+            error: errorText.slice(0, 100),
+          });
+        }
+      } catch (fetchError) {
+        clearTimeout(timeoutId);
+        if ((fetchError as Error).name === "AbortError") {
+          this.logger?.error("Umami request timed out");
+        } else {
+          throw fetchError;
+        }
+      }
+    } catch (error) {
+      this.logger?.error("Failed to send analytics", {
+        error: (error as Error).message,
+      });
+    }
+  }
+
+  track(eventName: string, props?: AnalyticsEventProperties) {
+    this.sendPayload("event", {
+      name: eventName,
+      data: props,
+      url:
+        typeof window !== "undefined"
+          ? window.location.pathname + window.location.search
+          : undefined,
+    });
+  }
+
+  trackPageview(url?: string) {
+    this.sendPayload("event", {
+      url:
+        url ||
+        (typeof window !== "undefined"
+          ? window.location.pathname + window.location.search
+          : undefined),
+    });
+  }
+}

packages/observability/src/index.ts

@@ -0,0 +1,9 @@
+// Analytics
+export * from "./analytics/service";
+export * from "./analytics/umami";
+export * from "./analytics/noop";
+
+// Notifications
+export * from "./notifications/service";
+export * from "./notifications/gotify";
+export * from "./notifications/noop";

packages/observability/src/notifications/gotify.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { GotifyNotificationService } from "./gotify";
+
+describe("GotifyNotificationService", () => {
+  const mockConfig = {
+    url: "https://gotify.test",
+    token: "test-token",
+    enabled: true,
+  };
+
+  const mockLogger = {
+    error: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    global.fetch = vi.fn();
+  });
+
+  it("should not notify if disabled", async () => {
+    const service = new GotifyNotificationService({
+      ...mockConfig,
+      enabled: false,
+    });
+    await service.notify({ title: "test", message: "test" });
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("should send correct payload to Gotify", async () => {
+    const service = new GotifyNotificationService(mockConfig, mockLogger);
+    (global.fetch as any).mockResolvedValue({ ok: true });
+
+    await service.notify({
+      title: "Alert",
+      message: "Critical issue",
+      priority: 8,
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://gotify.test/message?token=test-token",
+      expect.objectContaining({
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          title: "Alert",
+          message: "Critical issue",
+          priority: 8,
+        }),
+      }),
+    );
+  });
+
+  it("should handle missing trailing slash in URL", async () => {
+    const service = new GotifyNotificationService({
+      ...mockConfig,
+      url: "https://gotify.test",
+    });
+    (global.fetch as any).mockResolvedValue({ ok: true });
+
+    await service.notify({ title: "test", message: "test" });
+
+    expect((global.fetch as any).mock.calls[0][0]).toBe(
+      "https://gotify.test/message?token=test-token",
+    );
+  });
+
+  it("should log error if notify fails", async () => {
+    const service = new GotifyNotificationService(mockConfig, mockLogger);
+    (global.fetch as any).mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: () => Promise.resolve("Unauthorized"),
+    });
+
+    await service.notify({ title: "test", message: "test" });
+
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      "Gotify notification failed",
+      expect.objectContaining({ status: 401 }),
+    );
+  });
+});

packages/observability/src/notifications/gotify.ts

@@ -0,0 +1,56 @@
+import { NotificationOptions, NotificationService } from "./service";
+
+export interface GotifyConfig {
+  url: string;
+  token: string;
+  enabled: boolean;
+}
+
+/**
+ * Gotify Notification Service implementation.
+ */
+export class GotifyNotificationService implements NotificationService {
+  constructor(
+    private config: GotifyConfig,
+    private logger?: { error(msg: string, data?: any): void },
+  ) {}
+
+  async notify(options: NotificationOptions): Promise<void> {
+    if (!this.config.enabled) return;
+
+    try {
+      const { title, message, priority = 4 } = options;
+
+      // Ensure we have a trailing slash for base URL, then append 'message'
+      const baseUrl = this.config.url.endsWith("/")
+        ? this.config.url
+        : `${this.config.url}/`;
+      const url = new URL("message", baseUrl);
+      url.searchParams.set("token", this.config.token);
+
+      const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          title,
+          message,
+          priority,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        this.logger?.error("Gotify notification failed", {
+          status: response.status,
+          error: errorText.slice(0, 100),
+        });
+      }
+    } catch (error) {
+      this.logger?.error("Gotify notification error", {
+        error: (error as Error).message,
+      });
+    }
+  }
+}

packages/observability/src/notifications/noop.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { NoopNotificationService } from "./noop";
+
+describe("NoopNotificationService", () => {
+  it("should not throw on notify", async () => {
+    const service = new NoopNotificationService();
+    await expect(
+      service.notify({ title: "test", message: "test" }),
+    ).resolves.not.toThrow();
+  });
+});

packages/observability/src/notifications/noop.ts

@@ -0,0 +1,10 @@
+import { NotificationService } from "./service";
+
+/**
+ * No-operation notification service.
+ */
+export class NoopNotificationService implements NotificationService {
+  async notify(): Promise<void> {
+    // Do nothing
+  }
+}

packages/observability/src/notifications/service.ts

@@ -0,0 +1,16 @@
+export interface NotificationOptions {
+  title: string;
+  message: string;
+  priority?: number;
+}
+
+/**
+ * Interface for notification service implementations.
+ * Allows for different implementations (Gotify, Slack, Email, etc.)
+ */
+export interface NotificationService {
+  /**
+   * Send a notification.
+   */
+  notify(options: NotificationOptions): Promise<void>;
+}

packages/observability/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig/base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "jsx": "react-jsx",
+    "esModuleInterop": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}