@devopsplaybook.io/common-utils 1.10.1-beta.23.b1906d7 → 1.11.0-beta.24.d8f9aef

package/src/Notifications.spec.ts

@@ -1,265 +0,0 @@
-jest.mock("axios", () => ({
-  create: jest.fn(),
-}));
-
-import axios from "axios";
-import {
-  NotificationsClient,
-  NotificationsLogger,
-} from "./Notifications";
-
-const mockedCreate = axios.create as jest.MockedFunction<
-  typeof axios.create
->;
-
-/** Logger double that records every call. */
-function createMockLogger(): NotificationsLogger & {
-  info: jest.Mock;
-  warn: jest.Mock;
-  error: jest.Mock;
-} {
-  return {
-    info: jest.fn(),
-    warn: jest.fn(),
-    error: jest.fn(),
-  };
-}
-
-describe("NotificationsClient", () => {
-  let mockPost: jest.Mock;
-  let mockLogger: ReturnType<typeof createMockLogger>;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    mockPost = jest.fn();
-    mockedCreate.mockReturnValue({ post: mockPost } as never);
-    mockLogger = createMockLogger();
-  });
-
-  describe("constructor", () => {
-    it("should be enabled when apiEndpoint and apiToken are set", () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-
-      expect(client.isEnabled()).toBe(true);
-      expect(mockedCreate).toHaveBeenCalledTimes(1);
-    });
-
-    it("should be disabled when apiEndpoint is empty", () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-
-      expect(client.isEnabled()).toBe(false);
-      expect(mockedCreate).not.toHaveBeenCalled();
-    });
-
-    it("should be disabled when apiToken is empty", () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "",
-        logger: mockLogger,
-      });
-
-      expect(client.isEnabled()).toBe(false);
-      expect(mockedCreate).not.toHaveBeenCalled();
-    });
-
-    it("should log the enabled status exactly once at construction", () => {
-      new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-
-      expect(mockLogger.info).toHaveBeenCalledTimes(1);
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        "Notifications integration enabled",
-      );
-    });
-
-    it("should log the disabled status exactly once at construction", () => {
-      new NotificationsClient({
-        apiEndpoint: "",
-        apiToken: "",
-        logger: mockLogger,
-      });
-
-      expect(mockLogger.info).toHaveBeenCalledTimes(1);
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        "Notifications integration disabled (apiEndpoint or apiToken not set)",
-      );
-    });
-
-    it("should fall back to console logging when no logger is provided", () => {
-      const logSpy = jest.spyOn(console, "log").mockImplementation(jest.fn());
-
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-      });
-
-      expect(client.isEnabled()).toBe(true);
-      expect(logSpy).toHaveBeenCalledWith(
-        "Notifications integration enabled",
-      );
-
-      logSpy.mockRestore();
-    });
-  });
-
-  describe("send", () => {
-    it("should return null silently when disabled", async () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "",
-        apiToken: "",
-        logger: mockLogger,
-      });
-      jest.clearAllMocks(); // drop the startup log
-
-      const result = await client.send({ title: "Test" });
-
-      expect(result).toBeNull();
-      expect(mockPost).not.toHaveBeenCalled();
-      expect(mockLogger.info).not.toHaveBeenCalled();
-      expect(mockLogger.warn).not.toHaveBeenCalled();
-      expect(mockLogger.error).not.toHaveBeenCalled();
-    });
-
-    it("should post with default values when payload fields are omitted", async () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-      const response = {
-        id: "id-1",
-        title: "Test",
-        body: "",
-        source: "api",
-        severity: "info",
-        data: "{}",
-        createdAt: "2026-08-26T00:00:00.000Z",
-      };
-      mockPost.mockResolvedValue({ data: response });
-
-      const result = await client.send({ title: "Test" });
-
-      expect(mockPost).toHaveBeenCalledWith("/", {
-        title: "Test",
-        body: "",
-        source: "api",
-        severity: "info",
-        data: "{}",
-      });
-      expect(result).toEqual(response);
-    });
-
-    it("should pass through explicit payload values", async () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-      mockPost.mockResolvedValue({ data: {} });
-
-      await client.send({
-        title: "Alert",
-        body: "Something happened",
-        source: "my-app",
-        severity: "error",
-        data: '{"key":"value"}',
-      });
-
-      expect(mockPost).toHaveBeenCalledWith("/", {
-        title: "Alert",
-        body: "Something happened",
-        source: "my-app",
-        severity: "error",
-        data: '{"key":"value"}',
-      });
-    });
-
-    it("should return null and log an error when the request fails", async () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-      const failure = new Error("network down");
-      mockPost.mockRejectedValue(failure);
-
-      const result = await client.send({ title: "Test" });
-
-      expect(result).toBeNull();
-      expect(mockLogger.error).toHaveBeenCalledWith(
-        "NotificationsClient: failed to send notification",
-        failure,
-      );
-    });
-
-    it("should not reject when the request fails", async () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "http://localhost/api/notifications",
-        apiToken: "token",
-        logger: mockLogger,
-      });
-      mockPost.mockRejectedValue(new Error("network down"));
-
-      await expect(client.send({ title: "Test" })).resolves.toBeNull();
-    });
-  });
-
-  describe("severity helpers", () => {
-    it.each([
-      ["info", "info"],
-      ["success", "success"],
-      ["warning", "warning"],
-      ["error", "error"],
-    ] as const)(
-      "should send a %s notification",
-      async (method, severity) => {
-        const client = new NotificationsClient({
-          apiEndpoint: "http://localhost/api/notifications",
-          apiToken: "token",
-          logger: mockLogger,
-        });
-        mockPost.mockResolvedValue({ data: {} });
-
-        await client[method]("Title", "Body", "my-app");
-
-        expect(mockPost).toHaveBeenCalledWith(
-          "/",
-          expect.objectContaining({
-            title: "Title",
-            body: "Body",
-            source: "my-app",
-            severity,
-          }),
-        );
-      },
-    );
-
-    it("should return null silently from helpers when disabled", async () => {
-      const client = new NotificationsClient({
-        apiEndpoint: "",
-        apiToken: "",
-        logger: mockLogger,
-      });
-      jest.clearAllMocks(); // drop the startup log
-
-      expect(await client.info("Title")).toBeNull();
-      expect(await client.success("Title")).toBeNull();
-      expect(await client.warning("Title")).toBeNull();
-      expect(await client.error("Title")).toBeNull();
-      expect(mockPost).not.toHaveBeenCalled();
-      expect(mockLogger.info).not.toHaveBeenCalled();
-      expect(mockLogger.error).not.toHaveBeenCalled();
-    });
-  });
-});

package/src/Notifications.ts

@@ -1,201 +0,0 @@
-import axios, { AxiosInstance } from "axios";
-
-/**
- * Severity levels for notifications.
- */
-export type NotificationSeverity = "info" | "warning" | "error" | "success";
-
-/**
- * Minimal logger interface expected by the notifications client.
- * Matches the subset of the OTel logger used by devopsplaybook.io projects.
- */
-export interface NotificationsLogger {
-  info(message: string): void;
-  warn(message: string): void;
-  error(message: string, err?: unknown): void;
-}
-
-/**
- * Configuration for {@link NotificationsClient}.
- */
-export interface NotificationsConfig {
-  /** API endpoint URL (e.g., "https://notifications.example.com/api/notifications") */
-  apiEndpoint: string;
-  /** API token used for Bearer authentication */
-  apiToken: string;
-  /** Optional logger; falls back to console when omitted */
-  logger?: NotificationsLogger;
-}
-
-/**
- * Payload for creating a notification.
- */
-export interface NotificationPayload {
-  /** Notification title */
-  title: string;
-  /** Notification body/content */
-  body?: string;
-  /** Source identifier (defaults to "api") */
-  source?: string;
-  /** Severity level (defaults to "info") */
-  severity?: NotificationSeverity;
-  /** Additional data as a JSON string */
-  data?: string;
-}
-
-/**
- * Response from the notifications API.
- */
-export interface NotificationResponse {
-  id: string;
-  title: string;
-  body: string;
-  source: string;
-  severity: string;
-  data: string;
-  createdAt: string;
-}
-
-/** Console fallback used when no logger is injected. */
-const consoleLogger: NotificationsLogger = {
-  info: (message: string) => console.log(message),
-  warn: (message: string) => console.warn(message),
-  error: (message: string, err?: unknown) => console.error(message, err),
-};
-
-/**
- * Client for sending notifications to the central notifications service.
- *
- * The client is fail-safe by design:
- *
- * - It is disabled (and never throws) when `apiEndpoint` or `apiToken` is
- *   missing, so a partially configured parent application still starts.
- * - The integration status is logged exactly once, at construction time.
- * - Follow-up `send` calls on a disabled client are silent and resolve to
- *   `null`.
- * - Sending errors are logged and resolve to `null` instead of rejecting.
- *
- * @example
- * ```ts
- * const client = new NotificationsClient({
- *   apiEndpoint: config.NOTIFICATIONS_API,
- *   apiToken: config.NOTIFICATIONS_TOKEN,
- *   logger: OTelLogger().createModuleLogger("notifications"),
- * });
- *
- * await client.send({
- *   title: "Deployment finished",
- *   body: "Version 1.2.3 deployed to production",
- *   source: "my-app",
- *   severity: "success",
- * });
- * ```
- */
-export class NotificationsClient {
-  private client: AxiosInstance | null = null;
-  private readonly enabled: boolean;
-  private readonly logger: NotificationsLogger;
-
-  constructor(config: NotificationsConfig) {
-    this.enabled = !!(config.apiEndpoint && config.apiToken);
-    this.logger = config.logger || consoleLogger;
-
-    if (this.enabled) {
-      this.client = axios.create({
-        baseURL: config.apiEndpoint,
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.apiToken}`,
-        },
-        timeout: 10000,
-      });
-      this.logger.info("Notifications integration enabled");
-    } else {
-      this.logger.info(
-        "Notifications integration disabled (apiEndpoint or apiToken not set)",
-      );
-    }
-  }
-
-  /**
-   * Check whether the client is properly configured.
-   */
-  public isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  /**
-   * Send a notification.
-   *
-   * @param payload  The notification payload.
-   * @returns The created notification, or `null` when disabled or on failure.
-   */
-  public async send(
-    payload: NotificationPayload,
-  ): Promise<NotificationResponse | null> {
-    if (!this.enabled || !this.client) {
-      return null;
-    }
-
-    try {
-      const response = await this.client.post<NotificationResponse>("/", {
-        title: payload.title,
-        body: payload.body || "",
-        source: payload.source || "api",
-        severity: payload.severity || "info",
-        data: payload.data || "{}",
-      });
-      return response.data;
-    } catch (err) {
-      this.logger.error(
-        "NotificationsClient: failed to send notification",
-        err,
-      );
-      return null;
-    }
-  }
-
-  /**
-   * Send an info notification.
-   */
-  public async info(
-    title: string,
-    body?: string,
-    source?: string,
-  ): Promise<NotificationResponse | null> {
-    return this.send({ title, body, source, severity: "info" });
-  }
-
-  /**
-   * Send a success notification.
-   */
-  public async success(
-    title: string,
-    body?: string,
-    source?: string,
-  ): Promise<NotificationResponse | null> {
-    return this.send({ title, body, source, severity: "success" });
-  }
-
-  /**
-   * Send a warning notification.
-   */
-  public async warning(
-    title: string,
-    body?: string,
-    source?: string,
-  ): Promise<NotificationResponse | null> {
-    return this.send({ title, body, source, severity: "warning" });
-  }
-
-  /**
-   * Send an error notification.
-   */
-  public async error(
-    title: string,
-    body?: string,
-    source?: string,
-  ): Promise<NotificationResponse | null> {
-    return this.send({ title, body, source, severity: "error" });
-  }
-}

package/src/OTelContext.spec.ts

@@ -1,58 +0,0 @@
-import { createOTelContext } from "./OTelContext";
-
-describe("createOTelContext", () => {
-  it("should return an object with all expected methods", () => {
-    const ctx = createOTelContext();
-    expect(typeof ctx.OTelTracer).toBe("function");
-    expect(typeof ctx.OTelSetTracer).toBe("function");
-    expect(typeof ctx.OTelMeter).toBe("function");
-    expect(typeof ctx.OTelSetMeter).toBe("function");
-    expect(typeof ctx.OTelLogger).toBe("function");
-    expect(typeof ctx.OTelRequestSpan).toBe("function");
-  });
-
-  it("should create a StandardLogger lazily", () => {
-    const ctx = createOTelContext();
-    const logger = ctx.OTelLogger();
-    expect(logger).toBeDefined();
-    // Same instance on second call
-    expect(ctx.OTelLogger()).toBe(logger);
-  });
-
-  it("should store and retrieve tracer via setter/getter", () => {
-    const ctx = createOTelContext();
-    const fakeTracer = { id: "tracer-1" } as never;
-    ctx.OTelSetTracer(fakeTracer);
-    expect(ctx.OTelTracer()).toBe(fakeTracer);
-  });
-
-  it("should store and retrieve meter via setter/getter", () => {
-    const ctx = createOTelContext();
-    const fakeMeter = { id: "meter-1" } as never;
-    ctx.OTelSetMeter(fakeMeter);
-    expect(ctx.OTelMeter()).toBe(fakeMeter);
-  });
-
-  it("should isolate contexts from each other", () => {
-    const ctx1 = createOTelContext();
-    const ctx2 = createOTelContext();
-    const fakeTracer1 = { id: "tracer-1" } as never;
-    const fakeTracer2 = { id: "tracer-2" } as never;
-    ctx1.OTelSetTracer(fakeTracer1);
-    ctx2.OTelSetTracer(fakeTracer2);
-    expect(ctx1.OTelTracer()).toBe(fakeTracer1);
-    expect(ctx2.OTelTracer()).toBe(fakeTracer2);
-  });
-
-  it("OTelRequestSpan should return undefined for object without tracerSpanApi", () => {
-    const ctx = createOTelContext();
-    expect(ctx.OTelRequestSpan({})).toBeUndefined();
-  });
-
-  it("OTelRequestSpan should return the span when present", () => {
-    const ctx = createOTelContext();
-    const fakeSpan = { spanId: "123" } as never;
-    const req = { tracerSpanApi: fakeSpan };
-    expect(ctx.OTelRequestSpan(req)).toBe(fakeSpan);
-  });
-});

package/src/OTelContext.ts

@@ -1,63 +0,0 @@
-import {
-  StandardLogger,
-  StandardMeter,
-  StandardTracer,
-} from "@devopsplaybook.io/otel-utils";
-import { Span } from "@opentelemetry/sdk-trace-base";
-
-/**
- * Result of {@link createOTelContext}.
- * Holds module-level singletons for the OpenTelemetry tracer, meter and logger
- * used throughout a server process.
- */
-export interface OTelContext {
-  OTelTracer: () => StandardTracer;
-  OTelSetTracer: (tracer: StandardTracer) => void;
-  OTelMeter: () => StandardMeter;
-  OTelSetMeter: (meter: StandardMeter) => void;
-  OTelLogger: () => StandardLogger;
-  /**
-   * Retrieves the span previously attached to a request object.
-   * Equivalent to `req.tracerSpanApi`.
-   */
-  OTelRequestSpan: (req: any) => Span | undefined;
-}
-
-/**
- * Creates an isolated OTel context (tracer / meter / logger singletons).
- *
- * Each server process should call this once at startup and pass the returned
- * object to modules that need telemetry access.  This avoids polluting the
- * global module scope and makes unit-testing straightforward.
- *
- * @example
- * ```ts
- * const otel = createOTelContext();
- * otel.OTelSetTracer(new StandardTracer(config));
- * otel.OTelSetMeter(new StandardMeter(config));
- * otel.OTelLogger().initOTel(config);
- * ```
- */
-export function createOTelContext(): OTelContext {
-  let tracer: StandardTracer;
-  let meter: StandardMeter;
-  let logger: StandardLogger;
-
-  return {
-    OTelTracer: () => tracer,
-    OTelSetTracer: (t: StandardTracer) => {
-      tracer = t;
-    },
-    OTelMeter: () => meter,
-    OTelSetMeter: (m: StandardMeter) => {
-      meter = m;
-    },
-    OTelLogger: () => {
-      if (!logger) {
-        logger = new StandardLogger();
-      }
-      return logger;
-    },
-    OTelRequestSpan: (req: any) => req?.tracerSpanApi as Span | undefined,
-  };
-}