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

package/src/DbUtilsNoTelemetry.ts

@@ -1,117 +0,0 @@
-import { StandardLogger, ModuleLogger } from "@devopsplaybook.io/otel-utils";
-import {
-  DbUtilsGetDatabase,
-  DbUtilsGetType,
-  convertToPostgresPlaceholders,
-} from "./DbUtils";
-
-let logger: ModuleLogger;
-
-/**
- * Injects the OTel logger instance used by no-telemetry DB operations.
- * Must be called once at startup.
- */
-export function DbUtilsNoTelemetrySetLogger(loggerIn: StandardLogger): void {
-  logger = loggerIn.createModuleLogger("DbUtilsNoTelemetry");
-}
-
-/**
- * Execute a multi-row INSERT with a flat parameter array.
- * Builds: INSERT INTO <tableCols> VALUES (?,?...),(?,?...),...
- *
- * @returns Number of rows inserted.
- */
-export function DbUtilsNoTelemetryBatchInsert(
-  tableCols: string,
-  numCols: number,
-  rows: any[][],
-): number | Promise<number> {
-  if (rows.length === 0) return 0;
-  const rowSQL = `(${Array.from({ length: numCols }, () => "?").join(",")})`;
-  const multiValues = Array.from({ length: rows.length }, () => rowSQL).join(
-    ",",
-  );
-  const sql = `INSERT ${tableCols} VALUES ${multiValues}`;
-  return DbUtilsNoTelemetryExecSQL(sql, rows.flat());
-}
-
-/**
- * Execute a write SQL statement **without** creating an OTel span.
- * Use this on high-throughput paths where span overhead matters.
- *
- * @returns Number of rows changed.
- */
-export function DbUtilsNoTelemetryExecSQL(
-  sql: string,
-  params: unknown[] = [],
-): number | Promise<number> {
-  const dbType = DbUtilsGetType();
-  if (dbType === "postgres") {
-    const pgSql = convertToPostgresPlaceholders(sql);
-    return new Promise((resolve, reject) => {
-      (DbUtilsGetDatabase() as any).query(
-        pgSql,
-        params,
-        (error: Error | null, result: { rowCount: number | null }) => {
-          if (error) {
-            logger.error(`SQL INSERT ERROR: ${sql.substring(0, 200)}`, error);
-            reject(error);
-          } else {
-            resolve(result.rowCount || 0);
-          }
-        },
-      );
-    });
-  }
-  // SQLite (better-sqlite3) – synchronous
-  const stmt = (
-    DbUtilsGetDatabase() as {
-      prepare: (sql: string) => {
-        run: (params: unknown[]) => { changes: number };
-      };
-    }
-  ).prepare(sql);
-  const result = stmt.run(params);
-  return result.changes;
-}
-
-/**
- * Execute a read SQL query **without** creating an OTel span.
- * Use this on high-throughput paths where span overhead matters.
- *
- * @returns Array of row objects.
- */
-export function DbUtilsNoTelemetryQuerySQL(
-  sql: string,
-  params: unknown[] = [],
-  debug = false,
-): any[] | Promise<any[]> {
-  if (debug) {
-    console.log(sql);
-  }
-  const dbType = DbUtilsGetType();
-  if (dbType === "postgres") {
-    const pgSql = convertToPostgresPlaceholders(sql);
-    return new Promise((resolve, reject) => {
-      (DbUtilsGetDatabase() as any).query(
-        pgSql,
-        params,
-        (error: Error | null, result: { rows: unknown[] }) => {
-          if (error) {
-            logger.error(`SQL ERROR: ${sql}`, error);
-            reject(error);
-          } else {
-            resolve(result.rows);
-          }
-        },
-      );
-    });
-  }
-  // SQLite (better-sqlite3) – synchronous
-  const stmt = (
-    DbUtilsGetDatabase() as {
-      prepare: (sql: string) => { all: (params: unknown[]) => unknown[] };
-    }
-  ).prepare(sql);
-  return stmt.all(params);
-}

package/src/LLM.spec.ts

@@ -1,303 +0,0 @@
-jest.mock("axios", () => ({
-  create: jest.fn(),
-  isAxiosError: (err: unknown) =>
-    typeof err === "object" &&
-    err !== null &&
-    (err as { isAxiosError?: boolean }).isAxiosError === true,
-}));
-
-import axios from "axios";
-import { LLMClient, LLMLogger } from "./LLM";
-
-const mockedCreate = axios.create as jest.MockedFunction<typeof axios.create>;
-
-/** Logger double that records every call. */
-function createMockLogger(): LLMLogger & {
-  info: jest.Mock;
-  error: jest.Mock;
-} {
-  return {
-    info: jest.fn(),
-    error: jest.fn(),
-  };
-}
-
-describe("LLMClient", () => {
-  let mockPost: jest.Mock;
-  let mockLogger: ReturnType<typeof createMockLogger>;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    mockPost = jest.fn();
-    mockedCreate.mockReturnValue({ post: mockPost } as never);
-    mockLogger = createMockLogger();
-  });
-
-  function createEnabledClient(): LLMClient {
-    return new LLMClient({
-      apiKey: "key",
-      apiUrl: "https://api.example.com/chat/completions",
-      model: "test-model",
-      logger: mockLogger,
-    });
-  }
-
-  describe("constructor", () => {
-    it("should be enabled when apiKey, apiUrl and model are set", () => {
-      const client = createEnabledClient();
-
-      expect(client.isEnabled()).toBe(true);
-      expect(mockedCreate).toHaveBeenCalledTimes(1);
-    });
-
-    it("should create the HTTP client with auth header and timeout", () => {
-      new LLMClient({
-        apiKey: "key",
-        apiUrl: "https://api.example.com/chat/completions",
-        model: "test-model",
-        timeoutMs: 42000,
-        logger: mockLogger,
-      });
-
-      expect(mockedCreate).toHaveBeenCalledWith({
-        baseURL: "https://api.example.com/chat/completions",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: "Bearer key",
-        },
-        timeout: 42000,
-      });
-    });
-
-    it("should default the timeout to 120000 ms", () => {
-      createEnabledClient();
-
-      expect(mockedCreate).toHaveBeenCalledWith(
-        expect.objectContaining({ timeout: 120000 }),
-      );
-    });
-
-    it.each([
-      ["apiKey", { apiKey: "" }],
-      ["apiUrl", { apiUrl: "" }],
-      ["model", { model: "" }],
-    ])("should be disabled when %s is empty", (_name, override) => {
-      const client = new LLMClient({
-        apiKey: "key",
-        apiUrl: "https://api.example.com/chat/completions",
-        model: "test-model",
-        logger: mockLogger,
-        ...override,
-      });
-
-      expect(client.isEnabled()).toBe(false);
-      expect(mockedCreate).not.toHaveBeenCalled();
-    });
-
-    it("should log the integration status exactly once at construction", () => {
-      createEnabledClient();
-
-      expect(mockLogger.info).toHaveBeenCalledTimes(1);
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        "LLM integration enabled (model: test-model)",
-      );
-    });
-
-    it("should log the disabled status when misconfigured", () => {
-      new LLMClient({
-        apiKey: "",
-        apiUrl: "",
-        model: "",
-        logger: mockLogger,
-      });
-
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        "LLM integration disabled (apiKey, apiUrl or model not set)",
-      );
-    });
-  });
-
-  describe("request", () => {
-    it("should throw when the client is disabled", async () => {
-      const client = new LLMClient({
-        apiKey: "",
-        apiUrl: "",
-        model: "",
-        logger: mockLogger,
-      });
-
-      await expect(
-        client.request([{ role: "user", content: "hello" }]),
-      ).rejects.toThrow("LLM integration disabled");
-      expect(mockPost).not.toHaveBeenCalled();
-    });
-
-    it("should send model and messages without response_format by default", async () => {
-      mockPost.mockResolvedValue({
-        data: {
-          choices: [{ message: { content: "hi there" } }],
-          usage: { total_tokens: 12 },
-        },
-      });
-      const client = createEnabledClient();
-
-      const response = await client.request([
-        { role: "system", content: "be brief" },
-        { role: "user", content: "hello" },
-      ]);
-
-      expect(mockPost).toHaveBeenCalledWith("", {
-        model: "test-model",
-        messages: [
-          { role: "system", content: "be brief" },
-          { role: "user", content: "hello" },
-        ],
-        stream: false,
-      });
-      expect(response).toEqual({ content: "hi there", totalTokens: 12 });
-    });
-
-    it("should add response_format json_object in jsonMode", async () => {
-      mockPost.mockResolvedValue({
-        data: {
-          choices: [{ message: { content: "{}" } }],
-          usage: { total_tokens: 1 },
-        },
-      });
-      const client = createEnabledClient();
-
-      await client.request([{ role: "user", content: "hello" }], {
-        jsonMode: true,
-      });
-
-      expect(mockPost).toHaveBeenCalledWith(
-        "",
-        expect.objectContaining({
-          response_format: { type: "json_object" },
-        }),
-      );
-    });
-
-    it("should override the model per request", async () => {
-      mockPost.mockResolvedValue({
-        data: {
-          choices: [{ message: { content: "ok" } }],
-          usage: { total_tokens: 1 },
-        },
-      });
-      const client = createEnabledClient();
-
-      await client.request([{ role: "user", content: "hello" }], {
-        model: "other-model",
-      });
-
-      expect(mockPost).toHaveBeenCalledWith(
-        "",
-        expect.objectContaining({ model: "other-model" }),
-      );
-    });
-
-    it("should override the timeout per request", async () => {
-      mockPost.mockResolvedValue({
-        data: {
-          choices: [{ message: { content: "ok" } }],
-          usage: { total_tokens: 1 },
-        },
-      });
-      const client = createEnabledClient();
-
-      await client.request([{ role: "user", content: "hello" }], {
-        timeoutMs: 600000,
-      });
-
-      expect(mockPost).toHaveBeenCalledWith(
-        "",
-        expect.anything(),
-        expect.objectContaining({ timeout: 600000 }),
-      );
-    });
-
-    it("should disable the timeout when timeoutMs is 0", async () => {
-      mockPost.mockResolvedValue({
-        data: {
-          choices: [{ message: { content: "ok" } }],
-          usage: { total_tokens: 1 },
-        },
-      });
-      const client = createEnabledClient();
-
-      await client.request([{ role: "user", content: "hello" }], {
-        timeoutMs: 0,
-      });
-
-      expect(mockPost).toHaveBeenCalledWith(
-        "",
-        expect.anything(),
-        expect.objectContaining({ timeout: 0 }),
-      );
-    });
-
-    it("should not pass a request config when no timeout override is given", async () => {
-      mockPost.mockResolvedValue({
-        data: {
-          choices: [{ message: { content: "ok" } }],
-          usage: { total_tokens: 1 },
-        },
-      });
-      const client = createEnabledClient();
-
-      await client.request([{ role: "user", content: "hello" }]);
-
-      expect(mockPost).toHaveBeenCalledTimes(1);
-      expect(mockPost.mock.calls[0]).toHaveLength(2);
-    });
-
-    it("should default totalTokens to 0 and content to empty string", async () => {
-      mockPost.mockResolvedValue({
-        data: { choices: [{ message: { content: null } }] },
-      });
-      const client = createEnabledClient();
-
-      const response = await client.request([
-        { role: "user", content: "hello" },
-      ]);
-
-      expect(response).toEqual({ content: "", totalTokens: 0 });
-    });
-
-    it("should throw when the response has no choices", async () => {
-      mockPost.mockResolvedValue({ data: {} });
-      const client = createEnabledClient();
-
-      await expect(
-        client.request([{ role: "user", content: "hello" }]),
-      ).rejects.toThrow("LLM response has no choices");
-    });
-
-    it("should surface the provider error message", async () => {
-      const axiosError = Object.assign(new Error("Request failed 401"), {
-        isAxiosError: true,
-        response: { data: { error: { message: "Invalid API key" } } },
-      });
-      mockPost.mockRejectedValue(axiosError);
-      const client = createEnabledClient();
-
-      await expect(
-        client.request([{ role: "user", content: "hello" }]),
-      ).rejects.toThrow("Invalid API key");
-      expect(mockLogger.error).toHaveBeenCalledWith(
-        "LLMClient: request failed (Invalid API key)",
-        axiosError,
-      );
-    });
-
-    it("should keep the original message for non-provider errors", async () => {
-      mockPost.mockRejectedValue(new Error("Network down"));
-      const client = createEnabledClient();
-
-      await expect(
-        client.request([{ role: "user", content: "hello" }]),
-      ).rejects.toThrow("Network down");
-    });
-  });
-});

package/src/LLM.ts

@@ -1,204 +0,0 @@
-import axios, { AxiosInstance } from "axios";
-
-/**
- * A single chat message in OpenAI-compatible format.
- */
-export interface LLMMessage {
-  /** Message role, e.g. "system", "user", "assistant" */
-  role: string;
-  /** Message content */
-  content: string;
-}
-
-/**
- * Minimal logger interface expected by the LLM client.
- * Matches the subset of the OTel logger used by devopsplaybook.io projects.
- */
-export interface LLMLogger {
-  info(message: string): void;
-  error(message: string, err?: unknown): void;
-}
-
-/**
- * Configuration for {@link LLMClient}.
- */
-export interface LLMClientConfig {
-  /** API key used for Bearer authentication */
-  apiKey: string;
-  /** Chat completions endpoint URL (e.g., "https://api.deepseek.com/chat/completions") */
-  apiUrl: string;
-  /** Model name to use (e.g., "deepseek-chat") */
-  model: string;
-  /** Request timeout in milliseconds (defaults to 120000) */
-  timeoutMs?: number;
-  /** Optional logger; falls back to console when omitted */
-  logger?: LLMLogger;
-}
-
-/**
- * Per-request options for {@link LLMClient.request}.
- */
-export interface LLMRequestOptions {
-  /** Request JSON output (`response_format: json_object`). Defaults to false. */
-  jsonMode?: boolean;
-  /** Override the configured model for this call */
-  model?: string;
-  /**
-   * Override the configured timeout for this call, in milliseconds.
-   * Set `0` to disable the timeout entirely, for slow models or very large
-   * completions that legitimately exceed the client-level timeout.
-   * When omitted, the client-level `timeoutMs` applies.
-   */
-  timeoutMs?: number;
-}
-
-/**
- * Normalized response from a chat completion call.
- */
-export interface LLMResponse {
-  /** Content of the first choice (empty string when the model returned none) */
-  content: string;
-  /** Total tokens used, as reported by the provider (0 when unavailable) */
-  totalTokens: number;
-}
-
-/** Console fallback used when no logger is injected. */
-const consoleLogger: LLMLogger = {
-  info: (message: string) => console.log(message),
-  error: (message: string, err?: unknown) => console.error(message, err),
-};
-
-/**
- * Client for OpenAI-compatible chat completions APIs (DeepSeek, Moonshot,
- * Ollama, etc.).
- *
- * The client follows the same fail-safe pattern as {@link NotificationsClient}:
- *
- * - It is disabled when `apiKey`, `apiUrl` or `model` is missing, so a
- *   partially configured parent application still starts.
- * - The integration status is logged exactly once, at construction time.
- * - Calling `request` on a disabled client throws, since an LLM call that
- *   silently returns nothing is rarely what the caller wants. Check
- *   `isEnabled()` before relying on the client.
- * - Provider errors are rethrown as `Error` with the provider message when
- *   available, so callers get actionable failure reasons.
- *
- * @example
- * ```ts
- * const llm = new LLMClient({
- *   apiKey: config.LLM_API_KEY,
- *   apiUrl: config.LLM_API_URL,
- *   model: config.LLM_MODEL,
- *   logger: OTelLogger().createModuleLogger("llm"),
- * });
- *
- * if (llm.isEnabled()) {
- *   const response = await llm.request([
- *     { role: "system", content: "You summarize text." },
- *     { role: "user", content: someText },
- *   ]);
- *   console.log(response.content, response.totalTokens);
- * }
- * ```
- */
-export class LLMClient {
-  private client: AxiosInstance | null = null;
-  private readonly enabled: boolean;
-  private readonly model: string;
-  private readonly timeoutMs: number;
-  private readonly logger: LLMLogger;
-
-  constructor(config: LLMClientConfig) {
-    this.enabled = !!(config.apiKey && config.apiUrl && config.model);
-    this.model = config.model;
-    this.timeoutMs = config.timeoutMs || 120000;
-    this.logger = config.logger || consoleLogger;
-
-    if (this.enabled) {
-      this.client = axios.create({
-        baseURL: config.apiUrl,
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.apiKey}`,
-        },
-        timeout: this.timeoutMs,
-      });
-      this.logger.info(`LLM integration enabled (model: ${this.model})`);
-    } else {
-      this.logger.info(
-        "LLM integration disabled (apiKey, apiUrl or model not set)",
-      );
-    }
-  }
-
-  /**
-   * Check whether the client is properly configured.
-   */
-  public isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  /**
-   * Send a chat completion request.
-   *
-   * @param messages  The chat messages to send.
-   * @param options   Optional per-request overrides (JSON mode, model,
-   *                  timeout). `timeoutMs: 0` disables the request timeout.
-   * @returns The first choice content and total token usage.
-   * @throws When the client is disabled, the provider returns an error, or
-   *         the response has no choices.
-   */
-  public async request(
-    messages: LLMMessage[],
-    options?: LLMRequestOptions,
-  ): Promise<LLMResponse> {
-    if (!this.enabled || !this.client) {
-      throw new Error(
-        "LLM integration disabled (apiKey, apiUrl or model not set)",
-      );
-    }
-
-    const model = options?.model || this.model;
-    const body: Record<string, any> = {
-      model,
-      messages,
-      stream: false,
-    };
-    if (options?.jsonMode) {
-      body.response_format = { type: "json_object" };
-    }
-
-    try {
-      const response =
-        options?.timeoutMs !== undefined
-          ? await this.client.post("", body, { timeout: options.timeoutMs })
-          : await this.client.post("", body);
-      const choice = response.data?.choices?.[0];
-      if (!choice) {
-        throw new Error("LLM response has no choices");
-      }
-      return {
-        content: choice.message?.content || "",
-        totalTokens: response.data?.usage?.total_tokens || 0,
-      };
-    } catch (err) {
-      const message = this.extractErrorMessage(err);
-      this.logger.error(`LLMClient: request failed (${message})`, err);
-      throw new Error(message, { cause: err });
-    }
-  }
-
-  /**
-   * Extract a readable error message, preferring the provider's error
-   * payload when the failure comes from an HTTP response.
-   */
-  private extractErrorMessage(err: unknown): string {
-    if (axios.isAxiosError(err)) {
-      const providerMessage = (err.response?.data as any)?.error?.message;
-      if (providerMessage) {
-        return providerMessage;
-      }
-    }
-    return err instanceof Error ? err.message : String(err);
-  }
-}