hlquery-node-client 1.0.5 → 1.0.7

package/README.md

@@ -16,13 +16,13 @@
 
 ### What is the hlquery Node.js API?
 
-The hlquery Node.js API is the official Node.js client for [hlquery](https://github.com/hlquery/hlquery). It wraps the REST interface in a modular service-style client with helpers for collections, documents, search, SQL, and SAM.
+The hlquery Node.js API is the official Node.js client for [hlquery](https://github.com/hlquery/hlquery). It wraps the REST interface in a modular service-style client with helpers for collections, documents, search, and SQL.
 
 It is a good fit for backend services, scripts, dashboards, and apps that want hlquery integration without repeating request code.
 
 ### 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()` and `client.documents()`, 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
@@ -86,6 +88,16 @@ const disconnect = await client.linksDisconnect('http://node-b:9200');
 const flush = await client.flush();
 ```
 
+Maintenance actions default to `POST`, and can explicitly use either server-supported method:
+
+```javascript
+await client.updateCounters({ force: true });
+await client.updateCounters({ force: true }, 'GET');
+await client.repair({}, 'POST');
+```
+
+The client also wraps readiness, startup, metrics, connection, storage, integrity, counter, user, key, module, and analytics routes through `client.system()`, `client.users()`, `client.keys()`, `client.modules()`, and `client.analytics()`.
+
 Routes that do not have a dedicated wrapper can still be called through `executeRequest()`:
 
 ```javascript
@@ -93,45 +105,70 @@ 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);
 ```
 
-### SAM
+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 is separate from vector search. It performs term and intent-style lookup, not vector similarity search.
+### Collections, documents, and search
 
 ```javascript
-const sam = client.sam();
+const metadata = await client.collections().get('products');
+const language = await client.collections().language('products');
 
-const status = await sam.status('books');
-const history = await sam.history('books', 5);
-const results = await sam.search('books', 'distributed systems', {
-  limit: 10
+// getFields() is a compatibility alias for collection metadata. The server has
+// no /collections/{name}/fields route.
+const metadataAgain = await client.collections().getFields('products');
+
+const context = await client.documents().context('products', 'prod_1');
+const facets = await client.documents().facetCounts('products', { facet_by: 'brand' });
+const exported = await client.documents().export('products', { filter_by: 'active:true' });
+const suggestions = await client.documents().maybe('products', { q: 'keybaord' });
+
+await client.documents().updateByQuery('products', {
+  filter_by: 'active:false',
+  set: { archived: true }
 });
+await client.documents().deleteByQuery('products', { filter_by: 'expired:true' });
 
-/* Print the SAM status response body. */
-console.log(status.getBody());
-/* Print the SAM search history response body. */
-console.log(history.getBody());
-/* Print the SAM search results response body. */
-console.log(results.getBody());
+const searches = [{ collection: 'products', q: 'keyboard', query_by: 'title' }];
+await client.searchApi().multiSearch(searches);        // POST (default)
+await client.searchApi().multiSearch(searches, 'GET');
+await client.globalSearch({ collection: 'products', q: 'keyboard' });
+```
+
+Synonyms, overrides, and aliases expose separate `create()` (`POST`) and `update()` (`PUT`) helpers; `upsert()` uses the client's default upsert verb. Stopwords use their collection or global create/delete routes.
+
+### Request safety and errors
+
+`executeRequest()` accepts a relative path on the configured hlquery origin. Absolute cross-origin URLs are rejected with `RequestException` code `CROSS_ORIGIN_REQUEST`; this prevents credentials from being forwarded to another host. HTTP error bodies retain the server's `error`, optional `message`, numeric `code`, and stable `code_text` fields.
+
+Run the offline route-contract suite with:
+
+```bash
+npm test
 ```
 
 ### SQL
@@ -147,11 +184,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
@@ -160,17 +197,19 @@ We welcome contributions from the community! All contributions must be released
 
 ### How to Contribute
 
-- Check existing [issues](https://github.com/hlquery/hlquery/issues) or create new ones
-- Contribute to client libraries (Node.js, Go, Java, Python, PHP, Ruby, Rust, Perl, C++)
-- Test and report bugs
-- Improve documentation
+- Check existing [Node.js API issues](https://github.com/hlquery/node-api/issues) or create new ones
+- Contribute Node.js client changes to [hlquery/node-api](https://github.com/hlquery/node-api)
+- Contribute shared server/API changes to [hlquery/hlquery](https://github.com/hlquery/hlquery)
+- Test and report bugs against the Node.js client
+- Improve Node.js-specific documentation and examples
 
 ### Community
 
-- 📖 [Documentation](https://docs.hlquery.com)
-- 🐦 [X (Twitter)](https://x.com/hlquery)
-- 📦 [GitHub](https://github.com/hlquery/hlquery)
+- [Documentation](https://docs.hlquery.com)
+- [X (Twitter)](https://x.com/hlquery)
+- [Node.js API GitHub](https://github.com/hlquery/node-api)
+- [hlquery GitHub](https://github.com/hlquery/hlquery)
 
 ### License
 
-hlquery is licensed under the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause).
+The hlquery Node.js API is licensed under the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause).

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

@@ -17,7 +17,10 @@ const Overrides = require('./Overrides');
 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 +41,8 @@ class Client {
             baseUrl,
             opts.timeout,
             opts.token || null,
-            opts.auth_method || 'bearer'
+            opts.auth_method || 'bearer',
+            opts
         );
         
         this._collections = new Collections(this.request);
@@ -50,7 +54,9 @@ class Client {
         this._synonyms = new Synonyms(this.request);
         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 +149,10 @@ class Client {
         return await this._system.bootStatus();
     }
 
+    async ready() {
+        return await this._system.ready();
+    }
+
     /**
      * Get metrics.
      *
@@ -161,6 +171,10 @@ class Client {
         return await this._system.metricsJson();
     }
 
+    async metricsHistory() {
+        return await this._system.metricsHistory();
+    }
+
     /**
      * Get live connections.
      *
@@ -242,6 +256,22 @@ class Client {
         return await this._system.storageStatus();
     }
 
+    async searchConfig() {
+        return await this._system.searchConfig();
+    }
+
+    async updateCounters(params = {}, method = 'POST') {
+        return await this._system.updateCounters(params, method);
+    }
+
+    async debugCounters() {
+        return await this._system.debugCounters();
+    }
+
+    async repair(params = {}, method = 'POST') {
+        return await this._system.repair(params, method);
+    }
+
     /**
      * Execute a top-level SQL query through GET /sql.
      *
@@ -269,7 +299,7 @@ class Client {
      * @returns {Promise<Response>}
      */
     async clusterHealth() {
-        return await this.request.execute('GET', '/cluster/health');
+        return await this._system.health();
     }
     
     /**
@@ -278,7 +308,7 @@ class Client {
      * @returns {Promise<Response>}
      */
     async clusterStats() {
-        return await this.request.execute('GET', '/cluster/stats');
+        return await this._system.stats();
     }
     
     /**
@@ -287,7 +317,7 @@ class Client {
      * @returns {Promise<Response>}
      */
     async clusterNodes() {
-        return await this.request.execute('GET', '/cluster/nodes');
+        return await this.links();
     }
 
     /**
@@ -383,6 +413,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 +537,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 +586,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
@@ -562,59 +612,6 @@ class Client {
         return this._search;
     }
 
-    /**
-     * Get SAM API instance
-     *
-     * @returns {SAM}
-     */
-    sam() {
-        return this._sam;
-    }
-
-    async samSearch(collectionName, query, params = {}) {
-        return await this._sam.search(collectionName, query, params);
-    }
-
-    async samSearchAll(query, params = {}) {
-        return await this._sam.searchAll(query, params);
-    }
-
-    async samRebuild(collectionName, params = {}) {
-        return await this._sam.rebuild(collectionName, params);
-    }
-
-    async samStatus(collectionName = null, params = {}) {
-        return await this._sam.status(collectionName, params);
-    }
-
-    async samDebug(collectionName = null, params = {}) {
-        return await this._sam.debug(collectionName, params);
-    }
-
-    async samHistory(collectionName = null, limit = 100, params = {}) {
-        return await this._sam.history(collectionName, limit, params);
-    }
-
-    async samPause(pauseUntilMs, params = {}) {
-        return await this._sam.pause(pauseUntilMs, params);
-    }
-
-    async samClearPause(params = {}) {
-        return await this._sam.clearPause(params);
-    }
-
-    async samDocuments(collectionName, offset = 0, limit = 20, params = {}) {
-        return await this._sam.listDocuments(collectionName, offset, limit, params);
-    }
-
-    async samDocument(collectionName, documentId, params = {}) {
-        return await this._sam.getDocument(collectionName, documentId, params);
-    }
-
-    async samOpenDocument(collectionName, documentId, interactionQuery = null, params = {}) {
-        return await this._sam.openDocument(collectionName, documentId, interactionQuery, params);
-    }
-
     /**
      * Get aliases API instance
      *
@@ -668,6 +665,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 +770,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, {