@ttt-productions/monitoring-core 0.0.1

package/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "@ttt-productions/monitoring-core",
+    "version": "0.0.1",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ttt-productions/ttt-packages.git",
+        "directory": "packages/monitoring-core"
+    },
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "sideEffects": false,
+    "dependencies": {},
+    "peerDependencies": {
+        "@sentry/nextjs": "^8.0.0"
+    }
+}

package/src/adapter.ts

@@ -0,0 +1,16 @@
+import type { MonitoringInitOptions, MonitoringUser, ScopeLike } from "./types";
+
+export interface MonitoringAdapter {
+  init(options: MonitoringInitOptions): void | Promise<void>;
+
+  captureException(error: unknown, context?: Record<string, unknown>): void;
+  captureMessage(
+    message: string,
+    level?: "fatal" | "error" | "warning" | "info" | "debug"
+  ): void;
+
+  setUser(user: MonitoringUser | null): void;
+  setTag(key: string, value: string): void;
+
+  withScope?<T>(fn: (scope: ScopeLike) => T): T;
+}

package/src/adapters/noop.ts

@@ -0,0 +1,21 @@
+import type { MonitoringAdapter } from "../adapter";
+import type { MonitoringInitOptions, MonitoringUser, ScopeLike } from "../types";
+
+const noopScope: ScopeLike = {
+  setTag: () => {},
+  setUser: () => {},
+  setExtra: () => {},
+  setContext: () => {},
+};
+
+export const NoopAdapter: MonitoringAdapter = {
+  init: (_options: MonitoringInitOptions) => {},
+
+  captureException: (_error: unknown, _context?: Record<string, unknown>) => {},
+  captureMessage: (_message: string, _level?: any) => {},
+
+  setUser: (_user: MonitoringUser | null) => {},
+  setTag: (_key: string, _value: string) => {},
+
+  withScope: <T>(fn: (scope: ScopeLike) => T) => fn(noopScope),
+};

package/src/adapters/sentry.ts

@@ -0,0 +1,96 @@
+import type { MonitoringAdapter } from "../adapter";
+import type { MonitoringInitOptions, MonitoringUser, ScopeLike } from "../types";
+
+type SentryLike = {
+  init: (opts: any) => void;
+  captureException: (e: unknown) => void;
+  captureMessage: (m: string, level?: any) => void;
+  setUser: (u: any) => void;
+  setTag: (k: string, v: string) => void;
+  withScope?: (fn: (scope: any) => void) => void;
+};
+
+let sentryPromise: Promise<SentryLike> | null = null;
+
+function getSentry(): Promise<SentryLike> {
+  if (!sentryPromise) {
+    // keep the import fully dynamic and untyped so TS doesn't require the module at build time
+    sentryPromise = (Function("return import('@sentry/nextjs')")() as Promise<any>).then(
+      (m) => m as SentryLike
+    );
+  }
+  return sentryPromise;
+}
+
+export const SentryAdapter: MonitoringAdapter = {
+  async init(options: MonitoringInitOptions) {
+    const enabled = options.enabled ?? true;
+    if (!enabled || !options.dsn) return;
+
+    const S = await getSentry();
+    S.init({
+      dsn: options.dsn,
+      environment: options.environment,
+      enabled: true,
+      release: options.release,
+    });
+  },
+
+  captureException(error: unknown, context?: Record<string, unknown>) {
+    void (async () => {
+      const S = await getSentry();
+
+      if (context && S.withScope) {
+        S.withScope((scope) => {
+          for (const [k, v] of Object.entries(context)) {
+            if (typeof scope?.setExtra === "function") scope.setExtra(k, v);
+          }
+          S.captureException(error);
+        });
+        return;
+      }
+
+      S.captureException(error);
+    })();
+  },
+
+  captureMessage(message: string, level?: any) {
+    void (async () => {
+      const S = await getSentry();
+      S.captureMessage(message, level);
+    })();
+  },
+
+  setUser(user: MonitoringUser | null) {
+    void (async () => {
+      const S = await getSentry();
+      S.setUser(user as any);
+    })();
+  },
+
+  setTag(key: string, value: string) {
+    void (async () => {
+      const S = await getSentry();
+      S.setTag(key, value);
+    })();
+  },
+
+  withScope<T>(fn: (scope: ScopeLike) => T): T {
+    // run immediately (sync) with a minimal scope.
+    // also try to run in real Sentry scope when available.
+    const minimalScope: ScopeLike = {
+      setTag: () => {},
+      setUser: () => {},
+      setExtra: () => {},
+      setContext: () => {},
+    };
+
+    void (async () => {
+      const S = await getSentry();
+      if (!S.withScope) return;
+      S.withScope((scope) => fn(scope as any));
+    })();
+
+    return fn(minimalScope);
+  },
+};

package/src/api.ts

@@ -0,0 +1,31 @@
+import type { MonitoringUser } from "./types";
+import { getMonitoringAdapter } from "./init";
+
+export function captureException(error: unknown, context?: Record<string, unknown>) {
+  return getMonitoringAdapter().captureException(error, context);
+}
+
+export function captureMessage(
+  message: string,
+  level?: "fatal" | "error" | "warning" | "info" | "debug"
+) {
+  return getMonitoringAdapter().captureMessage(message, level);
+}
+
+export function setUser(user: MonitoringUser | null) {
+  return getMonitoringAdapter().setUser(user);
+}
+
+export function setTag(key: string, value: string) {
+  return getMonitoringAdapter().setTag(key, value);
+}
+
+export function withScope(fn: (scope: any) => any) {
+  const a = getMonitoringAdapter();
+  return a.withScope ? a.withScope(fn as any) : fn({
+    setTag: () => {},
+    setUser: () => {},
+    setExtra: () => {},
+    setContext: () => {},
+  });
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export type { MonitoringInitOptions, MonitoringUser, MonitoringProvider, ScopeLike } from "./types";
+
+export { initMonitoring } from "./init";
+export { captureException, captureMessage, setUser, setTag, withScope } from "./api";

package/src/init.ts

@@ -0,0 +1,33 @@
+import type { MonitoringAdapter } from "./adapter";
+import type { MonitoringInitOptions } from "./types";
+import { NoopAdapter } from "./adapters/noop";
+import { SentryAdapter } from "./adapters/sentry";
+
+let adapter: MonitoringAdapter = NoopAdapter;
+let initialized = false;
+
+export function getMonitoringAdapter(): MonitoringAdapter {
+  return adapter;
+}
+
+export async function initMonitoring(options: MonitoringInitOptions): Promise<void> {
+  if (initialized) return;
+
+  const enabled = options.enabled ?? true;
+
+  if (!enabled || options.provider === "noop") {
+    adapter = NoopAdapter;
+    initialized = true;
+    return;
+  }
+
+  if (options.provider === "sentry") {
+    adapter = SentryAdapter;
+    await adapter.init(options);
+    initialized = true;
+    return;
+  }
+
+  adapter = NoopAdapter;
+  initialized = true;
+}

package/src/types.ts

@@ -0,0 +1,23 @@
+export type MonitoringProvider = "sentry" | "noop";
+
+export type MonitoringInitOptions = {
+  provider: MonitoringProvider;
+  dsn?: string;
+  environment?: string;
+  enabled?: boolean; // default true
+  release?: string;
+};
+
+export type MonitoringUser = {
+  id?: string;
+  email?: string;
+  username?: string;
+  ip_address?: string;
+};
+
+export type ScopeLike = {
+  setTag: (key: string, value: string) => void;
+  setUser: (user: MonitoringUser | null) => void;
+  setExtra: (key: string, value: unknown) => void;
+  setContext: (key: string, context: Record<string, unknown>) => void;
+};

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+      "outDir": "dist",
+      "rootDir": "src",
+      "declaration": true,
+      "declarationMap": true
+    },
+    "include": ["src"]
+  }
+