@devopsplaybook.io/common-utils 1.4.0 → 1.5.0-beta.14.dd2303d

package/AGENTS.md

@@ -29,6 +29,7 @@ src/
     UsersRoutes.ts          # Standard fastify user management routes
   SystemCommand.ts          # Promise wrapper around child_process.exec
   Timeout.ts                # Promise wrapper around setTimeout
+  LLM.ts                    # OpenAI-compatible chat completions client (LLMClient)
   *.spec.ts                 # Co-located test files
 .github/workflows/
   main-build.yml            # Caller: push to main -> reusable-npm-merge

package/README.md

@@ -33,7 +33,7 @@ npm install @devopsplaybook.io/common-utils
 | `pg`                            | PostgreSQL client (`Pool`)                          |
 | `fs-extra`                      | File system helpers                                 |
 | `uuid`                          | UUID generation for JWT keys                        |
-| `axios`                         | HTTP client for the notifications integration        |
+| `axios`                         | HTTP client for the notifications and LLM integrations |
 | `bcrypt`                        | Password hashing for the users module               |
 | `jsonwebtoken`                  | JWT signing/verification for the auth module        |
 | `fastify`                       | HTTP framework types for the users routes           |
@@ -336,6 +336,48 @@ await client.send({
 
 ---
 
+#### `LLM` -- OpenAI-Compatible Chat Completions Client
+
+Client for any OpenAI-compatible chat completions API (DeepSeek, Moonshot, Ollama, etc.), centralizing the `LLM_API_KEY` / `LLM_API_URL` / `LLM_MODEL` integration used across server projects. The client follows the same fail-safe pattern as the notifications client: it is disabled (and logs once at construction) when `apiKey`, `apiUrl` or `model` is missing. Unlike notifications, `request` on a disabled client throws, since a silently empty LLM result is rarely what the caller wants — check `isEnabled()` first.
+
+```ts
+import { LLMClient } from "@devopsplaybook.io/common-utils";
+
+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);
+
+  // JSON output mode (response_format: json_object) and per-call model override
+  const json = await llm.request(
+    [{ role: "user", content: "Reply with a JSON object" }],
+    { jsonMode: true, model: "other-model" },
+  );
+}
+```
+
+| Export               | Description                                                                |
+| -------------------- | -------------------------------------------------------------------------- |
+| `LLMClient`          | HTTP client with `isEnabled()` and `request(messages, options?)`           |
+| `LLMClientConfig`    | `{ apiKey, apiUrl, model, timeoutMs?, logger? }` constructor configuration |
+| `LLMMessage`         | `{ role, content }` chat message                                           |
+| `LLMRequestOptions`  | `{ jsonMode?, model? }` per-request overrides                              |
+| `LLMResponse`        | `{ content, totalTokens }` normalized response                             |
+| `LLMLogger`          | Minimal logger interface (`info`/`error`), console by default              |
+
+**Behaviour details**: requests are sent with `stream: false` and Bearer authentication; the default timeout is 120 seconds (`timeoutMs` overrides it). Provider errors are rethrown as `Error` carrying the provider message when available (e.g., `error.message` from the HTTP response). An empty content is returned as-is — applications that need an empty-content policy (e.g., retry on reasoning models) keep it in their own code.
+
+---
+
 #### `Auth`, `User`, `UserSession`, `UserPassword`, `UsersData`, `UsersRoutes` -- Authentication and User Management
 
 Standard JWT-based authentication and user management shared across all server projects: JWT key persistence in the `metadata` table, request authentication helpers, bcrypt password hashing, users CRUD, and ready-to-register fastify routes (login, user CRUD, password change).

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./src/DbUtilsNoTelemetry";
 export * from "./src/SqlDbUtils";
 export * from "./src/PostgresDbUtils";
 export * from "./src/Notifications";
+export * from "./src/LLM";
 export * from "./src/SystemCommand";
 export * from "./src/Timeout";
 export * from "./src/users/User";

package/dist/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./src/DbUtilsNoTelemetry"), exports);
 __exportStar(require("./src/SqlDbUtils"), exports);
 __exportStar(require("./src/PostgresDbUtils"), exports);
 __exportStar(require("./src/Notifications"), exports);
+__exportStar(require("./src/LLM"), exports);
 __exportStar(require("./src/SystemCommand"), exports);
 __exportStar(require("./src/Timeout"), exports);
 __exportStar(require("./src/users/User"), exports);

package/dist/src/LLM.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare class LLMClient {
+    private client;
+    private readonly enabled;
+    private readonly model;
+    private readonly timeoutMs;
+    private readonly logger;
+    constructor(config: LLMClientConfig);
+    /**
+     * Check whether the client is properly configured.
+     */
+    isEnabled(): boolean;
+    /**
+     * Send a chat completion request.
+     *
+     * @param messages  The chat messages to send.
+     * @param options   Optional per-request overrides (JSON mode, model).
+     * @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.
+     */
+    request(messages: LLMMessage[], options?: LLMRequestOptions): Promise<LLMResponse>;
+    /**
+     * Extract a readable error message, preferring the provider's error
+     * payload when the failure comes from an HTTP response.
+     */
+    private extractErrorMessage;
+}

package/dist/src/LLM.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+/** Console fallback used when no logger is injected. */
+const consoleLogger = {
+    info: (message) => console.log(message),
+    error: (message, err) => 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);
+ * }
+ * ```
+ */
+class LLMClient {
+    constructor(config) {
+        this.client = null;
+        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_1.default.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.
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Send a chat completion request.
+     *
+     * @param messages  The chat messages to send.
+     * @param options   Optional per-request overrides (JSON mode, model).
+     * @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.
+     */
+    async request(messages, options) {
+        var _a, _b, _c, _d, _e;
+        if (!this.enabled || !this.client) {
+            throw new Error("LLM integration disabled (apiKey, apiUrl or model not set)");
+        }
+        const model = (options === null || options === void 0 ? void 0 : options.model) || this.model;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = {
+            model,
+            messages,
+            stream: false,
+        };
+        if (options === null || options === void 0 ? void 0 : options.jsonMode) {
+            body.response_format = { type: "json_object" };
+        }
+        try {
+            const response = await this.client.post("", body);
+            const choice = (_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.choices) === null || _b === void 0 ? void 0 : _b[0];
+            if (!choice) {
+                throw new Error("LLM response has no choices");
+            }
+            return {
+                content: ((_c = choice.message) === null || _c === void 0 ? void 0 : _c.content) || "",
+                totalTokens: ((_e = (_d = response.data) === null || _d === void 0 ? void 0 : _d.usage) === null || _e === void 0 ? void 0 : _e.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.
+     */
+    extractErrorMessage(err) {
+        var _a, _b, _c;
+        if (axios_1.default.isAxiosError(err)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const providerMessage = (_c = (_b = (_a = err.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.error) === null || _c === void 0 ? void 0 : _c.message;
+            if (providerMessage) {
+                return providerMessage;
+            }
+        }
+        return err instanceof Error ? err.message : String(err);
+    }
+}
+exports.LLMClient = LLMClient;

package/dist/src/users/Auth.js

@@ -71,7 +71,7 @@ async function AuthInit(context, configIn, allScopes = []) {
     const authKeyRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_AUTH_TOKEN);
     if (authKeyRaw.length == 0) {
         configIn.JWT_KEY = (0, uuid_1.v4)();
-        await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
             configIn.JWT_KEY,
             new Date().toISOString(),
         ]);

package/index.ts

@@ -5,6 +5,7 @@ export * from "./src/DbUtilsNoTelemetry";
 export * from "./src/SqlDbUtils";
 export * from "./src/PostgresDbUtils";
 export * from "./src/Notifications";
+export * from "./src/LLM";
 export * from "./src/SystemCommand";
 export * from "./src/Timeout";
 export * from "./src/users/User";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.4.0",
-  "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, auth/users, notifications, system helpers)",
+  "version": "1.5.0-beta.14.dd2303d",
+  "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, auth/users, notifications, LLM, system helpers)",
   "keywords": [
     "Open Telemetry",
     "OTel",
@@ -12,6 +12,7 @@
     "JWT",
     "Users",
     "Notifications",
+    "LLM",
     "Utilities"
   ],
   "license": "ISC",

package/src/LLM.spec.ts

@@ -0,0 +1,248 @@
+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 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

@@ -0,0 +1,195 @@
+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;
+}
+
+/**
+ * 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).
+   * @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;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const body: Record<string, any> = {
+      model,
+      messages,
+      stream: false,
+    };
+    if (options?.jsonMode) {
+      body.response_format = { type: "json_object" };
+    }
+
+    try {
+      const response = 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)) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const providerMessage = (err.response?.data as any)?.error?.message;
+      if (providerMessage) {
+        return providerMessage;
+      }
+    }
+    return err instanceof Error ? err.message : String(err);
+  }
+}

package/src/users/Auth.ts

@@ -2,7 +2,7 @@ import { StandardTracer } from "@devopsplaybook.io/otel-utils";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import * as jwt from "jsonwebtoken";
 import { v4 as uuidv4 } from "uuid";
-import { DbUtilsQuerySQL } from "../DbUtils";
+import { DbUtilsExecSQL, DbUtilsQuerySQL } from "../DbUtils";
 import { User, UserScope } from "./User";
 import { UserSession } from "./UserSession";
 
@@ -48,7 +48,7 @@ export async function AuthInit(
   const authKeyRaw = await DbUtilsQuerySQL(span, SQL_QUERIES.GET_AUTH_TOKEN);
   if (authKeyRaw.length == 0) {
     configIn.JWT_KEY = uuidv4();
-    await DbUtilsQuerySQL(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
+    await DbUtilsExecSQL(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
       configIn.JWT_KEY,
       new Date().toISOString(),
     ]);

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2019",
+    "lib": ["ES2019", "ES2022.Error"],
     "module": "commonjs",
     "declaration": true,
     "outDir": "./dist",