hlquery-node-client 1.0.4 → 1.0.6

package/lib/Request.js

@@ -16,11 +16,26 @@ const Response = require('./Response');
  * HTTP request handler
  */
 class Request {
-    constructor(baseUrl, timeout = 30000, authToken = null, authMethod = 'bearer') {
-        this.baseUrl = baseUrl.replace(/\/$/, '');
+    constructor(baseUrl, timeout = 30000, authToken = null, authMethod = 'bearer', options = {}) {
+        if (timeout && typeof timeout === 'object') {
+            options = timeout;
+            timeout = options.timeout || 30000;
+            authToken = options.token || null;
+            authMethod = options.auth_method || options.authMethod || 'bearer';
+        }
+
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
         this.timeout = timeout;
         this.authToken = authToken;
         this.authMethod = authMethod;
+        this.agent = options.agent || null;
+        this.httpAgent = options.http_agent || options.httpAgent || null;
+        this.httpsAgent = options.https_agent || options.httpsAgent || null;
+        this.defaultHeaders = options.headers || {};
+        this.maxResponseBytes = options.max_response_bytes || options.maxResponseBytes || 0;
+        this.throwOnError = Boolean(options.throw_on_error || options.throwOnError);
+        this.queryArrayFormat = options.query_array_format || options.queryArrayFormat || 'comma';
+        this.signal = options.signal || null;
     }
     
     setAuthToken(token, method = 'bearer') {
@@ -42,8 +57,21 @@ class Request {
      * @returns {Promise<Response>}
      * @throws {RequestException}
      */
-    async execute(method, path, body = null, queryParams = {}) {
-        const url = new URL(this.baseUrl + path);
+    async execute(method, path, body = null, queryParams = {}, requestOptions = {}) {
+        const url = new URL(path, `${this.baseUrl}/`);
+        const signal = requestOptions.signal || this.signal;
+        const maxResponseBytes = requestOptions.max_response_bytes || requestOptions.maxResponseBytes || this.maxResponseBytes;
+        const throwOnError = requestOptions.throw_on_error !== undefined
+            ? requestOptions.throw_on_error
+            : (requestOptions.throwOnError !== undefined ? requestOptions.throwOnError : this.throwOnError);
+        const queryArrayFormat = requestOptions.query_array_format || requestOptions.queryArrayFormat || this.queryArrayFormat;
+
+        if (signal && signal.aborted) {
+            throw new RequestException('Request aborted', 0, null, {
+                code: 'ABORT_ERR',
+                retryable: false
+            });
+        }
         
         // Add query parameters
         Object.keys(queryParams).forEach(key => {
@@ -53,7 +81,11 @@ class Request {
             }
 
             if (Array.isArray(value)) {
-                url.searchParams.append(key, value.join(','));
+                if (queryArrayFormat === 'repeat' || queryArrayFormat === 'repeated') {
+                    value.forEach(item => url.searchParams.append(key, item));
+                } else {
+                    url.searchParams.append(key, value.join(','));
+                }
                 return;
             }
 
@@ -66,7 +98,9 @@ class Request {
         });
         
         const headers = {
-            'Accept': 'application/json'
+            'Accept': 'application/json',
+            ...this.defaultHeaders,
+            ...(requestOptions.headers || {})
         };
         
         // Prepare body string if present
@@ -89,32 +123,112 @@ class Request {
         const options = {
             method: method,
             headers: headers,
-            timeout: this.timeout
+            timeout: requestOptions.timeout || this.timeout
         };
         
         const client = url.protocol === 'https:' ? https : http;
+        const agent = this.agent || (url.protocol === 'https:' ? this.httpsAgent : this.httpAgent);
+        if (agent) {
+            options.agent = agent;
+        }
         
         return new Promise((resolve, reject) => {
-            const req = client.request(url, options, (res) => {
+            let settled = false;
+            let req = null;
+            const rejectOnce = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (signal && abortHandler && typeof signal.removeEventListener === 'function') {
+                    signal.removeEventListener('abort', abortHandler);
+                } else if (signal && abortHandler && typeof signal.removeListener === 'function') {
+                    signal.removeListener('abort', abortHandler);
+                }
+                reject(error);
+            };
+            const resolveOnce = (response) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (signal && abortHandler && typeof signal.removeEventListener === 'function') {
+                    signal.removeEventListener('abort', abortHandler);
+                } else if (signal && abortHandler && typeof signal.removeListener === 'function') {
+                    signal.removeListener('abort', abortHandler);
+                }
+                resolve(response);
+            };
+            const abortHandler = () => {
+                if (req) {
+                    req.destroy();
+                }
+                rejectOnce(new RequestException('Request aborted', 0, null, {
+                    code: 'ABORT_ERR',
+                    retryable: false
+                }));
+            };
+
+            if (signal && typeof signal.addEventListener === 'function') {
+                signal.addEventListener('abort', abortHandler, { once: true });
+            } else if (signal && typeof signal.once === 'function') {
+                signal.once('abort', abortHandler);
+            }
+
+            req = client.request(url, options, (res) => {
                 const responseHeaders = {};
                 Object.keys(res.headers).forEach(key => {
                     responseHeaders[key.toLowerCase()] = res.headers[key];
                 });
                 
-                let data = '';
+                const chunks = [];
+                let receivedBytes = 0;
                 
                 res.on('data', (chunk) => {
-                    data += chunk;
+                    receivedBytes += chunk.length;
+                    if (maxResponseBytes > 0 && receivedBytes > maxResponseBytes) {
+                        res.destroy();
+                        rejectOnce(new RequestException(
+                            `Response exceeded maximum size of ${maxResponseBytes} bytes`,
+                            res.statusCode,
+                            null,
+                            {
+                                headers: responseHeaders,
+                                retryable: false,
+                                code: 'MAX_RESPONSE_BYTES'
+                            }
+                        ));
+                        return;
+                    }
+                    chunks.push(chunk);
                 });
                 
                 res.on('end', () => {
+                    if (settled) {
+                        return;
+                    }
+                    const rawBuffer = Buffer.concat(chunks);
+                    const data = rawBuffer.toString('utf8');
                     let decoded;
+                    let parsed = true;
                     try {
                         decoded = data ? JSON.parse(data) : null;
                     } catch (e) {
                         // If JSON parsing fails, return raw response
                         decoded = data;
+                        parsed = false;
                     }
+
+                    const response = new Response(res.statusCode, decoded, responseHeaders, {
+                        statusMessage: res.statusMessage || '',
+                        rawBody: rawBuffer,
+                        parsed: parsed,
+                        request: {
+                            method: method,
+                            url: url.toString(),
+                            path: path
+                        }
+                    });
                     
                     // Check for demo mode errors
                     if (res.statusCode === 403 && decoded && typeof decoded === 'object') {
@@ -122,30 +236,51 @@ class Request {
                         if (errorMsg.includes('Demo mode is enabled') || 
                             errorMsg.includes('Operation not allowed') ||
                             errorMsg.includes('Write operations are not allowed')) {
-                            return reject(new DemoModeException(
+                            return rejectOnce(new DemoModeException(
                                 `Demo mode is enabled on the server. Write operations are blocked. Only search and read operations are permitted. Server message: ${decoded.message || decoded.error}`
                             ));
                         }
                         // Check if server rejected token because auth is disabled
                         if (errorMsg.includes('Authentication is disabled') || 
                             errorMsg.includes('Tokens are not accepted when authentication is disabled')) {
-                            return reject(new AuthenticationException(
+                            return rejectOnce(new AuthenticationException(
                                 `Authentication is disabled on the server. Remove the token from your client configuration. Server message: ${decoded.message || decoded.error}`
                             ));
                         }
                     }
+
+                    if (throwOnError && response.isError()) {
+                        const errorMessage = response.getError() ||
+                            `${res.statusCode} ${res.statusMessage || 'HTTP error'}`;
+                        return rejectOnce(new RequestException(errorMessage, res.statusCode, decoded, {
+                            response: response,
+                            headers: responseHeaders,
+                            rawBody: rawBuffer,
+                            retryable: res.statusCode >= 500
+                        }));
+                    }
                     
-                    resolve(new Response(res.statusCode, decoded, responseHeaders));
+                    resolveOnce(response);
                 });
             });
             
             req.on('error', (error) => {
-                reject(new RequestException(`Request failed: ${error.message}`, 0));
+                if (settled) {
+                    return;
+                }
+                rejectOnce(new RequestException(`Request failed: ${error.message}`, 0, null, {
+                    cause: error,
+                    retryable: true,
+                    code: error.code || null
+                }));
             });
             
             req.on('timeout', () => {
                 req.destroy();
-                reject(new RequestException('Request timeout', 0));
+                rejectOnce(new RequestException('Request timeout', 0, null, {
+                    retryable: true,
+                    code: 'ETIMEDOUT'
+                }));
             });
             
             if (bodyStr !== null) {

package/lib/Response.js

@@ -10,10 +10,15 @@
  * Response wrapper for API responses
  */
 class Response {
-    constructor(statusCode, body, headers = {}) {
+    constructor(statusCode, body, headers = {}, options = {}) {
         this.statusCode = statusCode;
         this.body = body;
         this.headers = headers;
+        this.statusMessage = options.statusMessage || '';
+        this.rawBody = options.rawBody || null;
+        this.request = options.request || null;
+        this.contentType = headers['content-type'] || headers['Content-Type'] || null;
+        this.parsed = options.parsed !== undefined ? options.parsed : true;
     }
     
     getStatusCode() {
@@ -27,6 +32,26 @@ class Response {
     getHeaders() {
         return this.headers;
     }
+
+    getStatusMessage() {
+        return this.statusMessage;
+    }
+
+    getRawBody() {
+        return this.rawBody;
+    }
+
+    getRequest() {
+        return this.request;
+    }
+
+    getContentType() {
+        return this.contentType;
+    }
+
+    isParsed() {
+        return this.parsed;
+    }
     
     isSuccess() {
         return this.statusCode >= 200 && this.statusCode < 300;
@@ -46,7 +71,8 @@ class Response {
     toArray() {
         return {
             status: this.statusCode,
-            body: this.body
+            body: this.body,
+            headers: this.headers
         };
     }
 }

package/lib/Route.js

@@ -0,0 +1,111 @@
+/**
+ * hlquery Node.js Client - Fluent Route API
+ *
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ *
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+}
+
+function cleanRoute(route) {
+    if (route === null || route === undefined) {
+        return '';
+    }
+
+    if (Array.isArray(route)) {
+        return route
+            .map(segment => {
+                requireNonEmptyString(String(segment), 'Route segment');
+                return encodeURIComponent(String(segment).replace(/^\/+|\/+$/g, ''));
+            })
+            .filter(Boolean)
+            .join('/');
+    }
+
+    return String(route).replace(/^\/+|\/+$/g, '');
+}
+
+function joinPath(basePath, route) {
+    const base = String(basePath || '').replace(/\/+$/g, '');
+    const suffix = cleanRoute(route);
+
+    if (!suffix) {
+        return base || '/';
+    }
+
+    if (!base || base === '/') {
+        return `/${suffix}`;
+    }
+
+    return `${base}/${suffix}`;
+}
+
+/**
+ * Small Redis-style command builder for dynamic hlquery routes.
+ */
+class RouteCommand {
+    constructor(request, path) {
+        this.request = request;
+        this.path = path || '/';
+    }
+
+    route(route) {
+        return new RouteCommand(this.request, joinPath(this.path, route));
+    }
+
+    async call(method, body = null, queryParams = {}, options = {}) {
+        requireNonEmptyString(method, 'HTTP method');
+        return await this.request.execute(method.toUpperCase(), this.path, body, queryParams, options);
+    }
+
+    async get(queryParams = {}, options = {}) {
+        return await this.call('GET', null, queryParams, options);
+    }
+
+    async post(body = null, queryParams = {}, options = {}) {
+        return await this.call('POST', body, queryParams, options);
+    }
+
+    async put(body = null, queryParams = {}, options = {}) {
+        return await this.call('PUT', body, queryParams, options);
+    }
+
+    async patch(body = null, queryParams = {}, options = {}) {
+        return await this.call('PATCH', body, queryParams, options);
+    }
+
+    async delete(queryParams = {}, options = {}) {
+        return await this.call('DELETE', null, queryParams, options);
+    }
+
+    async del(queryParams = {}, options = {}) {
+        return await this.delete(queryParams, options);
+    }
+}
+
+/**
+ * Fluent command builder rooted at /modules/{name}.
+ */
+class ModuleRouteCommand extends RouteCommand {
+    constructor(request, name) {
+        requireNonEmptyString(name, 'Module name');
+        super(request, `/modules/${encodeURIComponent(name)}`);
+        this.name = name;
+    }
+
+    async syntax(queryParams = {}, options = {}) {
+        return await this.route('syntax').get(queryParams, options);
+    }
+}
+
+module.exports = {
+    RouteCommand,
+    ModuleRouteCommand,
+    cleanRoute,
+    joinPath
+};

package/lib/SAM.js

@@ -123,6 +123,15 @@ class SAM {
         return await this.pause(0, params);
     }
 
+    async improve(params = {}) {
+        this._validateParams(params, 'SAM improve params');
+        return await this.request.execute('POST', '/sam/improve', null, params);
+    }
+
+    async flushActorMetadata() {
+        return await this.request.execute('POST', '/sam/flush_actor_metadata');
+    }
+
     async listDocuments(collectionName, offset = 0, limit = 20, params = {}) {
         Validator.validateCollectionName(collectionName);
         this._validateParams(params, 'SAM document list params');
@@ -169,6 +178,22 @@ class SAM {
 
         return await this.getDocument(collectionName, documentId, queryParams);
     }
+
+    async addDocumentLabel(collectionName, documentId, labels) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+
+        const normalizedLabels = Array.isArray(labels) ? labels : [labels];
+        if (normalizedLabels.length === 0 || normalizedLabels.some(label => typeof label !== 'string' || label.trim() === '')) {
+            throw new Error('SAM document labels must contain at least one non-empty string');
+        }
+
+        return await this.request.execute(
+            'POST',
+            `/sam/label/add/${encodeURIComponent(collectionName)}/${encodeURIComponent(documentId)}`,
+            { labels: normalizedLabels }
+        );
+    }
 }
 
 module.exports = SAM;

package/lib/Search.js

@@ -15,6 +15,7 @@ class Search {
     constructor(request, collections) {
         this.request = request;
         this.collections = collections;
+        this.searchableFieldsCache = new Map();
     }
     
     /**
@@ -96,13 +97,18 @@ class Search {
             queryParams.query_by = Array.isArray(params.query_by)
                 ? params.query_by.join(',')
                 : params.query_by;
-        } else if (params.q && params.q !== '') {
-            // Auto-detect searchable fields
-            const collection = await this.collections.get(collectionName);
-            if (collection.getStatusCode() === 200) {
-                const body = collection.getBody();
-                if (body.searchable_fields && body.searchable_fields.length > 0) {
-                    queryParams.query_by = body.searchable_fields.join(',');
+        } else if (params.q && params.q !== '' && params.auto_detect_query_by !== false) {
+            const cacheKey = collectionName;
+            if (this.searchableFieldsCache.has(cacheKey)) {
+                queryParams.query_by = this.searchableFieldsCache.get(cacheKey);
+            } else {
+                const collection = await this.collections.get(collectionName);
+                if (collection.getStatusCode() === 200) {
+                    const body = collection.getBody();
+                    if (body.searchable_fields && body.searchable_fields.length > 0) {
+                        queryParams.query_by = body.searchable_fields.join(',');
+                        this.searchableFieldsCache.set(cacheKey, queryParams.query_by);
+                    }
                 }
             }
         }

package/lib/System.js

@@ -30,6 +30,10 @@ class System {
         return await this.request.execute('GET', '/boot-status');
     }
 
+    async ready() {
+        return await this.request.execute('GET', '/ready');
+    }
+
     async info() {
         return await this.request.execute('GET', '/');
     }
@@ -46,6 +50,14 @@ class System {
         return await this.request.execute('GET', '/metrics.json');
     }
 
+    async metricsHistory() {
+        return await this.request.execute('GET', '/metrics/history');
+    }
+
+    async metricsHistoryAlias() {
+        return await this.request.execute('GET', '/metrics-history');
+    }
+
     async connections() {
         return await this.request.execute('GET', '/connections');
     }
@@ -105,6 +117,26 @@ class System {
     async storageStatus() {
         return await this.request.execute('GET', '/admin/storage_status');
     }
+
+    async searchConfig() {
+        return await this.request.execute('GET', '/search-config');
+    }
+
+    async llm() {
+        return await this.request.execute('GET', '/llm');
+    }
+
+    async updateCounters(params = {}) {
+        return await this.request.execute('POST', '/update-counters', null, params);
+    }
+
+    async debugCounters() {
+        return await this.request.execute('GET', '/debug/counters');
+    }
+
+    async repair(params = {}) {
+        return await this.request.execute('POST', '/repair', null, params);
+    }
 }
 
 module.exports = System;

package/lib/Users.js

@@ -0,0 +1,51 @@
+/**
+ * hlquery Node.js Client - Users API
+ *
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ *
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+class Users {
+    constructor(request) {
+        this.request = request;
+    }
+
+    _validateName(name) {
+        if (typeof name !== 'string' || name.trim() === '') {
+            throw new Error('User name is required');
+        }
+    }
+
+    async list() {
+        return await this.request.execute('GET', '/users');
+    }
+
+    async get(name) {
+        this._validateName(name);
+        return await this.request.execute('GET', `/users/${encodeURIComponent(name)}`);
+    }
+
+    async create(params) {
+        if (!params || typeof params !== 'object' || Array.isArray(params)) {
+            throw new Error('User parameters must be an object');
+        }
+        this._validateName(params.name);
+        return await this.request.execute('POST', '/users', params);
+    }
+
+    async update(name, params) {
+        this._validateName(name);
+        if (!params || typeof params !== 'object' || Array.isArray(params)) {
+            throw new Error('User parameters must be an object');
+        }
+        return await this.request.execute('PUT', `/users/${encodeURIComponent(name)}`, params);
+    }
+
+    async delete(name) {
+        this._validateName(name);
+        return await this.request.execute('DELETE', `/users/${encodeURIComponent(name)}`);
+    }
+}
+
+module.exports = Users;