acinguiux-dnr-utils 0.0.1

package/src/instrumentation/browser.ts

@@ -0,0 +1,24 @@
+import { faro, getWebInstrumentations, initializeFaro } from "@grafana/faro-web-sdk";
+import type { Session } from "next-auth";
+
+export const instrument = (productName: string, user: Session["user"]) => {
+  if (faro.api) return null;
+  if (!process.env.NEXT_PUBLIC_FARO_URL) return null;
+
+  initializeFaro({
+    url: `${process.env.NEXT_PUBLIC_FARO_URL}/collect`,
+    app: {
+      name: `${productName}-browser`,
+      namespace: `geneva-${productName}`,
+    },
+    user: {
+      email: user?.email || "",
+      fullName: user?.name || "",
+    },
+    pageTracking: {
+      generatePageId: (url) => url.pathname,
+    },
+    trackGeolocation: true,
+    instrumentations: [...getWebInstrumentations()],
+  });
+};

package/src/instrumentation/node.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock only the heavy external dependencies that prevent module loading
+vi.mock("@opentelemetry/winston-transport", () => ({
+  OpenTelemetryTransportV3: vi.fn(),
+}));
+
+vi.mock("winston", () => ({
+  createLogger: vi.fn(() => ({
+    info: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+  })),
+}));
+
+describe("node instrumentation", () => {
+  const originalEnv = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+
+  beforeEach(() => {
+    delete process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  });
+
+  afterEach(() => {
+    if (originalEnv) {
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = originalEnv;
+    }
+  });
+
+  it("should export an instrument function", async () => {
+    const { instrument } = await import("./node");
+    expect(typeof instrument).toBe("function");
+  });
+
+  it("should export a logger", async () => {
+    const { logger } = await import("./node");
+    expect(logger).toBeDefined();
+    expect(typeof logger.info).toBe("function");
+    expect(typeof logger.error).toBe("function");
+  });
+
+  it("should return early when OTEL_EXPORTER_OTLP_ENDPOINT is not set", async () => {
+    delete process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+
+    const { instrument } = await import("./node");
+    const result = instrument("test-product");
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should accept product name parameter without throwing", async () => {
+    const { instrument } = await import("./node");
+    expect(() => instrument("service-name")).not.toThrow();
+  });
+
+  it("should initialize SDK when OTEL_EXPORTER_OTLP_ENDPOINT is set", async () => {
+    process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "https://otel.example.com";
+
+    const { instrument } = await import("./node");
+
+    // Should not throw when endpoint is configured
+    expect(() => instrument("test-service")).not.toThrow();
+  });
+});

package/src/instrumentation/node.ts

@@ -0,0 +1,81 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: supress noExplicitAny */
+
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
+import { WinstonInstrumentation } from "@opentelemetry/instrumentation-winston";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { api, logs, metrics, NodeSDK, node as traces } from "@opentelemetry/sdk-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { OpenTelemetryTransportV3 } from "@opentelemetry/winston-transport";
+import { createLogger } from "winston";
+
+export const logger = createLogger({
+  transports: [new OpenTelemetryTransportV3()],
+});
+
+class DisableExtractContextPropagator implements api.TextMapPropagator {
+  constructor(private readonly propagator: W3CTraceContextPropagator) {}
+  inject = (context: api.Context, carrier: any, setter = api.defaultTextMapSetter) =>
+    this.propagator.inject(context, carrier, setter);
+  extract = (context: api.Context, _carrier: any, _getter = api.defaultTextMapGetter) => context;
+  fields = () => this.propagator.fields();
+}
+
+export const instrument = (productName: string) => {
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return;
+
+  api.propagation.setGlobalPropagator(
+    new DisableExtractContextPropagator(new W3CTraceContextPropagator()),
+  );
+
+  const sdk = new NodeSDK({
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: `${productName}-ui`,
+    }),
+    metricReader: new metrics.PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/metrics`,
+      }),
+      exportIntervalMillis: 10000,
+    }),
+    spanProcessors: [
+      new traces.BatchSpanProcessor(
+        new OTLPTraceExporter({
+          url: `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
+        }),
+      ),
+    ],
+    logRecordProcessors: [
+      new logs.BatchLogRecordProcessor(
+        new OTLPLogExporter({
+          url: `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/logs`,
+        }),
+      ),
+    ],
+    instrumentations: [
+      new HttpInstrumentation({
+        ignoreIncomingRequestHook: (request) => {
+          const ignoreUrls = ["/_next/static", "/_next/image", "/favicon.ico", "/api/auth"];
+
+          return ignoreUrls.some((url) => request.url?.includes(url));
+        },
+      }),
+      new UndiciInstrumentation({
+        ignoreRequestHook: (request) => {
+          const ignoreUrls = ["/v1/traces"];
+
+          return ignoreUrls.some((url) => request.path?.includes(url));
+        },
+      }),
+      new WinstonInstrumentation({
+        disableLogSending: true,
+      }),
+    ],
+  });
+
+  sdk.start();
+};

package/src/loggers/auth-fetch.test.ts

@@ -0,0 +1,383 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as auth_module from "../authentication";
+import * as logger_module from "../instrumentation/node";
+import { authFetch } from "./auth-fetch";
+
+vi.mock("../authentication", () => ({
+  auth: vi.fn(() => ({
+    access_token: "test-token",
+    user: { name: "Test User", email: "test@example.com" },
+  })),
+}));
+
+vi.mock("../instrumentation/node", () => ({
+  logger: {
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+
+describe("authFetch", () => {
+  const domain = "https://api.test.com";
+  const path = "test/path";
+  const queryParams = "key=value";
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const makeJsonResponse = (
+    data: unknown,
+    {
+      ok = true,
+      status = 200,
+      statusText = "OK",
+      contentType = "application/json",
+    }: {
+      ok?: boolean;
+      status?: number;
+      statusText?: string;
+      contentType?: string;
+    } = {},
+  ) => {
+    const response: any = {
+      ok,
+      json: () => Promise.resolve(data),
+      headers: new Headers({ "content-type": contentType }),
+      status,
+      statusText,
+    };
+
+    if (!ok) {
+      response.clone = () => ({
+        json: () => Promise.resolve(data),
+        status,
+        statusText,
+      });
+    }
+
+    return response;
+  };
+
+  const makeTextResponse = (
+    text: string,
+    {
+      ok = true,
+      status = 200,
+      statusText = "OK",
+      contentType = "text/plain",
+    }: {
+      ok?: boolean;
+      status?: number;
+      statusText?: string;
+      contentType?: string;
+    } = {},
+  ) => {
+    const response: any = {
+      ok,
+      text: () => Promise.resolve(text),
+      headers: new Headers({ "content-type": contentType }),
+      status,
+      statusText,
+    };
+
+    if (!ok) {
+      response.clone = () => ({
+        text: () => Promise.resolve(text),
+        status,
+        statusText,
+      });
+    }
+
+    return response;
+  };
+
+  const mockFetchResolved = (response: any) => {
+    global.fetch = vi.fn().mockResolvedValue(response);
+  };
+
+  it("uses default requestOptions when no additional options are provided", async () => {
+    mockFetchResolved(makeJsonResponse({}));
+
+    await authFetch(`${domain}/${path}?${queryParams}`, {});
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      `${domain}/${path}?${queryParams}`,
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.any(Headers),
+      }),
+    );
+  });
+
+  it("merges additional options into requestOptions", async () => {
+    mockFetchResolved(makeJsonResponse({}));
+
+    const additionalOptions = {
+      method: "POST",
+      body: JSON.stringify({ data: "test" }),
+    };
+
+    await authFetch(`${domain}/${path}?${queryParams}`, additionalOptions);
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      `${domain}/${path}?${queryParams}`,
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.any(Headers),
+        body: '{"data":"test"}',
+      }),
+    );
+  });
+
+  it("includes the Authorization header with the token", async () => {
+    mockFetchResolved(makeJsonResponse({}));
+
+    await authFetch(`${domain}/${path}`, {});
+
+    const callArgs = (global.fetch as any).mock.calls[0];
+    const headers = callArgs[1].headers as Headers;
+
+    expect(headers.get("Authorization")).toBe("Bearer test-token");
+  });
+
+  it("logs success when response is ok with JSON content", async () => {
+    mockFetchResolved(makeJsonResponse({ data: "success" }));
+
+    await authFetch(`${domain}/${path}?${queryParams}`);
+
+    const logger = logger_module.logger;
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining("API request succeeded"),
+      expect.objectContaining({
+        path: `/${path}`,
+        status: 200,
+      }),
+    );
+  });
+
+  it("throws error when response is not ok with JSON error body", async () => {
+    mockFetchResolved(
+      makeJsonResponse(
+        {
+          context: {
+            errors: [{ msg: "Invalid request" }, { msg: "Missing field" }],
+          },
+        },
+        { ok: false, status: 400, statusText: "Bad Request" },
+      ),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow("Invalid request | Missing field");
+
+    const logger = logger_module.logger;
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("API request failed"),
+      expect.any(Object),
+    );
+  });
+
+  it("throws error when response is not ok with text error body", async () => {
+    mockFetchResolved(
+      makeTextResponse("Error message", {
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+      }),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow("Error message");
+  });
+
+  it("logs error with session data when request fails", async () => {
+    mockFetchResolved(makeJsonResponse({}, { ok: false, status: 401, statusText: "Unauthorized" }));
+
+    try {
+      await authFetch(`${domain}/${path}`);
+    } catch {
+      // Expected error
+    }
+
+    const logger = logger_module.logger;
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        status: 401,
+        user: expect.any(Object),
+      }),
+    );
+  });
+
+  it("logs error with anonymous user when session has no user", async () => {
+    vi.mocked(auth_module.auth).mockResolvedValue({} as any);
+
+    mockFetchResolved(makeJsonResponse({}, { ok: false, status: 401, statusText: "Unauthorized" }));
+
+    try {
+      await authFetch(`${domain}/${path}`);
+    } catch {
+      // Expected error
+    }
+
+    const logger = logger_module.logger;
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        user: expect.objectContaining({
+          name: "Anonymous",
+          email: "anonymous@shell.com",
+        }),
+      }),
+    );
+  });
+
+  it("returns response object on successful fetch", async () => {
+    const mockResponse = makeJsonResponse({ data: "test" });
+
+    mockFetchResolved(mockResponse);
+
+    const response = await authFetch(`${domain}/${path}`);
+
+    expect(response).toBe(mockResponse);
+  });
+
+  it("sets Content-Type header to application/json", async () => {
+    mockFetchResolved(makeJsonResponse({}));
+
+    await authFetch(`${domain}/${path}`, {});
+
+    const callArgs = (global.fetch as any).mock.calls[0];
+    const headers = callArgs[1].headers as Headers;
+
+    expect(headers.get("Content-Type")).toBe("application/json");
+  });
+
+  it("does not set Authorization header when session has no access_token", async () => {
+    vi.mocked(auth_module.auth).mockResolvedValueOnce({
+      user: { name: "Test User", email: "test@example.com" },
+    } as any);
+
+    mockFetchResolved(makeJsonResponse({}));
+
+    await authFetch(`${domain}/${path}`, {});
+
+    const callArgs = (global.fetch as any).mock.calls[0];
+    const headers = callArgs[1].headers as Headers;
+
+    expect(headers.get("Authorization")).toBeNull();
+  });
+
+  it("handles error response with no error context", async () => {
+    mockFetchResolved(
+      makeJsonResponse(
+        { someOtherField: "value" },
+        { ok: false, status: 400, statusText: "Bad Request" },
+      ),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow(
+      "Failed to read error response text.",
+    );
+  });
+
+  it("handles error response with empty error array", async () => {
+    mockFetchResolved(
+      makeJsonResponse(
+        { context: { errors: [] } },
+        { ok: false, status: 400, statusText: "Bad Request" },
+      ),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow(
+      "Failed to read error response text.",
+    );
+  });
+
+  it("handles error response with error messages from error array", async () => {
+    mockFetchResolved(
+      makeJsonResponse(
+        {
+          context: {
+            errors: [{ msg: "Error 1" }, { msg: "Error 2" }, { other: "field" }],
+          },
+        },
+        { ok: false, status: 400, statusText: "Bad Request" },
+      ),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow(" | Error 1 | Error 2");
+  });
+
+  it("handles error response with non-JSON content type", async () => {
+    mockFetchResolved(
+      makeTextResponse("Text error response", {
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+      }),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow("Text error response");
+  });
+
+  it("handles error response with empty text response", async () => {
+    mockFetchResolved(
+      makeTextResponse("", {
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+      }),
+    );
+
+    await expect(authFetch(`${domain}/${path}`)).rejects.toThrow(
+      "Failed to read error response text.",
+    );
+  });
+
+  it("returns response when throwOnError is false and response is not ok", async () => {
+    const mockResponse = makeJsonResponse(
+      {
+        context: {
+          errors: [{ msg: "Error message" }],
+        },
+      },
+      { ok: false, status: 400, statusText: "Bad Request" },
+    );
+
+    mockFetchResolved(mockResponse);
+
+    const response = await authFetch(`${domain}/${path}`, {}, false);
+
+    expect(response).toBe(mockResponse);
+    expect(response.ok).toBe(false);
+    // Verify the response body is still readable via clone
+    const clonedBody = await response.clone().json();
+    expect(clonedBody).toEqual({ context: { errors: [{ msg: "Error message" }] } });
+  });
+
+  it("logs error but does not throw when throwOnError is false", async () => {
+    const mockResponse = makeJsonResponse(
+      {
+        context: {
+          errors: [{ msg: "Test error" }],
+        },
+      },
+      { ok: false, status: 400, statusText: "Bad Request" },
+    );
+
+    mockFetchResolved(mockResponse);
+
+    const response = await authFetch(`${domain}/${path}`, {}, false);
+
+    expect(response.ok).toBe(false);
+
+    const logger = logger_module.logger;
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("API request failed"),
+      expect.any(Object),
+    );
+    // Verify the response body is still readable via clone
+    const clonedBody = await response.clone().json();
+    expect(clonedBody).toEqual({ context: { errors: [{ msg: "Test error" }] } });
+  });
+});

package/src/loggers/auth-fetch.ts

@@ -0,0 +1,79 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: Ignore any for the file */
+
+declare type RequestInit = any;
+
+import { auth } from "../authentication";
+import { logger } from "../instrumentation/node";
+
+export const authFetch = async (
+  url: string,
+  options: RequestInit = {},
+  throwOnError: boolean = true,
+) => {
+  const { pathname, searchParams } = new URL(url);
+  const humanReadablePath = pathname.replaceAll("/", " > ");
+  const session = await auth();
+
+  const headers = new Headers(options.headers);
+  headers.set("Content-Type", "application/json");
+  if (session?.access_token) {
+    headers.set("Authorization", `Bearer ${session.access_token}`);
+  }
+
+  const requestOptions: RequestInit = {
+    method: "GET",
+    ...options,
+    headers: headers,
+  };
+
+  const response = await fetch(url, requestOptions);
+  const isJson = response.headers.get("content-type")?.includes("application/json");
+
+  if (!response.ok) {
+    const responseClone = response.clone();
+    let errorText: string = "Failed to read error response text.";
+
+    if (isJson) {
+      const data = await responseClone.json();
+      const errors = data?.context?.errors;
+
+      if (Array.isArray(errors)) {
+        const messages = errors.reduce(
+          (acc: string, err: any) => (err.msg ? `${acc} | ${err.msg}` : acc),
+          "",
+        );
+        errorText = messages === "" ? errorText : messages;
+      }
+    } else {
+      const data = await responseClone.text();
+      errorText = data || errorText;
+    }
+
+    logger.error(`API request failed for (${humanReadablePath})`, {
+      path: pathname,
+      params: searchParams.toString(),
+      status: responseClone.status,
+      statusText: responseClone.statusText,
+      detail: errorText,
+      user: {
+        name: session?.user?.name || "Anonymous",
+        email: session?.user?.email || "anonymous@shell.com",
+      },
+    });
+
+    if (throwOnError) {
+      throw new Error(errorText);
+    } else {
+      return response;
+    }
+  }
+
+  logger.info(`API request succeeded for ${humanReadablePath}`, {
+    path: pathname,
+    params: searchParams.toString(),
+    status: response.status,
+    statusText: response.statusText,
+  });
+
+  return response;
+};

package/src/loggers/index.ts

@@ -0,0 +1 @@
+export { authFetch } from "./auth-fetch";

package/src/mappers/index.ts

@@ -0,0 +1 @@
+export * from "./name";

package/src/mappers/name.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { mapNameInitials } from "./name";
+
+describe("mapNameInitials", () => {
+  it("should return initials for a full name", () => {
+    const result = mapNameInitials("John Doe");
+    expect(result).toBe("JD");
+  });
+
+  it("should return initials for a single name", () => {
+    const result = mapNameInitials("Cher");
+    expect(result).toBe("C");
+  });
+
+  it("should return undefined for an empty string", () => {
+    const result = mapNameInitials("");
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined for null input", () => {
+    const result = mapNameInitials(null);
+    expect(result).toBeUndefined();
+  });
+
+  it("should handle names with extra spaces", () => {
+    const result = mapNameInitials("  Jane   Austen  ");
+    expect(result).toBe("JA");
+  });
+
+  it("should handle names with multiple spaces between words", () => {
+    const result = mapNameInitials("Mary     Shelley");
+    expect(result).toBe("MS");
+  });
+
+  it("should handle names with special characters", () => {
+    const result = mapNameInitials("O'Connor");
+    expect(result).toBe("O");
+  });
+
+  it("should return two characters for names with more than two words", () => {
+    const result = mapNameInitials("Mike J Smith");
+    expect(result).toBe("MS");
+  });
+});

package/src/mappers/name.ts

@@ -0,0 +1,16 @@
+export const mapNameInitials = (name?: string | null) => {
+  if (!name) {
+    return undefined;
+  }
+
+  const names = name.trim().split(" ");
+
+  const abbreviation = names
+    // take the first and last names
+    .filter((_name, i) => i === 0 || i === names.length - 1)
+    .map((name) => name.charAt(0))
+    .join("")
+    .toUpperCase();
+
+  return abbreviation.toUpperCase();
+};