@boristype/ws-client 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BorisType
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/client.d.ts

@@ -0,0 +1,69 @@
+import { WshcmClientOptions } from './types.js';
+import { Evaluator } from './evaluator.js';
+/**
+ * Клиент для работы с WebSoft HCM через SP-XML API
+ *
+ * @example
+ * ```typescript
+ * const client = new WshcmClient({
+ *   overHttps: false,
+ *   host: 'localhost',
+ *   port: 8080,
+ *   username: 'admin',
+ *   password: 'password'
+ * });
+ *
+ * await client.initialize();
+ * const result = await client.callMethod<string>('tools', 'some_method', ['arg1', 'arg2']);
+ *
+ * const evaluator = client.createEvaluator();
+ * await evaluator.initialize();
+ * // ... use evaluator ...
+ * await evaluator.close();
+ * ```
+ */
+export declare class WshcmClient {
+    private baseUrl;
+    private username;
+    private password;
+    private cookies;
+    private isHttps;
+    private requestTimeout;
+    /**
+     * Создает новый экземпляр WSHCM-клиента
+     * @param options - опции подключения
+     */
+    constructor(options: WshcmClientOptions);
+    /**
+     * Инициализирует клиент и проверяет авторизацию
+     * Должен быть вызван после создания экземпляра
+     */
+    initialize(): Promise<void>;
+    /**
+     * Вызывает метод через SP-XML API
+     * @template T - тип возвращаемого значения
+     * @param lib - библиотека/модуль (например, "tools", или URL модуля)
+     * @param method - имя метода
+     * @param methodArgs - массив аргументов метода
+     * @returns результат выполнения метода
+     */
+    callMethod<T = any>(lib: string, method: string, methodArgs?: any[]): Promise<T>;
+    /**
+     * Создаёт новый Evaluator для выполнения произвольного кода на сервере.
+     *
+     * Вызывающий код отвечает за lifecycle evaluator-а:
+     * вызов `initialize()` перед использованием и `close()` после завершения.
+     *
+     * @returns новый экземпляр Evaluator
+     */
+    createEvaluator(): Evaluator;
+    /**
+     * Выполняет HTTP-запрос
+     * @param path - путь запроса
+     * @param method - HTTP-метод
+     * @param headers - заголовки
+     * @param body - тело запроса
+     * @returns статус-код или тело ответа
+     */
+    private makeRequest;
+}

package/build/client.js

@@ -0,0 +1,156 @@
+import * as https from 'https';
+import * as http from 'http';
+import { UnauthorizedError, WshcmException } from './exceptions.js';
+import { renderRequest, parseResponse } from './soap-utils.js';
+import { Evaluator } from './evaluator.js';
+// ============================================================================
+// Main WSHCM Client
+// ============================================================================
+/** Таймаут HTTP-запросов по умолчанию (30 секунд) */
+const DEFAULT_REQUEST_TIMEOUT = 30_000;
+/**
+ * Клиент для работы с WebSoft HCM через SP-XML API
+ *
+ * @example
+ * ```typescript
+ * const client = new WshcmClient({
+ *   overHttps: false,
+ *   host: 'localhost',
+ *   port: 8080,
+ *   username: 'admin',
+ *   password: 'password'
+ * });
+ *
+ * await client.initialize();
+ * const result = await client.callMethod<string>('tools', 'some_method', ['arg1', 'arg2']);
+ *
+ * const evaluator = client.createEvaluator();
+ * await evaluator.initialize();
+ * // ... use evaluator ...
+ * await evaluator.close();
+ * ```
+ */
+export class WshcmClient {
+    baseUrl;
+    username;
+    password;
+    cookies = [];
+    isHttps;
+    requestTimeout;
+    /**
+     * Создает новый экземпляр WSHCM-клиента
+     * @param options - опции подключения
+     */
+    constructor(options) {
+        this.isHttps = options.overHttps;
+        this.baseUrl = `${options.overHttps ? 'https' : 'http'}://${options.host}:${options.port}`;
+        this.username = options.username;
+        this.password = options.password;
+        this.requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+    }
+    /**
+     * Инициализирует клиент и проверяет авторизацию
+     * Должен быть вызван после создания экземпляра
+     */
+    async initialize() {
+        const statusCode = await this.makeRequest('/spxml_web/main.htm', 'GET');
+        if (statusCode !== 200) {
+            throw new UnauthorizedError();
+        }
+    }
+    /**
+     * Вызывает метод через SP-XML API
+     * @template T - тип возвращаемого значения
+     * @param lib - библиотека/модуль (например, "tools", или URL модуля)
+     * @param method - имя метода
+     * @param methodArgs - массив аргументов метода
+     * @returns результат выполнения метода
+     */
+    async callMethod(lib, method, methodArgs = []) {
+        const headers = {
+            'accept': '*/*',
+            'accept-language': 'ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7',
+            'cache-control': 'no-cache',
+            'content-type': 'application/soap+xml; charset=UTF-8',
+            'pragma': 'no-cache',
+            'x-spxml-client': 'SP-XML Web client 1.0',
+        };
+        const body = renderRequest(lib, method, methodArgs);
+        const responseText = await this.makeRequest('/api/spxml/CallMethod', 'POST', headers, body);
+        return parseResponse(responseText);
+    }
+    /**
+     * Создаёт новый Evaluator для выполнения произвольного кода на сервере.
+     *
+     * Вызывающий код отвечает за lifecycle evaluator-а:
+     * вызов `initialize()` перед использованием и `close()` после завершения.
+     *
+     * @returns новый экземпляр Evaluator
+     */
+    createEvaluator() {
+        return new Evaluator(this);
+    }
+    /**
+     * Выполняет HTTP-запрос
+     * @param path - путь запроса
+     * @param method - HTTP-метод
+     * @param headers - заголовки
+     * @param body - тело запроса
+     * @returns статус-код или тело ответа
+     */
+    makeRequest(path, method, headers = {}, body) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(this.baseUrl + path);
+            const auth = Buffer.from(`${this.username}:${this.password}`).toString('base64');
+            const allHeaders = {
+                ...headers,
+                'Authorization': `Basic ${auth}`,
+            };
+            if (this.cookies.length > 0) {
+                allHeaders['Cookie'] = this.cookies.join('; ');
+            }
+            if (body) {
+                allHeaders['Content-Length'] = Buffer.byteLength(body).toString();
+            }
+            const options = {
+                hostname: url.hostname,
+                port: url.port,
+                path: url.pathname + url.search,
+                method: method,
+                headers: allHeaders,
+                timeout: this.requestTimeout,
+            };
+            const lib = this.isHttps ? https : http;
+            const req = lib.request(options, (res) => {
+                // Сохраняем cookies
+                const setCookie = res.headers['set-cookie'];
+                if (setCookie) {
+                    this.cookies.push(...setCookie.map(cookie => cookie.split(';')[0]));
+                }
+                let data = '';
+                res.on('data', (chunk) => {
+                    data += chunk;
+                });
+                res.on('end', () => {
+                    if (method === 'GET') {
+                        resolve(res.statusCode || 500);
+                    }
+                    else {
+                        resolve(data);
+                    }
+                });
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new WshcmException(`Request timed out after ${this.requestTimeout}ms: ${method} ${path}`));
+            });
+            req.on('error', (error) => {
+                reject(new WshcmException(`Request failed: ${error.message}`));
+            });
+            if (body) {
+                req.write(body);
+            }
+            req.end();
+        });
+    }
+}

package/build/evaluator.d.ts

@@ -0,0 +1,51 @@
+import { WshcmClient } from './client.js';
+/**
+ * Evaluator для выполнения произвольного BorisScript-кода на сервере
+ *
+ * Создает временный модуль на сервере с функциями execute и drop_self,
+ * позволяя выполнять динамический код через eval.
+ *
+ * @example
+ * ```typescript
+ * const evaluator = client.evaluator;
+ * await evaluator.initialize();
+ * const result = await evaluator.eval('return 2 + 2;');
+ * await evaluator.close();
+ * ```
+ */
+export declare class Evaluator {
+    private client;
+    private evalKey;
+    private libUrl;
+    private initialized;
+    /**
+     * Создает новый evaluator
+     * @param client - экземпляр WshcmClient
+     */
+    constructor(client: WshcmClient);
+    /**
+     * Инициализирует evaluator, создавая временный модуль на сервере
+     */
+    initialize(): Promise<void>;
+    /**
+     * Выполняет произвольный BorisScript-код на сервере
+     * @param code - код для выполнения
+     * @returns результат выполнения
+     */
+    eval(code: string): Promise<any>;
+    evalCode(code: string): Promise<any>;
+    evalExpr(expr: string): Promise<any>;
+    /**
+     * Закрывает evaluator и удаляет временный модуль с сервера
+     * @returns true если удаление успешно, false в противном случае
+     */
+    close(): Promise<boolean>;
+    /**
+     * Генерирует случайную строку заданной длины
+     */
+    private generateRandomString;
+    /**
+     * Возвращает содержимое временного модуля unsafe_eval.bs
+     */
+    private getUnsafeEvalScript;
+}

package/build/evaluator.js

@@ -0,0 +1,107 @@
+/**
+ * Evaluator для выполнения произвольного BorisScript-кода на сервере
+ *
+ * Создает временный модуль на сервере с функциями execute и drop_self,
+ * позволяя выполнять динамический код через eval.
+ *
+ * @example
+ * ```typescript
+ * const evaluator = client.evaluator;
+ * await evaluator.initialize();
+ * const result = await evaluator.eval('return 2 + 2;');
+ * await evaluator.close();
+ * ```
+ */
+export class Evaluator {
+    client;
+    evalKey;
+    libUrl;
+    initialized = false;
+    /**
+     * Создает новый evaluator
+     * @param client - экземпляр WshcmClient
+     */
+    constructor(client) {
+        this.client = client;
+        this.evalKey = 'unsafe_eval_' + this.generateRandomString(32);
+        this.libUrl = `x-local://wt/${this.evalKey}.bs`;
+    }
+    /**
+     * Инициализирует evaluator, создавая временный модуль на сервере
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        const content = this.getUnsafeEvalScript();
+        await this.client.callMethod('tools', 'put_url_text_server', [this.libUrl, content]);
+        this.initialized = true;
+    }
+    /**
+     * Выполняет произвольный BorisScript-код на сервере
+     * @param code - код для выполнения
+     * @returns результат выполнения
+     */
+    async eval(code) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        return this.client.callMethod(this.libUrl, 'execute', [code]);
+    }
+    async evalCode(code) {
+        // Оборачиваем код в функцию, чтобы явно не возвращать никакого результата всего сегмента кода, даже если в коде есть return
+        const randomFuncName = '__evaluator_wrapper_' + this.generateRandomString(32);
+        const wrappedCode = `function ${randomFuncName}() {\n${code}\n}\n${randomFuncName}();return;`;
+        return this.eval(wrappedCode);
+    }
+    async evalExpr(expr) {
+        return this.eval(expr);
+    }
+    /**
+     * Закрывает evaluator и удаляет временный модуль с сервера
+     * @returns true если удаление успешно, false в противном случае
+     */
+    async close() {
+        if (!this.initialized) {
+            return false;
+        }
+        try {
+            const result = await this.client.callMethod(this.libUrl, 'drop_self', []);
+            this.initialized = false;
+            return result;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Генерирует случайную строку заданной длины
+     */
+    generateRandomString(length) {
+        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+        let result = '';
+        for (let i = 0; i < length; i++) {
+            result += chars.charAt(Math.floor(Math.random() * chars.length));
+        }
+        return result;
+    }
+    /**
+     * Возвращает содержимое временного модуля unsafe_eval.bs
+     */
+    getUnsafeEvalScript() {
+        return `"META:ALLOW-CALL-FROM-CLIENT:1"
+function execute(code) {
+    return eval(code);
+}
+
+"META:ALLOW-CALL-FROM-CLIENT:1"
+function drop_self() {
+    try {
+        DeleteFile("${this.libUrl}");
+        return true;
+    } catch (err) {
+        return false;
+    }
+}`;
+    }
+}

package/build/exceptions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Базовое исключение для WSHCM-клиента
+ */
+export declare class WshcmException extends Error {
+    constructor(message: string);
+}
+/**
+ * Исключение при ошибке авторизации
+ */
+export declare class UnauthorizedError extends WshcmException {
+    constructor(message?: string);
+}

package/build/exceptions.js

@@ -0,0 +1,20 @@
+/**
+ * Базовое исключение для WSHCM-клиента
+ */
+export class WshcmException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WshcmException';
+        Object.setPrototypeOf(this, WshcmException.prototype);
+    }
+}
+/**
+ * Исключение при ошибке авторизации
+ */
+export class UnauthorizedError extends WshcmException {
+    constructor(message = 'Unauthorized') {
+        super(message);
+        this.name = 'UnauthorizedError';
+        Object.setPrototypeOf(this, UnauthorizedError.prototype);
+    }
+}

package/build/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * WSHCM Client - клиент для работы с WebSoft HCM через SP-XML API
+ *
+ * @module wshcm
+ */
+export { WshcmClient } from './client.js';
+export { Evaluator } from './evaluator.js';
+export { WshcmException, UnauthorizedError } from './exceptions.js';
+export { renderRequest, parseResponse } from './soap-utils.js';
+export { WshcmUploader } from './uploader.js';
+export type { WshcmClientOptions } from './types.js';
+export type { WshcmUploaderOptions, UploadProgressCallback } from './uploader.js';

package/build/index.js

@@ -0,0 +1,10 @@
+/**
+ * WSHCM Client - клиент для работы с WebSoft HCM через SP-XML API
+ *
+ * @module wshcm
+ */
+export { WshcmClient } from './client.js';
+export { Evaluator } from './evaluator.js';
+export { WshcmException, UnauthorizedError } from './exceptions.js';
+export { renderRequest, parseResponse } from './soap-utils.js';
+export { WshcmUploader } from './uploader.js';

package/build/soap-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Рендерит SOAP-запрос для вызова метода
+ * @param lib - библиотека/модуль
+ * @param method - имя метода
+ * @param methodArgs - аргументы метода
+ * @returns XML-строка SOAP-запроса
+ */
+export declare function renderRequest(lib: string, method: string, methodArgs: any[]): string;
+/**
+ * Парсит SOAP-ответ и извлекает результат.
+ *
+ * Использует `fast-xml-parser` с `removeNSPrefix: true` для прозрачной
+ * работы с namespace-префиксами (soap:Envelope → Envelope и т.д.).
+ *
+ * @param responseText - XML-строка ответа
+ * @returns результат выполнения метода
+ */
+export declare function parseResponse(responseText: string): any;

package/build/soap-utils.js

@@ -0,0 +1,224 @@
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+import { WshcmException } from './exceptions.js';
+// ============================================================================
+// XML Parser / Builder instances
+// ============================================================================
+/**
+ * XMLParser для SOAP-ответов.
+ * `removeNSPrefix: true` убирает namespace-префиксы (soap:Envelope → Envelope),
+ * что позволяет обращаться к элементам напрямую без привязки к префиксам сервера.
+ */
+const soapParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    removeNSPrefix: true,
+    trimValues: true,
+});
+/**
+ * XMLBuilder для формирования SOAP-запросов.
+ * Автоматически экранирует XML-сущности в значениях и атрибутах.
+ */
+const soapBuilder = new XMLBuilder({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    format: true,
+    indentBy: '    ',
+    suppressEmptyNode: false,
+    processEntities: true,
+});
+// ============================================================================
+// Request Building
+// ============================================================================
+/**
+ * Преобразует аргумент метода в объект для XMLBuilder
+ * @param arg - значение аргумента
+ * @returns объект с VALUE-TYPE атрибутом и текстовым содержимым
+ */
+function buildArgumentValue(arg) {
+    if (typeof arg === 'string') {
+        return {
+            '@_VALUE-TYPE': 'string',
+            '#text': arg
+        };
+    }
+    if (typeof arg === 'number') {
+        return {
+            '@_VALUE-TYPE': Number.isInteger(arg) ? 'integer' : 'real',
+            '#text': arg,
+        };
+    }
+    if (typeof arg === 'boolean') {
+        return {
+            '@_VALUE-TYPE': 'bool',
+            '#text': arg ? 1 : 0
+        };
+    }
+    if (arg === null || arg === undefined) {
+        return { '@_VALUE-TYPE': 'string', '#text': '' };
+    }
+    // Для объектов и массивов — неподдерживаемый тип, используем JSON как строку
+    try {
+        return { '@_VALUE-TYPE': 'string', '#text': JSON.stringify(arg) };
+    }
+    catch {
+        throw new WshcmException('Unsupported argument type');
+    }
+}
+/**
+ * Рендерит SOAP-запрос для вызова метода
+ * @param lib - библиотека/модуль
+ * @param method - имя метода
+ * @param methodArgs - аргументы метода
+ * @returns XML-строка SOAP-запроса
+ */
+export function renderRequest(lib, method, methodArgs) {
+    const argData = {};
+    for (let i = 0; i < methodArgs.length; i++) {
+        argData[`arg-${i}`] = buildArgumentValue(methodArgs[i]);
+    }
+    const requestObj = {
+        '?xml': { '@_version': '1.0', '@_encoding': 'utf-8' },
+        'soap:Envelope': {
+            '@_xmlns:soap': 'http://schemas.xmlsoap.org/soap/envelope/',
+            '@_xmlns': 'http://www.datex-soft.com/soap/',
+            'soap:Body': {
+                'CallMethod': {
+                    'LibName': lib,
+                    'MethodName': method,
+                    'ArgData': argData,
+                },
+            },
+        },
+    };
+    return soapBuilder.build(requestObj);
+}
+// ============================================================================
+// Response Parsing
+// ============================================================================
+/**
+ * Рекурсивно ищет элемент по имени в распарсенном XML-объекте.
+ * Аналог SimpleXmlParser.findElement — ищет ключ на любом уровне вложенности.
+ *
+ * @param obj - распарсенный XML-объект
+ * @param key - имя искомого элемента
+ * @returns найденный элемент или undefined
+ */
+function findElement(obj, key) {
+    if (!obj || typeof obj !== 'object')
+        return undefined;
+    const record = obj;
+    if (key in record)
+        return record[key];
+    for (const val of Object.values(record)) {
+        const found = findElement(val, key);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Парсит значение элемента на основе VALUE-TYPE атрибута.
+ *
+ * fast-xml-parser представляет элемент с атрибутами как объект:
+ * - `@_VALUE-TYPE` — тип значения
+ * - `#text` — текстовое содержимое (может отсутствовать для пустых элементов)
+ * - остальные ключи — дочерние элементы (для Object/Array типов)
+ *
+ * @param element - распарсенный XML-элемент
+ * @returns JS-значение соответствующего типа
+ */
+function parseResultValue(element) {
+    if (element === undefined || element === null)
+        return undefined;
+    // Если элемент — примитив (нет атрибутов), вернуть как есть
+    if (typeof element !== 'object')
+        return element;
+    const valueType = element['@_VALUE-TYPE'];
+    if (!valueType || valueType === 'undefined' || valueType === 'null') {
+        return undefined;
+    }
+    if (valueType === 'string') {
+        const text = element['#text'];
+        return text != null ? String(text) : '';
+    }
+    if (valueType === 'integer') {
+        return parseInt(String(element['#text'] ?? '0'), 10);
+    }
+    if (valueType === 'real') {
+        return parseFloat(String(element['#text'] ?? '0'));
+    }
+    if (valueType === 'bool') {
+        return (element['#text'] ?? 0) == 1;
+    }
+    if (valueType === 'Object') {
+        return parseResultObject(element);
+    }
+    if (valueType === 'Array') {
+        return parseResultArray(element);
+    }
+    throw new WshcmException(`Unexpected VALUE-TYPE: ${valueType}`);
+}
+/**
+ * Парсит объект из распарсенного XML-элемента.
+ * Итерирует дочерние ключи (исключая `@_*` атрибуты и `#text`),
+ * рекурсивно разбирая каждый через {@link parseResultValue}.
+ *
+ * @param element - элемент с `@_VALUE-TYPE="Object"`
+ * @returns JS-объект
+ */
+function parseResultObject(element) {
+    const result = {};
+    for (const [key, value] of Object.entries(element)) {
+        if (key.startsWith('@_') || key === '#text')
+            continue;
+        result[key] = parseResultValue(value);
+    }
+    return result;
+}
+/**
+ * Парсит массив из распарсенного XML-элемента.
+ * Итерирует дочерние ключи (исключая `@_*` атрибуты и `#text`),
+ * рекурсивно разбирая каждый через {@link parseResultValue}.
+ *
+ * @param element - элемент с `@_VALUE-TYPE="Array"`
+ * @returns JS-массив
+ */
+function parseResultArray(element) {
+    const result = [];
+    for (const [key, value] of Object.entries(element)) {
+        if (key.startsWith('@_') || key === '#text')
+            continue;
+        result.push(parseResultValue(value));
+    }
+    return result;
+}
+/**
+ * Парсит SOAP-ответ и извлекает результат.
+ *
+ * Использует `fast-xml-parser` с `removeNSPrefix: true` для прозрачной
+ * работы с namespace-префиксами (soap:Envelope → Envelope и т.д.).
+ *
+ * @param responseText - XML-строка ответа
+ * @returns результат выполнения метода
+ */
+export function parseResponse(responseText) {
+    const parsed = soapParser.parse(responseText);
+    // Проверяем на ошибку SOAP Fault
+    const fault = findElement(parsed, 'Fault');
+    if (fault && typeof fault === 'object') {
+        const errorCode = fault.faultcode ?? 'UNKNOWN';
+        const errorMessage = fault.faultstring ?? 'Unknown error';
+        throw new WshcmException(`ERR: (${errorCode}) ${errorMessage}`);
+    }
+    // Ищем ResultData
+    const resultData = findElement(parsed, 'ResultData');
+    if (!resultData) {
+        return undefined;
+    }
+    // Ищем Result внутри ResultData
+    const result = typeof resultData === 'object' ? resultData.Result : undefined;
+    if (result === undefined) {
+        throw new WshcmException('Unexpected response: Result element not found');
+    }
+    return parseResultValue(result);
+}

package/build/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Опции для создания WSHCM-клиента
+ */
+export interface WshcmClientOptions {
+    /** Использовать HTTPS вместо HTTP */
+    overHttps: boolean;
+    /** Хост сервера (например, "localhost") */
+    host: string;
+    /** Порт сервера (например, 80, 8080 или "8080") */
+    port: number | string;
+    /** Имя пользователя */
+    username: string;
+    /** Пароль */
+    password: string;
+    /** Таймаут HTTP-запросов в мс (по умолчанию 30000) */
+    requestTimeout?: number;
+}

package/build/types.js

@@ -0,0 +1 @@
+export {};

package/build/uploader.d.ts

@@ -0,0 +1,111 @@
+import { Evaluator } from './evaluator.js';
+/**
+ * Callback для отслеживания прогресса загрузки
+ * @param uploadedBytes - количество загруженных байт
+ * @param totalBytes - общий размер всех файлов
+ */
+export type UploadProgressCallback = (uploadedBytes: number, totalBytes: number) => void;
+/**
+ * Опции для создания загрузчика
+ */
+export interface WshcmUploaderOptions {
+    /** Evaluator для выполнения кода на сервере (lifecycle управляется снаружи) */
+    evaluator: Evaluator;
+    /** Путь к загружаемому файлу или директории */
+    path: string;
+    /** Путь назначения на сервере */
+    destination: string;
+    /** Размер чанка в байтах (по умолчанию 4MB) */
+    chunkSize?: number;
+}
+/**
+ * Загрузчик файлов для WSHCM
+ *
+ * Позволяет загружать файлы и директории на сервер WebSoft HCM
+ * с разбиением на чанки и последующей сборкой на сервере.
+ *
+ * @example
+ * ```typescript
+ * const evaluator = client.createEvaluator();
+ * await evaluator.initialize();
+ *
+ * const uploader = new WshcmUploader({
+ *   evaluator,
+ *   path: './myfile.txt',
+ *   destination: 'x-local://wt/uploaded/',
+ *   chunkSize: 4 * 1024 * 1024 // 4MB
+ * });
+ *
+ * await uploader.prepare();
+ * await uploader.upload((uploaded, total) => {
+ *   console.log(`Progress: ${(uploaded / total * 100).toFixed(2)}%`);
+ * });
+ * const urls = await uploader.finish();
+ *
+ * await evaluator.close();
+ * ```
+ */
+export declare class WshcmUploader {
+    private evaluator;
+    private chunkSize;
+    private uploadPath;
+    private destination;
+    private isDir;
+    private isFile;
+    private isGlob;
+    private totalSize;
+    /** Базовый путь для вычисления relative paths */
+    private basePath;
+    /** Имя для finish скрипта (пустое для glob режима) */
+    private uploadName;
+    private files;
+    private destPath;
+    private tempPath;
+    private chunkPath1;
+    private chunkPath2;
+    /**
+     * Создает новый загрузчик файлов
+     *
+     * Lifecycle evaluator-а управляется вызывающим кодом —
+     * uploader не вызывает evaluator.close().
+     */
+    constructor(options: WshcmUploaderOptions);
+    /**
+     * Подготавливает загрузку: сканирует файлы, создает структуру на сервере
+     *
+     * Поддерживаемые форматы path:
+     * - `file.txt` — загрузка одного файла
+     * - `dir/` — загрузка директории (как вложенная папка)
+     * - `dir/*` — загрузка содержимого директории (без вложенной папки)
+     */
+    prepare(): Promise<void>;
+    /**
+     * Загружает файлы на сервер по частям (чанкам)
+     * Мелкие чанки группируются в батчи для оптимизации
+     * @param callback - функция для отслеживания прогресса
+     */
+    upload(callback?: UploadProgressCallback): Promise<void>;
+    /**
+     * Финализирует загрузку: собирает чанки и перемещает файлы в целевую директорию
+     * @returns массив URL загруженных файлов
+     */
+    finish(): Promise<string[]>;
+    /**
+     * Сканирует директорию рекурсивно и добавляет файлы в список
+     */
+    private scanDirectory;
+    /**
+     * Разбивает файл на чанки
+     */
+    private chunksFromFile;
+    /**
+     * Группирует чанки в батчи для оптимизации загрузки
+     * Суммарный размер данных в батче не превышает chunkSize
+     */
+    private batchChunks;
+    /**
+     * Загружает батч чанков одним запросом
+     * @returns размер загруженных данных в байтах
+     */
+    private uploadBatch;
+}

package/build/uploader.js

@@ -0,0 +1,283 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+/**
+ * Описание файла для загрузки
+ */
+class FileDescription {
+    /** Абсолютный путь к файлу */
+    path;
+    /** Относительный путь от базовой директории */
+    relative;
+    /** MD5 хеш относительного пути (в верхнем регистре) */
+    hash;
+    /** Размер файла в байтах */
+    size;
+    constructor(filePath, basePath) {
+        this.path = filePath;
+        this.relative = path.relative(basePath, filePath).replace(/\\/g, '/');
+        this.hash = crypto.createHash('md5').update(this.relative).digest('hex').toUpperCase();
+        this.size = fs.statSync(filePath).size;
+    }
+}
+/**
+ * Информация о чанке файла
+ */
+class ChunkInfo {
+    /** Путь к файлу */
+    path;
+    /** Начало чанка в файле (байты) */
+    chunkStart;
+    /** Конец чанка в файле (байты) */
+    chunkEnd;
+    /** Хеш файла */
+    hash;
+    /** Индекс чанка */
+    index;
+    constructor(filePath, chunkStart, chunkEnd, hash, index) {
+        this.path = filePath;
+        this.chunkStart = chunkStart;
+        this.chunkEnd = chunkEnd;
+        this.hash = hash;
+        this.index = index;
+    }
+    toString() {
+        return `[ ${this.hash} : '${this.path}' : (${this.index}) ${this.chunkStart}-${this.chunkEnd} ]`;
+    }
+}
+/**
+ * Загрузчик файлов для WSHCM
+ *
+ * Позволяет загружать файлы и директории на сервер WebSoft HCM
+ * с разбиением на чанки и последующей сборкой на сервере.
+ *
+ * @example
+ * ```typescript
+ * const evaluator = client.createEvaluator();
+ * await evaluator.initialize();
+ *
+ * const uploader = new WshcmUploader({
+ *   evaluator,
+ *   path: './myfile.txt',
+ *   destination: 'x-local://wt/uploaded/',
+ *   chunkSize: 4 * 1024 * 1024 // 4MB
+ * });
+ *
+ * await uploader.prepare();
+ * await uploader.upload((uploaded, total) => {
+ *   console.log(`Progress: ${(uploaded / total * 100).toFixed(2)}%`);
+ * });
+ * const urls = await uploader.finish();
+ *
+ * await evaluator.close();
+ * ```
+ */
+export class WshcmUploader {
+    evaluator;
+    chunkSize;
+    uploadPath;
+    destination;
+    isDir = false;
+    isFile = false;
+    isGlob = false;
+    totalSize = 0;
+    /** Базовый путь для вычисления relative paths */
+    basePath = '';
+    /** Имя для finish скрипта (пустое для glob режима) */
+    uploadName = '';
+    files = [];
+    // Пути на сервере
+    destPath = '';
+    tempPath = '';
+    chunkPath1 = '';
+    chunkPath2 = '';
+    /**
+     * Создает новый загрузчик файлов
+     *
+     * Lifecycle evaluator-а управляется вызывающим кодом —
+     * uploader не вызывает evaluator.close().
+     */
+    constructor(options) {
+        this.evaluator = options.evaluator;
+        this.uploadPath = options.path;
+        this.destination = options.destination;
+        this.chunkSize = options.chunkSize || 4 * 1024 * 1024; // 4MB по умолчанию
+    }
+    /**
+     * Подготавливает загрузку: сканирует файлы, создает структуру на сервере
+     *
+     * Поддерживаемые форматы path:
+     * - `file.txt` — загрузка одного файла
+     * - `dir/` — загрузка директории (как вложенная папка)
+     * - `dir/*` — загрузка содержимого директории (без вложенной папки)
+     */
+    async prepare() {
+        // Проверяем glob-паттерн (dir/* или dir\*)
+        if (this.uploadPath.endsWith('/*') || this.uploadPath.endsWith('\\*')) {
+            this.isGlob = true;
+            const dirPath = this.uploadPath.slice(0, -2);
+            if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+                throw new Error(`Glob pattern requires existing directory: ${dirPath}`);
+            }
+            this.basePath = dirPath;
+            this.uploadName = ''; // пустое имя сигнализирует glob-режим на сервере
+            this.scanDirectory(dirPath, dirPath);
+        }
+        else {
+            // Обычный режим: файл или директория
+            const stats = fs.statSync(this.uploadPath);
+            if (stats.isDirectory()) {
+                this.isDir = true;
+                this.basePath = path.dirname(this.uploadPath);
+                this.uploadName = path.basename(this.uploadPath);
+                this.scanDirectory(this.uploadPath, this.basePath);
+            }
+            else if (stats.isFile()) {
+                this.isFile = true;
+                this.basePath = path.dirname(this.uploadPath);
+                this.uploadName = path.basename(this.uploadPath);
+                const fileDesc = new FileDescription(this.uploadPath, this.basePath);
+                this.files.push(fileDesc);
+            }
+            else {
+                throw new Error('Path is not a file or directory');
+            }
+        }
+        // Сортируем файлы по размеру (от меньших к большим) для эффективного батчинга
+        this.files.sort((a, b) => a.size - b.size);
+        // Вычисляем общий размер
+        this.totalSize = this.files.reduce((sum, file) => sum + file.size, 0);
+        // Читаем скрипт подготовки
+        const prepareScript = fs.readFileSync(path.join(import.meta.dirname, '..', 'resources', 'upload_prepare.bs'), 'utf-8');
+        // Заменяем переменную
+        const script = prepareScript.replace('{{destination}}', this.destination);
+        // Выполняем на сервере
+        const response = await this.evaluator.eval(script);
+        // Сохраняем пути
+        this.destPath = response.dest_path.replace(/\\/g, '\\\\');
+        this.tempPath = response.temp_path.replace(/\\/g, '\\\\');
+        const [part1, part2] = response.chunk_path.split('RELATIVE_PATH_HASH');
+        this.chunkPath1 = part1.replace(/\\/g, '\\\\');
+        this.chunkPath2 = part2.replace(/\\/g, '\\\\');
+        // Создаем директории для чанков на сервере
+        const obtainDirCode = this.files
+            .map(file => `ObtainDirectory('${this.chunkPath1}${file.hash}', true);`)
+            .join('\n');
+        await this.evaluator.eval(obtainDirCode);
+    }
+    /**
+     * Загружает файлы на сервер по частям (чанкам)
+     * Мелкие чанки группируются в батчи для оптимизации
+     * @param callback - функция для отслеживания прогресса
+     */
+    async upload(callback) {
+        const chunks = [];
+        // Создаем список всех чанков (файлы уже отсортированы по размеру)
+        for (const file of this.files) {
+            this.chunksFromFile(file, chunks);
+        }
+        // Группируем чанки в батчи
+        const batches = this.batchChunks(chunks);
+        let uploadedBytes = 0;
+        // Загружаем батчи
+        for (const batch of batches) {
+            uploadedBytes += await this.uploadBatch(batch);
+            if (callback) {
+                callback(uploadedBytes, this.totalSize);
+            }
+        }
+    }
+    /**
+     * Финализирует загрузку: собирает чанки и перемещает файлы в целевую директорию
+     * @returns массив URL загруженных файлов
+     */
+    async finish() {
+        // Читаем скрипт финализации
+        const finishScript = fs.readFileSync(path.join(import.meta.dirname, '..', 'resources', 'upload_finish.bs'), 'utf-8');
+        // Заменяем переменные
+        const filePaths = JSON.stringify(this.files.map(f => f.relative));
+        let script = finishScript;
+        script = script.replace('{{file_name}}', this.uploadName);
+        script = script.replace('{{dest_path}}', this.destPath);
+        script = script.replace('{{temp_path}}', this.tempPath);
+        script = script.replace('{{file_paths}}', filePaths);
+        // Выполняем на сервере
+        const response = await this.evaluator.eval(script);
+        if (response.error) {
+            throw new Error(response.message || 'Upload finish failed');
+        }
+        return response.value || [];
+    }
+    /**
+     * Сканирует директорию рекурсивно и добавляет файлы в список
+     */
+    scanDirectory(dirPath, basePath) {
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                this.scanDirectory(fullPath, basePath);
+            }
+            else if (entry.isFile()) {
+                const fileDesc = new FileDescription(fullPath, basePath);
+                this.files.push(fileDesc);
+            }
+        }
+    }
+    /**
+     * Разбивает файл на чанки
+     */
+    chunksFromFile(file, chunks) {
+        let index = 0;
+        for (let start = 0; start < file.size; start += this.chunkSize) {
+            const end = Math.min(start + this.chunkSize, file.size);
+            chunks.push(new ChunkInfo(file.path, start, end, file.hash, index));
+            index++;
+        }
+    }
+    /**
+     * Группирует чанки в батчи для оптимизации загрузки
+     * Суммарный размер данных в батче не превышает chunkSize
+     */
+    batchChunks(chunks) {
+        const batches = [];
+        let currentBatch = [];
+        let currentSize = 0;
+        for (const chunk of chunks) {
+            const chunkSize = chunk.chunkEnd - chunk.chunkStart;
+            // Если батч переполнится — закрываем его
+            if (currentSize + chunkSize > this.chunkSize && currentBatch.length > 0) {
+                batches.push(currentBatch);
+                currentBatch = [];
+                currentSize = 0;
+            }
+            currentBatch.push(chunk);
+            currentSize += chunkSize;
+        }
+        if (currentBatch.length > 0) {
+            batches.push(currentBatch);
+        }
+        return batches;
+    }
+    /**
+     * Загружает батч чанков одним запросом
+     * @returns размер загруженных данных в байтах
+     */
+    async uploadBatch(batch) {
+        const statements = [];
+        let totalSize = 0;
+        for (const chunk of batch) {
+            const size = chunk.chunkEnd - chunk.chunkStart;
+            const buffer = Buffer.alloc(size);
+            const fd = await fs.promises.open(chunk.path, 'r');
+            await fd.read(buffer, 0, size, chunk.chunkStart);
+            await fd.close();
+            const encoded = buffer.toString('base64');
+            const serverPath = `${this.chunkPath1}${chunk.hash}${this.chunkPath2}_${chunk.index}`;
+            statements.push(`PutFileData('${serverPath}', Base64Decode('${encoded}'))`);
+            totalSize += size;
+        }
+        await this.evaluator.eval(statements.join('\n'));
+        return totalSize;
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@boristype/ws-client",
+  "version": "0.1.0-alpha.0",
+  "description": "WSHCM SOAP client — клиент для работы с WebSoft HCM через SP-XML API",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "dependencies": {
+    "fast-xml-parser": "^5.3.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "wshcm",
+    "soap",
+    "websoft",
+    "hcm"
+  ],
+  "author": "BorisType Project",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BorisType/BorisType.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BorisType/BorisType/issues"
+  },
+  "homepage": "https://github.com/BorisType/BorisType#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}