hlquery-node-client 1.0.5 → 1.0.6

package/README.md

@@ -22,7 +22,7 @@ It is a good fit for backend services, scripts, dashboards, and apps that want h
 
 ### Why use it?
 
-Use the Node.js client when you want hlquery calls to read like regular application code. The client is organized around familiar modules such as `client.collections()`, `client.documents()`, and `client.sam()`, so collection management, document indexing, search, SQL, and SAM workflows stay easy to find.
+Use the Node.js client when you want hlquery calls to read like regular application code. The client is organized around familiar modules such as `client.collections()`, `client.documents()`, and `client.sam()`, with Redis-style dynamic route helpers for module APIs and custom endpoints.
 
 It also keeps the repetitive parts in one place: authentication, request parameters, endpoint paths, and parsed responses are handled consistently across the client. Common hlquery workflows are covered by default, while raw request access is still available when you need a custom route.
 
@@ -49,12 +49,14 @@ const client = new Client(process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_U
 });
 
 const health = await client.system().health();
+
 /* Print the HTTP status code from the health response. */
 console.log('status:', health.getStatusCode());
 
 const collections = await client.collections().list(0, 10);
+
 /* Print the collection list response body. */
-console.log(collections.getBody());
+console.log(collections.body);
 ```
 
 ### Auth
@@ -93,24 +95,31 @@ const response = await client.executeRequest('GET', '/modules/<name>/<route>', n
   q: 'example query'
 });
 
-/* Print the server status response body. */
-console.log(status.getBody());
-/* Print the health response body. */
-console.log(health.getBody());
-/* Print the runtime configuration response body. */
-console.log(etc.getBody());
-/* Print the configured cluster links response body. */
-console.log(links.getBody());
-/* Print the link ping response body. */
-console.log(ping.getBody());
-/* Print the link connect response body. */
-console.log(connect.getBody());
-/* Print the link disconnect response body. */
-console.log(disconnect.getBody());
-/* Print the flush response body. */
-console.log(flush.getBody());
-/* Print the custom route response body. */
-console.log(response.getBody());
+console.log(response.body);
+```
+
+For module routes and custom endpoints, the client also supports a Redis-style fluent API:
+
+```javascript
+const result = await client.module('<name>').route('<route>').get({
+  q: 'example query'
+});
+
+console.log(result.body);
+
+const indexed = await client.module('<name>').route('index').post({
+  id: 'doc_1',
+  title: 'Example'
+});
+
+const modules = await client.modules().list();
+const syntax = await client.modules().syntax('<name>');
+const raw = await client.route('etc').get();
+
+console.log(indexed.body);
+console.log(modules.body);
+console.log(syntax.body);
+console.log(raw.body);
 ```
 
 ### SAM
@@ -127,11 +136,11 @@ const results = await sam.search('books', 'distributed systems', {
 });
 
 /* Print the SAM status response body. */
-console.log(status.getBody());
+console.log(status.body);
 /* Print the SAM search history response body. */
-console.log(history.getBody());
+console.log(history.body);
 /* Print the SAM search results response body. */
-console.log(results.getBody());
+console.log(results.body);
 ```
 
 ### SQL
@@ -147,11 +156,11 @@ const books = await client.sqlSearch(
 );
 
 /* Print the SQL query response body. */
-console.log(rows.getBody());
+console.log(rows.body);
 /* Print the SQL execution response body. */
-console.log(execResult.getBody());
+console.log(execResult.body);
 /* Print the collection SQL search response body. */
-console.log(books.getBody());
+console.log(books.body);
 ```
 
 ### Contributing

package/index.js

@@ -25,6 +25,10 @@ module.exports.Synonyms = require('./lib/Synonyms');
 module.exports.Stopwords = require('./lib/Stopwords');
 module.exports.System = require('./lib/System');
 module.exports.SAM = require('./lib/SAM');
+module.exports.Modules = require('./lib/Modules');
+module.exports.Users = require('./lib/Users');
+module.exports.Analytics = require('./lib/Analytics');
+module.exports.Route = require('./lib/Route');
 
 // Export exceptions
 module.exports.Exceptions = require('./lib/Exceptions');

package/lib/Aliases.js

@@ -20,6 +20,11 @@ class Aliases {
         return await this.request.execute('GET', '/aliases');
     }
 
+    async listCollection(collectionName) {
+        Validator.validateCollectionName(collectionName);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/aliases`);
+    }
+
     async get(name) {
         Validator.validateCollectionName(name);
         return await this.request.execute('GET', `/aliases/${encodeURIComponent(name)}`);

package/lib/Analytics.js

@@ -0,0 +1,30 @@
+/**
+ * hlquery Node.js Client - Analytics 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.
+ */
+
+const Validator = require('../utils/Validator');
+
+class Analytics {
+    constructor(request) {
+        this.request = request;
+    }
+
+    async click(payload) {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            throw new Error('Analytics click payload must be an object');
+        }
+
+        Validator.validateCollectionName(payload.collection);
+
+        const documentId = payload.doc_id !== undefined ? payload.doc_id : payload.document_id;
+        Validator.validateDocumentId(documentId);
+
+        return await this.request.execute('POST', '/analytics/click', payload);
+    }
+}
+
+module.exports = Analytics;

package/lib/Client.js

@@ -18,6 +18,10 @@ const Synonyms = require('./Synonyms');
 const Stopwords = require('./Stopwords');
 const System = require('./System');
 const SAM = require('./SAM');
+const Modules = require('./Modules');
+const Users = require('./Users');
+const Analytics = require('./Analytics');
+const { RouteCommand, ModuleRouteCommand } = require('./Route');
 const Config = require('../utils/Config');
 
 /**
@@ -38,7 +42,8 @@ class Client {
             baseUrl,
             opts.timeout,
             opts.token || null,
-            opts.auth_method || 'bearer'
+            opts.auth_method || 'bearer',
+            opts
         );
         
         this._collections = new Collections(this.request);
@@ -51,6 +56,9 @@ class Client {
         this._stopwords = new Stopwords(this.request);
         this._system = new System(this.request);
         this._sam = new SAM(this.request);
+        this._modules = new Modules(this.request);
+        this._users = new Users(this.request);
+        this._analytics = new Analytics(this.request);
     }
     
     /**
@@ -143,6 +151,10 @@ class Client {
         return await this._system.bootStatus();
     }
 
+    async ready() {
+        return await this._system.ready();
+    }
+
     /**
      * Get metrics.
      *
@@ -161,6 +173,10 @@ class Client {
         return await this._system.metricsJson();
     }
 
+    async metricsHistory() {
+        return await this._system.metricsHistory();
+    }
+
     /**
      * Get live connections.
      *
@@ -242,6 +258,26 @@ class Client {
         return await this._system.storageStatus();
     }
 
+    async searchConfig() {
+        return await this._system.searchConfig();
+    }
+
+    async llm() {
+        return await this._system.llm();
+    }
+
+    async updateCounters(params = {}) {
+        return await this._system.updateCounters(params);
+    }
+
+    async debugCounters() {
+        return await this._system.debugCounters();
+    }
+
+    async repair(params = {}) {
+        return await this._system.repair(params);
+    }
+
     /**
      * Execute a top-level SQL query through GET /sql.
      *
@@ -383,6 +419,10 @@ class Client {
     async getCollection(name) {
         return await this._collections.get(name);
     }
+
+    async getCollectionLanguage(name) {
+        return await this._collections.language(name);
+    }
     
     /**
      * Get collection fields (formatted)
@@ -503,6 +543,10 @@ class Client {
         return await this._documents.get(collectionName, documentId);
     }
 
+    async getDocumentContext(collectionName, documentId) {
+        return await this._documents.context(collectionName, documentId);
+    }
+
     /**
      * Copy a document to a new ID within the same collection.
      *
@@ -548,6 +592,18 @@ class Client {
     async facetCounts(collectionName, params = {}) {
         return await this._documents.facetCounts(collectionName, params);
     }
+
+    async maybeDocuments(collectionName, params = {}) {
+        return await this._documents.maybe(collectionName, params);
+    }
+
+    async updateDocumentsByQuery(collectionName, body = {}) {
+        return await this._documents.updateByQuery(collectionName, body);
+    }
+
+    async deleteDocumentsByQuery(collectionName, body = {}) {
+        return await this._documents.deleteByQuery(collectionName, body);
+    }
     
     // ============================================================================
     // SEARCH API
@@ -603,6 +659,14 @@ class Client {
         return await this._sam.clearPause(params);
     }
 
+    async samImprove(params = {}) {
+        return await this._sam.improve(params);
+    }
+
+    async samFlushActorMetadata() {
+        return await this._sam.flushActorMetadata();
+    }
+
     async samDocuments(collectionName, offset = 0, limit = 20, params = {}) {
         return await this._sam.listDocuments(collectionName, offset, limit, params);
     }
@@ -615,6 +679,10 @@ class Client {
         return await this._sam.openDocument(collectionName, documentId, interactionQuery, params);
     }
 
+    async samAddDocumentLabel(collectionName, documentId, labels) {
+        return await this._sam.addDocumentLabel(collectionName, documentId, labels);
+    }
+
     /**
      * Get aliases API instance
      *
@@ -668,6 +736,57 @@ class Client {
     keys() {
         return this._keys;
     }
+
+    /**
+     * Get runtime modules API instance
+     *
+     * @returns {Modules}
+     */
+    modules() {
+        return this._modules;
+    }
+
+    /**
+     * Get users API instance.
+     *
+     * @returns {Users}
+     */
+    users() {
+        return this._users;
+    }
+
+    /**
+     * Get analytics API instance.
+     *
+     * @returns {Analytics}
+     */
+    analytics() {
+        return this._analytics;
+    }
+
+    async analyticsClick(payload) {
+        return await this._analytics.click(payload);
+    }
+
+    /**
+     * Build a Redis-style dynamic module command.
+     *
+     * @param {string} name
+     * @returns {ModuleRouteCommand}
+     */
+    module(name) {
+        return new ModuleRouteCommand(this.request, name);
+    }
+
+    /**
+     * Build a Redis-style top-level route command.
+     *
+     * @param {string|Array<string>} route
+     * @returns {RouteCommand}
+     */
+    route(route) {
+        return new RouteCommand(this.request, '/').route(route);
+    }
     
     /**
      * Search documents
@@ -722,8 +841,8 @@ class Client {
      * @param {object} queryParams Query parameters
      * @returns {Promise<Response>}
      */
-    async executeRequest(method, path, body = null, queryParams = {}) {
-        return await this.request.execute(method, path, body, queryParams);
+    async executeRequest(method, path, body = null, queryParams = {}, options = {}) {
+        return await this.request.execute(method, path, body, queryParams, options);
     }
     
     // ============================================================================

package/lib/Collections.js

@@ -42,6 +42,17 @@ class Collections {
         Validator.validateCollectionName(name);
         return await this.request.execute('GET', `/collections/${encodeURIComponent(name)}`);
     }
+
+    /**
+     * Get detected collection language information.
+     *
+     * @param {string} name Collection name
+     * @returns {Promise<Response>}
+     */
+    async language(name) {
+        Validator.validateCollectionName(name);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(name)}/lang`);
+    }
     
     /**
      * Create a new collection
@@ -52,10 +63,14 @@ class Collections {
      */
     async create(name, schema) {
         Validator.validateCollectionName(name);
+        if (schema && schema.name !== undefined && schema.name !== name) {
+            throw new Error('Schema name must match the collection name argument');
+        }
+
         // Merge schema with name at top level (server expects fields/searchable_fields at root)
         const requestBody = {
-            name: name,
-            ...schema
+            ...schema,
+            name: name
         };
         return await this.request.execute('POST', '/collections', requestBody);
     }
@@ -99,6 +114,24 @@ class Collections {
         const body = response.getBody();
         const allFields = [];
         const fieldTypes = {};
+
+        if (Array.isArray(body.fields)) {
+            for (const field of body.fields) {
+                const fieldName = typeof field === 'string' ? field : field.name;
+                if (!fieldName) {
+                    continue;
+                }
+                if (!allFields.includes(fieldName)) {
+                    allFields.push(fieldName);
+                }
+                if (!fieldTypes[fieldName]) {
+                    fieldTypes[fieldName] = [];
+                }
+                if (field.type && !fieldTypes[fieldName].includes(field.type)) {
+                    fieldTypes[fieldName].push(field.type);
+                }
+            }
+        }
         
         // Collect searchable fields
         if (body.searchable_fields) {
@@ -142,7 +175,7 @@ class Collections {
         // Format fields
         const fields = allFields.map(field => ({
             name: field,
-            type: fieldTypes[field].join(', ')
+            type: fieldTypes[field].join(', ') || 'unknown'
         }));
         
         return new Response(200, {

package/lib/Documents.js

@@ -18,6 +18,13 @@ class Documents {
     constructor(request) {
         this.request = request;
     }
+
+    _responseFromRequestError(error) {
+        if (error && error.response) {
+            return error.response;
+        }
+        throw error;
+    }
     
     /**
      * List documents in a collection
@@ -52,6 +59,20 @@ class Documents {
         
         return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}`);
     }
+
+    /**
+     * Get alternate contextual phrases for a document.
+     *
+     * @param {string} collectionName
+     * @param {string} documentId
+     * @returns {Promise<Response>}
+     */
+    async context(collectionName, documentId) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}/context`);
+    }
     
     /**
      * Add a document
@@ -177,14 +198,24 @@ class Documents {
         }
         
         // Server expects {documents: [...]} format; fall back to per-doc inserts if bulk route is unavailable.
-        const bulkResponse = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/import`, {
-            documents: documents
-        });
+        let bulkResponse;
+        try {
+            bulkResponse = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/import`, {
+                documents: documents
+            });
+        } catch (error) {
+            bulkResponse = this._responseFromRequestError(error);
+        }
 
         if (bulkResponse && bulkResponse.getStatusCode && bulkResponse.getStatusCode() === 404) {
             let inserted = 0;
             for (const doc of documents) {
-                const response = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, doc);
+                let response;
+                try {
+                    response = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, doc);
+                } catch (error) {
+                    response = this._responseFromRequestError(error);
+                }
                 const status = response.getStatusCode();
                 if (status !== 201) {
                     return response;
@@ -215,7 +246,12 @@ class Documents {
             throw new Error('Source and target document ids must differ');
         }
 
-        const targetCheck = await this.get(collectionName, targetId);
+        let targetCheck;
+        try {
+            targetCheck = await this.get(collectionName, targetId);
+        } catch (error) {
+            targetCheck = this._responseFromRequestError(error);
+        }
         if (targetCheck.getStatusCode() === 200) {
             return targetCheck;
         }
@@ -223,7 +259,12 @@ class Documents {
             return targetCheck;
         }
 
-        const sourceResponse = await this.get(collectionName, sourceId);
+        let sourceResponse;
+        try {
+            sourceResponse = await this.get(collectionName, sourceId);
+        } catch (error) {
+            sourceResponse = this._responseFromRequestError(error);
+        }
         if (sourceResponse.getStatusCode() !== 200) {
             return sourceResponse;
         }
@@ -302,6 +343,57 @@ class Documents {
             queryParams
         );
     }
+
+    /**
+     * Request query suggestions for a collection.
+     *
+     * @param {string} collectionName
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async maybe(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateSearchParams(params);
+
+        const method = params.body ? 'POST' : 'GET';
+        const body = params.body || (method === 'POST' ? params : null);
+        const queryParams = method === 'GET' ? params : {};
+
+        return await this.request.execute(
+            method,
+            `/collections/${encodeURIComponent(collectionName)}/documents/maybe`,
+            body,
+            queryParams
+        );
+    }
+
+    /**
+     * Update documents matching a query.
+     *
+     * @param {string} collectionName
+     * @param {object} body
+     * @returns {Promise<Response>}
+     */
+    async updateByQuery(collectionName, body = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentFields(body);
+
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/_update_by_query`, body);
+    }
+
+    /**
+     * Delete documents matching a query.
+     *
+     * @param {string} collectionName
+     * @param {object} body
+     * @returns {Promise<Response>}
+     */
+    async deleteByQuery(collectionName, body = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentFields(body);
+
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/_delete_by_query`, body);
+    }
     
     /**
      * Delete documents by filter

package/lib/Exceptions.js

@@ -10,9 +10,12 @@
  * Base exception class for hlquery client
  */
 class HlqueryException extends Error {
-    constructor(message) {
+    constructor(message, options = {}) {
         super(message);
         this.name = 'HlqueryException';
+        if (options.cause) {
+            this.cause = options.cause;
+        }
         Error.captureStackTrace(this, this.constructor);
     }
 }
@@ -31,11 +34,16 @@ class AuthenticationException extends HlqueryException {
  * Exception thrown when a request fails
  */
 class RequestException extends HlqueryException {
-    constructor(message, statusCode = 0, responseBody = null) {
-        super(message);
+    constructor(message, statusCode = 0, responseBody = null, options = {}) {
+        super(message, options);
         this.name = 'RequestException';
         this.statusCode = statusCode;
         this.responseBody = responseBody;
+        this.response = options.response || null;
+        this.headers = options.headers || {};
+        this.rawBody = options.rawBody || null;
+        this.retryable = Boolean(options.retryable);
+        this.code = options.code || null;
     }
 }
 

package/lib/Modules.js

@@ -0,0 +1,64 @@
+/**
+ * hlquery Node.js Client - Runtime Modules 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.
+ */
+
+const { ModuleRouteCommand, cleanRoute } = require('./Route');
+
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+}
+
+/**
+ * Runtime module discovery and dynamic route calls.
+ */
+class Modules {
+    constructor(request) {
+        this.request = request;
+    }
+
+    list() {
+        return this.request.execute('GET', '/modules');
+    }
+
+    load(name) {
+        requireNonEmptyString(name, 'Module name');
+        return this.request.execute('POST', `/loadmodule/${encodeURIComponent(name)}`);
+    }
+
+    unload(name) {
+        requireNonEmptyString(name, 'Module name');
+        return this.request.execute('POST', `/unloadmodule/${encodeURIComponent(name)}`);
+    }
+
+    syntax(name, queryParams = {}) {
+        return this.module(name).syntax(queryParams);
+    }
+
+    module(name) {
+        return new ModuleRouteCommand(this.request, name);
+    }
+
+    route(name, route = '') {
+        return this.module(name).route(route);
+    }
+
+    call(name, route = '', method = 'GET', body = null, queryParams = {}, options = {}) {
+        requireNonEmptyString(name, 'Module name');
+        requireNonEmptyString(method, 'HTTP method');
+
+        const suffix = cleanRoute(route);
+        const path = suffix
+            ? `/modules/${encodeURIComponent(name)}/${suffix}`
+            : `/modules/${encodeURIComponent(name)}`;
+
+        return this.request.execute(method.toUpperCase(), path, body, queryParams, options);
+    }
+}
+
+module.exports = Modules;