mmintel

0 Followers · 0 Following

• Joined on 2026-01-15

Repositories

6

Projects Packages Public Activity Starred Repositories

@mintel/observability (1.9.10)

Published 2026-03-03 11:47:30 +00:00 by mmintel in mmintel/at-mintel

Installation

Set up this registry in your project .npmrc file:

@mintel:registry=

To install the package using npm, run the following command:

npm install @mintel/observability@1.9.10

or add it to the package.json file:

"@mintel/observability": "1.9.10"

For more information on the npm registry, see the documentation.

About this package

@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

pnpm add @mintel/observability @sentry/nextjs

Usage

1. Unified Environment (via @mintel/next-utils)

Define the following environment variables:

# 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:

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

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

import { createSentryRelayHandler } from "@mintel/observability";
export const POST = await createSentryRelayHandler({
  dsn: process.env.SENTRY_DSN,
});

4. Notification Setup (Server-side)

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:

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.

Dependencies

Development Dependencies

ID	Version
@mintel/eslint-config	1.9.10
@mintel/tsconfig	1.9.10
eslint	^9.39.2
tsup	^8.0.0
typescript	^5.0.0
vitest	^2.0.0

Details

npm

mmintel/at-mintel

2026-03-03 11:47:30 +00:00

0

6.2 KiB

Assets (1)

observability-1.9.10.tgz 6.2 KiB

Versions (11) View all

1.9.11 2026-03-03

1.9.10 2026-03-03

1.9.8 2026-03-03

1.9.7 2026-03-02

1.9.5 2026-02-27

Issues