gigachat-openai-client 0.1.0

package/README.md

@@ -0,0 +1,213 @@
+# gigachat-openai-client
+
+**gigachat-openai-client** — npm-библиотека для Node.js: доступ к API GigaChat в стиле OpenAI Chat Completions (`models`, `chat/completions` относительно `baseUrl`). Реализованы OAuth (официальный облачный эндпоинт), прямой Basic Auth на произвольный URL, заготовка под mTLS, общая обработка TLS (корпоративные CA, отладка), трассировка и отмена запросов.
+
+Исходный код клиента — [`llm-client.ts`](./llm-client.ts); после **`npm run build`** публикуется как ESM-модуль из каталога **`dist/`**.
+
+### Установка
+
+```bash
+npm install gigachat-openai-client
+```
+
+### Пример
+
+```typescript
+import { ChatClientFactory } from "gigachat-openai-client";
+
+const client = ChatClientFactory.create({
+  baseUrl: "https://gigachat.devices.sberbank.ru/api/v1/",
+  apiToken: process.env.GIGACHAT_AI_TOKEN!,
+});
+```
+
+### Сборка и публикация (для разработчиков пакета)
+
+**`npm run build`** — компиляция в **`dist/`**. Перед **`npm publish`** выполняется **`prepublishOnly`**. Проверить содержимое tarball без выгрузки: **`npm run pack:dry`**.
+
+---
+
+## Назначение `llm-client.ts`
+
+Файл объединяет:
+
+1. **Типы запросов/ответов** — описание тел JSON в формате, близком к OpenAI Chat Completions (`ChatRequest`, `ChatResponse`, сообщения, function calling).
+2. **Три реализации клиента** — разные схемы авторизации к одному и тому же стилю URL.
+3. **Фабрику** — автоматический выбор реализации по базовому URL и наличию токена.
+4. **Общую инфраструктуру** — трассировка вызовов, отмена долгих запросов, TLS для корпоративных сетей, сериализация тела запроса под особенности GigaChat.
+
+Ниже — как это устроено по слоям.
+
+---
+
+## Архитектура (обзор)
+
+```mermaid
+flowchart TB
+  subgraph factory [ChatClientFactory.create]
+    A{Есть apiToken?}
+    B[OAuthGigaChatClient]
+    C[BasicAuthChatClient]
+    D[MtlsChatClient]
+  end
+  A -->|да и URL = официальный api/v1/| B
+  A -->|да и другой URL| C
+  A -->|нет| D
+  B --> L[ChatApiClient.fetchJson + OAuth]
+  C --> L
+  D --> L
+```
+
+- Все конкретные клиенты наследуют **`ChatApiClient`** и реализуют `getModels()` и `postChatCompletions()`.
+- HTTP к API идёт через **`fetchJson`**: единая точка для `fetch`, TLS, трассировки и ошибок.
+
+---
+
+## Фабрика: `ChatClientFactory`
+
+Опции — **`ChatClientFactoryOptions`**:
+
+| Поле | Роль |
+|------|------|
+| `baseUrl` | Базовый URL API (со слэшем на конце или без — внутри нормализуется к виду `…/`) |
+| `apiToken` | Строка токена или `null`/`undefined` |
+| `clientCertificatePath`, `clientPrivateKeyPath` | Пути к клиентскому сертификату и ключу (только при ветке без токена) |
+
+**Правила выбора класса:**
+
+1. **`apiToken` задан** и после нормализации URL **строго равен**  
+   `https://gigachat.devices.sberbank.ru/api/v1/`  
+   → **`OAuthGigaChatClient`**.  
+   Значение — **Basic credentials для OAuth** (не готовый Bearer): см. ниже.
+
+2. **`apiToken` задан**, но URL **другой** (прокси, другой хост, другой путь)  
+   → **`BasicAuthChatClient`**: тот же токен в заголовке `Authorization: Basic …` на ваш `baseUrl`.
+
+3. **`apiToken` не задан**  
+   → **`MtlsChatClient`** (клиентский сертификат). Сейчас **`buildMtlsFetchExtras()`** возвращает `{}` — для Node нужно подставить `dispatcher`/`https.Agent` с `cert`/`key` из путей в конфиге.
+
+---
+
+## Базовый класс: `ChatApiClient`
+
+- **Нормализация URL**: в конструкторе к `baseUrl` добавляется завершающий `/`, если его не было.
+- **`fetchJson(url, init, signal?)`**:
+  - Проверяет **`Cancelable`** (если передан): перед запросом и после — `checkCanceled()`.
+  - Пишет **трассировку** в **`HttpCallTraceStore`**: URL, тело запроса (форматирование JSON, если возможно), ответ, статус, длительность; при ошибке сети — запись с `error`.
+  - Вызывает **`fetch`** с объединением опций: сначала **`tlsFetchInit()`** (кастомный TLS через `undici.Agent`), затем ваши `init`, затем `signal`.
+  - Раз в **500 ms** проверяет отмену: если `cancelable` перевёлся в «отменено», **абортирует** `AbortController`, чтобы прервать `fetch`.
+  - Успех: `response.ok` → парсит JSON в тип `T`. Иначе бросает **`HttpError`** с телом ответа, кодом статуса и URL.
+
+Ошибки сети оборачиваются в `Error("HTTP request failed: …")` с **`cause`**, после записи в трассировку.
+
+---
+
+## TLS: `tlsFetchInit` и переменные окружения
+
+Встроенный **`fetch`** в Node использует **undici**. Для корпоративных CA или отладки TLS добавлен общий **`Agent`**:
+
+| Переменная | Поведение |
+|------------|-----------|
+| **`GIGACHAT_TLS_CA_FILE`** | Путь к PEM-файлу (абсолютный или относительно `process.cwd()`). Содержимое **добавляется** к **`tls.rootCertificates`**; проверка сертификата **включена**. Имеет приоритет над «небезопасным» режимом. |
+| **`GIGACHAT_TLS_INSECURE`** | Значения `1` или `true`: **`rejectUnauthorized: false`** — цепочка не проверяется. **Только если CA-файл не задан.** Небезопасно, только для отладки/изолированной сети. |
+
+Агенты кэшируются (отдельно для CA-пути и для insecure-режима).
+
+Дополнительно в среде можно использовать стандарт Node **`NODE_EXTRA_CA_CERTS`** (файл с доп. CA), если загрузка окружения происходит до первых TLS-запросов.
+
+**Важно:** запрос OAuth в **`OAuthGigaChatClient.ensureAccessToken`** тоже использует **`...tlsFetchInit()`** — те же правила TLS действуют и на `https://ngw.devices.sberbank.ru:...`, и на запросы к `baseUrl`.
+
+---
+
+## `OAuthGigaChatClient` (официальный облачный GigaChat)
+
+- **OAuth**: `POST` на `https://ngw.devices.sberbank.ru:9443/api/v2/oauth` (константа `SBER_OAUTH_TOKEN_URL` в коде).  
+  Тело: `application/x-www-form-urlencoded`, поле `scope=GIGACHAT_API_PERS`.  
+  Заголовки: `Authorization: Basic` + секрет, `RqUID` — случайный UUID (`randomUUID()` из `node:crypto`).
+- Ответ JSON: `access_token`, `expires_at` (мс). Пока текущее время меньше `expires_at`, повторный OAuth не делается.
+- Запросы к **`baseUrl`** (`…/models`, `…/chat/completions`): **`Authorization: Bearer`** + полученный `access_token`.
+
+В `GIGACHAT_AI_TOKEN` / **`ChatClientFactoryOptions.apiToken`** для этой ветки нужен **ключ в формате Basic** (как выдаёт Сбер для API), а не уже готовый Bearer.
+
+---
+
+## `BasicAuthChatClient`
+
+- На **любой** `baseUrl` отправляет **`Authorization: Basic`** с вашим токеном для обоих методов.
+- Подходит для совместимых шлюзов, где не нужен отдельный OAuth к `ngw.devices.sberbank.ru`.
+
+---
+
+## `MtlsChatClient`
+
+- Сценарий **без** `apiToken`, с **`clientCertificatePath` / `clientPrivateKeyPath`** в опциях фабрики.
+- **`buildMtlsFetchExtras()`** сейчас возвращает `{}` — заготовка под **`dispatcher`** с клиентским сертификатом в Node.
+
+---
+
+## Сериализация тела запроса
+
+Внутренние функции **`serializeChatRequestBody`** / **`serializeChatMessageForApi`**:
+
+- В JSON всегда попадает поле **`content`**, в т.ч. **`null`** — так ожидает GigaChat для части сценариев.
+- Для **function call** в TypeScript **`arguments`** хранится **строкой** (как JSON), а в тело запроса уходит **распарсенный объект** (`parseFunctionArgumentsJson`), потому что GigaChat ожидает **объект**, а не строку.
+
+Поля `functions` и `function_call` в корне запроса добавляются только если они заданы (не `null`/`undefined`).
+
+---
+
+## Трассировка: `HttpCallTraceStore`
+
+Глобальный буфер (до **500** последних записей типа **`HttpCallTrace`**): идентификатор, время, URL, JSON запроса/ответа, HTTP-статус, длительность, при сбое — текст ошибки. Методы: **`nextTraceId`**, **`record`**, **`getAll`**, **`clear`**.
+
+---
+
+## Отмена: `Cancelable` / `CancelFlag`
+
+Опционально передаётся в конструкторы клиентов. При вызове **`cancel()`** последующие **`checkCanceled()`** бросают ошибку, а активный **`fetch`** стараются прервать через **AbortSignal**.
+
+---
+
+## Ошибки: `HttpError`
+
+Наследник `Error`: помимо сообщения (часто тело ответа сервера) доступны **`statusCode`** и **`url`**.
+
+---
+
+## Связь с `llm-test.ts`
+
+Скрипт загружает **`.env`** (`dotenv/config`), читает переменные и вызывает **`ChatClientFactory.create({ baseUrl: …, apiToken: … })`**, затем **`postChatCompletions`**. Переменные окружения для теста:
+
+| Переменная | Назначение |
+|------------|------------|
+| `GIGACHAT_AI_TOKEN` | Обязательна для текущего сценария |
+| `GIGACHAT_AI_URL` | По умолчанию официальный `…/api/v1/` |
+| `GIGACHAT_MODEL`, `GIGACHAT_PROMPT` | Модель и текст запроса |
+| `GIGACHAT_TLS_CA_FILE`, `GIGACHAT_TLS_INSECURE` | См. раздел TLS |
+
+Запуск (нужен Node с поддержкой загрузки `.ts`, например флаг типов):
+
+```bash
+npm test
+# или
+node --experimental-transform-types llm-test.ts
+```
+
+---
+
+## Зависимости, влияющие на `llm-client.ts`
+
+- **`undici`** — `Agent` для кастомного TLS в **`fetch`**.
+- Остальное — модули Node: `fs`, `path`, `tls`, `crypto` (`randomUUID`).
+
+---
+
+## Краткая шпаргалка по выбору режима
+
+| Условие | Клиент |
+|---------|--------|
+| URL = `https://gigachat.devices.sberbank.ru/api/v1/` и есть токен | `OAuthGigaChatClient` (OAuth → Bearer) |
+| Другой URL и есть токен | `BasicAuthChatClient` (Basic) |
+| Нет токена | `MtlsChatClient` (mTLS — доработать `buildMtlsFetchExtras`) |
+
+Если документация расходится с кодом, ориентируйтесь на актуальную реализацию в **`llm-client.ts`** (в опубликованном пакете — на собранные файлы в **`dist/`**).

package/dist/llm-client.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Клиенты для GigaChat-совместимого API (`/models`, `/chat/completions`).
+ *
+ * **Реализации:** {@link ChatApiClient} — база; {@link OAuthGigaChatClient} — OAuth (официальный URL + Basic-ключ);
+ * {@link BasicAuthChatClient} — `Authorization: Basic` на произвольный URL; {@link MtlsChatClient} — mTLS (см. `buildMtlsFetchExtras`).
+ *
+ * **TLS:** `GIGACHAT_TLS_CA_FILE`, `GIGACHAT_TLS_INSECURE` — см. {@link tlsFetchInit}.
+ */
+export interface PropertySchema {
+    type: string;
+    description: string;
+}
+export interface FunctionParameters {
+    type: "object";
+    properties: Record<string, PropertySchema>;
+    required?: string[];
+}
+export interface FunctionDefinition {
+    name: string;
+    description: string;
+    parameters: FunctionParameters;
+}
+/**
+ * GigaChat отправляет `arguments` как JSON-объект, OpenAI — как JSON-строку.
+ * В TypeScript храним всегда как строку, сериализуем в объект при отправке.
+ */
+export interface FunctionCall {
+    name: string;
+    /** JSON-строка аргументов, например '{"path":"/foo"}' */
+    arguments: string;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "function";
+    /** null разрешён — GigaChat требует явное поле в assistant+FC сообщении */
+    content: string | null;
+    function_call?: FunctionCall;
+    /** Имя функции (для role="function") */
+    name?: string;
+}
+export interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature: number;
+    max_tokens: number;
+    /** null → поле не отправляется */
+    functions?: FunctionDefinition[];
+    /** "auto" | "none" */
+    function_call?: string;
+}
+export interface ResponseChoice {
+    message?: ChatMessage;
+    index: number;
+    finish_reason?: string;
+}
+export interface Usage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+}
+export interface ChatResponse {
+    choices: ResponseChoice[];
+    model?: string;
+    usage?: Usage;
+}
+export interface ModelInfo {
+    id: string;
+    object?: string;
+    owned_by?: string;
+}
+export interface ModelsResponse {
+    data: ModelInfo[];
+}
+export interface TokenResponse {
+    access_token: string;
+    expires_at: number;
+}
+export interface HttpCallTrace {
+    id: number;
+    timestamp: Date;
+    url: string;
+    requestJson: string;
+    responseJson: string;
+    statusCode: number;
+    durationMs: number;
+    error?: string;
+}
+export declare const HttpCallTraceStore: {
+    nextTraceId: () => number;
+    record(trace: HttpCallTrace): void;
+    getAll(): readonly HttpCallTrace[];
+    clear(): void;
+};
+export interface Cancelable {
+    isCanceled(): boolean;
+    checkCanceled(): void;
+}
+/** Флаг отмены: вызовите `cancel()`, затем `checkCanceled()` прервёт ожидание. */
+export declare class CancelFlag implements Cancelable {
+    private _canceled;
+    cancel(): void;
+    isCanceled(): boolean;
+    checkCanceled(): void;
+}
+/** Нормализация base URL, TLS, трассировка, отмена. */
+export declare abstract class ChatApiClient {
+    protected readonly baseUrl: string;
+    protected readonly cancelable?: Cancelable;
+    constructor(baseUrl: string, cancelable?: Cancelable);
+    abstract getModels(): Promise<ModelsResponse>;
+    abstract postChatCompletions(request: ChatRequest): Promise<ChatResponse>;
+    /** Один HTTP-запрос с JSON-ответом, трассировкой и поддержкой {@link tlsFetchInit}. */
+    protected fetchJson<T>(url: string, init: RequestInit, signal?: AbortSignal): Promise<T>;
+}
+export declare class HttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    constructor(message: string, statusCode: number, url: string);
+}
+/** Basic-ключ → OAuth на `ngw`, затем Bearer к `baseUrl`. */
+export declare class OAuthGigaChatClient extends ChatApiClient {
+    private readonly oauthBasicSecret;
+    private accessToken;
+    private accessTokenExpiresAtMs;
+    constructor(baseUrl: string, oauthBasicSecret: string, cancelable?: Cancelable);
+    private ensureAccessToken;
+    getModels(): Promise<ModelsResponse>;
+    postChatCompletions(request: ChatRequest): Promise<ChatResponse>;
+}
+/** Тот же токен в `Authorization: Basic` для любого совместимого `baseUrl`. */
+export declare class BasicAuthChatClient extends ChatApiClient {
+    private readonly basicAuthToken;
+    constructor(baseUrl: string, basicAuthToken: string, cancelable?: Cancelable);
+    getModels(): Promise<ModelsResponse>;
+    postChatCompletions(request: ChatRequest): Promise<ChatResponse>;
+}
+export interface MtlsChatClientConfig {
+    baseUrl: string;
+    /** Путь к PEM сертификата или base64-PEM */
+    certificatePath?: string;
+    privateKeyPath?: string;
+    cancelable?: Cancelable;
+}
+/**
+ * Доступ по клиентскому сертификату.
+ * Реализуйте {@link MtlsChatClient.buildMtlsFetchExtras} (например `dispatcher` с `https.Agent`).
+ */
+export declare class MtlsChatClient extends ChatApiClient {
+    private readonly certificatePath?;
+    private readonly privateKeyPath?;
+    constructor(config: MtlsChatClientConfig);
+    getModels(): Promise<ModelsResponse>;
+    postChatCompletions(request: ChatRequest): Promise<ChatResponse>;
+    /** Доп. опции `fetch` для mTLS в Node (сейчас пусто). */
+    protected buildMtlsFetchExtras(): Record<string, unknown>;
+}
+/** Параметры для {@link ChatClientFactory.create}. */
+export interface ChatClientFactoryOptions {
+    /** Базовый URL API (со слэшем или без). */
+    baseUrl: string;
+    /**
+     * Для официального `…/api/v1/` — секрет для Basic OAuth;
+     * для другого URL — значение для `Authorization: Basic`.
+     */
+    apiToken?: string | null;
+    clientCertificatePath?: string | null;
+    clientPrivateKeyPath?: string | null;
+}
+/**
+ * Официальный `…/api/v1/` + `apiToken` → {@link OAuthGigaChatClient};
+ * иной URL + `apiToken` → {@link BasicAuthChatClient};
+ * без токена → {@link MtlsChatClient}.
+ */
+export declare class ChatClientFactory {
+    static create(options: ChatClientFactoryOptions, cancelable?: Cancelable): ChatApiClient;
+}
+//# sourceMappingURL=llm-client.d.ts.map

package/dist/llm-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-client.d.ts","sourceRoot":"","sources":["../llm-client.ts"],"names":[],"mappings":"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"}

package/dist/llm-client.js

@@ -0,0 +1,337 @@
+/**
+ * Клиенты для GigaChat-совместимого API (`/models`, `/chat/completions`).
+ *
+ * **Реализации:** {@link ChatApiClient} — база; {@link OAuthGigaChatClient} — OAuth (официальный URL + Basic-ключ);
+ * {@link BasicAuthChatClient} — `Authorization: Basic` на произвольный URL; {@link MtlsChatClient} — mTLS (см. `buildMtlsFetchExtras`).
+ *
+ * **TLS:** `GIGACHAT_TLS_CA_FILE`, `GIGACHAT_TLS_INSECURE` — см. {@link tlsFetchInit}.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import tls from "node:tls";
+import { randomUUID } from "node:crypto";
+import { Agent } from "undici";
+let _tlsInsecureAgent;
+let _tlsCaAgent;
+let _tlsCaResolvedPath;
+function envTruthy(v) {
+    return v === "1" || v === "true";
+}
+/**
+ * Опции TLS для встроенного `fetch`: дополнительный PEM (`GIGACHAT_TLS_CA_FILE`) или отключение проверки (`GIGACHAT_TLS_INSECURE`).
+ * Приоритет у CA-файла.
+ */
+function tlsFetchInit() {
+    const caRaw = process.env.GIGACHAT_TLS_CA_FILE?.trim();
+    if (caRaw) {
+        const resolved = path.isAbsolute(caRaw) ? caRaw : path.resolve(process.cwd(), caRaw);
+        if (_tlsCaAgent && _tlsCaResolvedPath === resolved)
+            return { dispatcher: _tlsCaAgent };
+        const extra = fs.readFileSync(resolved, "utf8");
+        _tlsCaAgent = new Agent({
+            connect: { ca: [...tls.rootCertificates, extra], rejectUnauthorized: true },
+        });
+        _tlsCaResolvedPath = resolved;
+        return { dispatcher: _tlsCaAgent };
+    }
+    if (!envTruthy(process.env.GIGACHAT_TLS_INSECURE))
+        return {};
+    if (!_tlsInsecureAgent) {
+        _tlsInsecureAgent = new Agent({ connect: { rejectUnauthorized: false } });
+    }
+    return { dispatcher: _tlsInsecureAgent };
+}
+let _traceSeq = 0;
+const _httpTraces = [];
+export const HttpCallTraceStore = {
+    nextTraceId: () => ++_traceSeq,
+    record(trace) {
+        _httpTraces.push(trace);
+        if (_httpTraces.length > 500)
+            _httpTraces.shift();
+    },
+    getAll() {
+        return _httpTraces;
+    },
+    clear() {
+        _httpTraces.splice(0);
+    },
+};
+/** Флаг отмены: вызовите `cancel()`, затем `checkCanceled()` прервёт ожидание. */
+export class CancelFlag {
+    _canceled = false;
+    cancel() { this._canceled = true; }
+    isCanceled() { return this._canceled; }
+    checkCanceled() {
+        if (this._canceled)
+            throw new Error("Operation was canceled");
+    }
+}
+// --- Базовый клиент ---
+/** Нормализация base URL, TLS, трассировка, отмена. */
+export class ChatApiClient {
+    baseUrl;
+    cancelable;
+    constructor(baseUrl, cancelable) {
+        this.baseUrl = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
+        this.cancelable = cancelable;
+    }
+    /** Один HTTP-запрос с JSON-ответом, трассировкой и поддержкой {@link tlsFetchInit}. */
+    async fetchJson(url, init, signal) {
+        this.cancelable?.checkCanceled();
+        const traceId = HttpCallTraceStore.nextTraceId();
+        const startedAt = new Date();
+        const requestJson = init.body ? formatJsonIfPossible(init.body.toString()) : "";
+        try {
+            const controller = new AbortController();
+            const mergedSignal = signal ?? controller.signal;
+            const cancelPoll = setInterval(() => {
+                if (this.cancelable?.isCanceled())
+                    controller.abort();
+            }, 500);
+            let response;
+            try {
+                response = await fetch(url, { ...tlsFetchInit(), ...init, signal: mergedSignal });
+            }
+            finally {
+                clearInterval(cancelPoll);
+            }
+            this.cancelable?.checkCanceled();
+            const bodyText = await response.text();
+            const durationMs = Date.now() - startedAt.getTime();
+            HttpCallTraceStore.record({
+                id: traceId,
+                timestamp: startedAt,
+                url,
+                requestJson,
+                responseJson: formatJsonIfPossible(bodyText),
+                statusCode: response.status,
+                durationMs,
+            });
+            if (response.ok) {
+                return JSON.parse(bodyText);
+            }
+            throw new HttpError(bodyText, response.status, url);
+        }
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
+            const durationMs = Date.now() - startedAt.getTime();
+            const message = err instanceof Error ? err.message : String(err);
+            HttpCallTraceStore.record({
+                id: traceId,
+                timestamp: startedAt,
+                url,
+                requestJson,
+                responseJson: "",
+                statusCode: 0,
+                durationMs,
+                error: message,
+            });
+            throw new Error(`HTTP request failed: ${message}`, { cause: err });
+        }
+    }
+}
+export class HttpError extends Error {
+    statusCode;
+    url;
+    constructor(message, statusCode, url) {
+        super(message);
+        this.name = "HttpError";
+        this.statusCode = statusCode;
+        this.url = url;
+    }
+}
+function formatJsonIfPossible(text) {
+    try {
+        return JSON.stringify(JSON.parse(text), null, 2);
+    }
+    catch {
+        return text;
+    }
+}
+// --- OAuth: официальный облачный GigaChat ---
+const SBER_OAUTH_TOKEN_URL = "https://ngw.devices.sberbank.ru:9443/api/v2/oauth";
+/** Basic-ключ → OAuth на `ngw`, затем Bearer к `baseUrl`. */
+export class OAuthGigaChatClient extends ChatApiClient {
+    oauthBasicSecret;
+    accessToken = "";
+    accessTokenExpiresAtMs = 0;
+    constructor(baseUrl, oauthBasicSecret, cancelable) {
+        super(baseUrl, cancelable);
+        this.oauthBasicSecret = oauthBasicSecret;
+    }
+    async ensureAccessToken() {
+        if (this.accessTokenExpiresAtMs > Date.now())
+            return;
+        const formBody = new URLSearchParams({ scope: "GIGACHAT_API_PERS" });
+        const requestId = randomUUID();
+        const response = await fetch(SBER_OAUTH_TOKEN_URL, {
+            ...tlsFetchInit(),
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+                RqUID: requestId,
+                Authorization: `Basic ${this.oauthBasicSecret}`,
+            },
+            body: formBody.toString(),
+        });
+        if (!response.ok) {
+            throw new HttpError(await response.text(), response.status, SBER_OAUTH_TOKEN_URL);
+        }
+        const token = await response.json();
+        this.accessToken = token.access_token;
+        this.accessTokenExpiresAtMs = token.expires_at;
+    }
+    async getModels() {
+        await this.ensureAccessToken();
+        return this.fetchJson(this.baseUrl + "models", {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${this.accessToken}`,
+            },
+        });
+    }
+    async postChatCompletions(request) {
+        await this.ensureAccessToken();
+        return this.fetchJson(this.baseUrl + "chat/completions", {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.accessToken}`,
+            },
+            body: serializeChatRequestBody(request),
+        });
+    }
+}
+// --- Basic Auth на произвольный хост ---
+/** Тот же токен в `Authorization: Basic` для любого совместимого `baseUrl`. */
+export class BasicAuthChatClient extends ChatApiClient {
+    basicAuthToken;
+    constructor(baseUrl, basicAuthToken, cancelable) {
+        super(baseUrl, cancelable);
+        this.basicAuthToken = basicAuthToken;
+    }
+    async getModels() {
+        return this.fetchJson(this.baseUrl + "models", {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+                Authorization: `Basic ${this.basicAuthToken}`,
+            },
+        });
+    }
+    async postChatCompletions(request) {
+        return this.fetchJson(this.baseUrl + "chat/completions", {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Basic ${this.basicAuthToken}`,
+            },
+            body: serializeChatRequestBody(request),
+        });
+    }
+}
+/**
+ * Доступ по клиентскому сертификату.
+ * Реализуйте {@link MtlsChatClient.buildMtlsFetchExtras} (например `dispatcher` с `https.Agent`).
+ */
+export class MtlsChatClient extends ChatApiClient {
+    certificatePath;
+    privateKeyPath;
+    constructor(config) {
+        super(config.baseUrl, config.cancelable);
+        this.certificatePath = config.certificatePath;
+        this.privateKeyPath = config.privateKeyPath;
+    }
+    async getModels() {
+        return this.fetchJson(this.baseUrl + "models", {
+            method: "GET",
+            headers: { Accept: "application/json" },
+            ...this.buildMtlsFetchExtras(),
+        });
+    }
+    async postChatCompletions(request) {
+        return this.fetchJson(this.baseUrl + "chat/completions", {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: serializeChatRequestBody(request),
+            ...this.buildMtlsFetchExtras(),
+        });
+    }
+    /** Доп. опции `fetch` для mTLS в Node (сейчас пусто). */
+    buildMtlsFetchExtras() {
+        return {};
+    }
+}
+// --- Тело запроса (GigaChat: `arguments` — объект, `content` может быть `null`) ---
+function serializeChatMessageForApi(msg) {
+    const out = {
+        role: msg.role,
+        content: msg.content ?? null,
+    };
+    if (msg.function_call) {
+        out.function_call = {
+            name: msg.function_call.name,
+            arguments: parseFunctionArgumentsJson(msg.function_call.arguments),
+        };
+    }
+    if (msg.name != null)
+        out.name = msg.name;
+    return out;
+}
+function parseFunctionArgumentsJson(args) {
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        return {};
+    }
+}
+function serializeChatRequestBody(request) {
+    const body = {
+        model: request.model,
+        messages: request.messages.map(serializeChatMessageForApi),
+        temperature: request.temperature,
+        max_tokens: request.max_tokens,
+    };
+    if (request.functions != null)
+        body.functions = request.functions;
+    if (request.function_call != null)
+        body.function_call = request.function_call;
+    return JSON.stringify(body);
+}
+// --- Фабрика ---
+const OFFICIAL_GIGACHAT_API_BASE = "https://gigachat.devices.sberbank.ru/api/v1/";
+/**
+ * Официальный `…/api/v1/` + `apiToken` → {@link OAuthGigaChatClient};
+ * иной URL + `apiToken` → {@link BasicAuthChatClient};
+ * без токена → {@link MtlsChatClient}.
+ */
+export class ChatClientFactory {
+    static create(options, cancelable) {
+        const hasToken = Boolean(options.apiToken);
+        const normalizedBase = options.baseUrl.endsWith("/")
+            ? options.baseUrl
+            : options.baseUrl + "/";
+        if (hasToken && normalizedBase === OFFICIAL_GIGACHAT_API_BASE) {
+            return new OAuthGigaChatClient(normalizedBase, options.apiToken, cancelable);
+        }
+        if (hasToken) {
+            return new BasicAuthChatClient(normalizedBase, options.apiToken, cancelable);
+        }
+        return new MtlsChatClient({
+            baseUrl: normalizedBase,
+            certificatePath: options.clientCertificatePath ?? undefined,
+            privateKeyPath: options.clientPrivateKeyPath ?? undefined,
+            cancelable,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "gigachat-openai-client",
+  "version": "0.1.0",
+  "description": "GigaChat API client for Node.js (OpenAI-compatible /v1/models and /v1/chat/completions): OAuth, Basic auth, mTLS hooks, TLS helpers",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/llm-client.js",
+  "types": "./dist/llm-client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/llm-client.d.ts",
+      "import": "./dist/llm-client.js",
+      "default": "./dist/llm-client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-transform-types llm-test.ts",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "gigachat",
+    "openai",
+    "openai-compatible",
+    "sber",
+    "llm",
+    "chat"
+  ],
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "undici": "^7.24.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}