hlquery-node-client 1.0.1 → 1.0.2

package/README.md

@@ -22,10 +22,9 @@ It is a good fit for backend services, scripts, dashboards, and apps that want h
 
 ### Why use it?
 
-- Familiar modular layout such as `client.collections()`, `client.documents()`, and `client.sam()`.
-- Consistent auth, params, and parsed responses.
-- Good default coverage for common hlquery workflows.
-- Raw request access for custom routes.
+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.
+
+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.
 
 ### Why choose it over raw HTTP?
 
@@ -34,7 +33,7 @@ Choose the Node.js client over raw HTTP when you want less repetitive `fetch` or
 ### Install
 
 ```bash
-npm install hlquery-node-client
+$ npm install hlquery-node-client
 ```
 
 For local development inside this repository:
@@ -54,9 +53,11 @@ 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());
 ```
 
@@ -72,6 +73,50 @@ client.setAuthToken('your_token_here', 'bearer');
 client.setAuthToken('your_api_key_here', 'api-key');
 ```
 
+### Operational routes
+
+The client includes wrappers for the common server and cluster routes used by dashboards, scripts, and maintenance jobs:
+
+```javascript
+const status = await client.status();
+const health = await client.health();
+const etc = await client.etc();
+
+const links = await client.links();
+const ping = await client.linksPing();
+const connect = await client.linksConnect('http://node-b:9200');
+const disconnect = await client.linksDisconnect('http://node-b:9200');
+
+const flush = await client.flush();
+```
+
+Routes that do not have a dedicated wrapper can still be called through `executeRequest()`:
+
+```javascript
+const response = await client.executeRequest('GET', '/modules/<name>/<route>', null, {
+  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());
+```
+
 ### SAM
 
 SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.
@@ -85,23 +130,31 @@ const results = await sam.search('books', 'distributed systems', {
   limit: 10
 });
 
+/* 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());
 ```
 
 ### SQL
 
 ```javascript
-const sql = client.sql();
-
-const rows = await sql.query('SHOW COLLECTIONS;');
-const books = await sql.search(
+const rows = await client.sql('SHOW COLLECTIONS;');
+const execResult = await client.execSql(
+  "INSERT INTO logs_archive (id, title) VALUES ('row-1', 'warm cache');"
+);
+const books = await client.sqlSearch(
   'books',
   'SELECT id, title FROM books ORDER BY title ASC LIMIT 3;'
 );
 
+/* Print the SQL query response body. */
 console.log(rows.getBody());
+/* Print the SQL execution response body. */
+console.log(execResult.getBody());
+/* Print the collection SQL search response body. */
 console.log(books.getBody());
 ```
 
@@ -114,6 +167,7 @@ const response = await client.executeRequest('GET', '/modules/<name>/<route>', n
   q: 'example query'
 });
 
+/* Print the custom module route response body. */
 console.log(response.getBody());
 ```
 

package/lib/Client.js

@@ -473,6 +473,50 @@ class Client {
         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
      *

package/lib/SAM.js

@@ -16,28 +16,51 @@ class SAM {
         this.request = request;
     }
 
-    async search(collectionName, query, params = {}) {
-        Validator.validateCollectionName(collectionName);
+    _validateParams(params, label) {
+        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+            throw new Error(`${label} must be an object`);
+        }
+    }
 
+    async search(collectionName, query, params = {}) {
         if (typeof query !== 'string' || query.trim() === '') {
             throw new Error('SAM query must be a non-empty string');
         }
 
-        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
-            throw new Error('SAM search params must be an object');
-        }
+        this._validateParams(params, 'SAM search params');
 
-        return await this.request.execute('GET', '/sam/search', null, {
+        const queryParams = {
             ...params,
-            collection: collectionName,
             q: query
+        };
+
+        if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
+            Validator.validateCollectionName(collectionName);
+            queryParams.collection = collectionName;
+        } else if (!queryParams.all && !queryParams.collections) {
+            throw new Error('Collection name is required unless all=true or collections is provided');
+        }
+
+        return await this.request.execute('GET', '/sam/search', null, queryParams);
+    }
+
+    async searchAll(query, params = {}) {
+        this._validateParams(params, 'SAM search params');
+        return await this.search(null, query, { ...params, all: true });
+    }
+
+    async rebuild(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        this._validateParams(params, 'SAM rebuild params');
+
+        return await this.request.execute('POST', '/sam/rebuild', null, {
+            ...params,
+            collection: collectionName
         });
     }
 
     async status(collectionName = null, params = {}) {
-        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
-            throw new Error('SAM status params must be an object');
-        }
+        this._validateParams(params, 'SAM status params');
 
         const queryParams = { ...params };
 
@@ -49,11 +72,22 @@ class SAM {
         return await this.request.execute('GET', '/sam/status', null, queryParams);
     }
 
-    async history(collectionName = null, limit = 100, params = {}) {
-        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
-            throw new Error('SAM history params must be an object');
+    async debug(collectionName = null, params = {}) {
+        this._validateParams(params, 'SAM debug params');
+
+        const queryParams = { ...params };
+
+        if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
+            Validator.validateCollectionName(collectionName);
+            queryParams.collection = collectionName;
         }
 
+        return await this.request.execute('GET', '/sam/debug', null, queryParams);
+    }
+
+    async history(collectionName = null, limit = 100, params = {}) {
+        this._validateParams(params, 'SAM history params');
+
         const queryParams = {
             ...params,
             limit: Number(limit)
@@ -66,6 +100,62 @@ class SAM {
 
         return await this.request.execute('GET', '/sam/history', null, queryParams);
     }
+
+    async pause(pauseUntilMs, params = {}) {
+        this._validateParams(params, 'SAM pause params');
+
+        const pause = Number(pauseUntilMs);
+        if (!Number.isFinite(pause) || pause < 0) {
+            throw new Error('SAM pause value must be a non-negative unix millisecond timestamp, or 0 to clear');
+        }
+
+        return await this.request.execute('POST', '/sam/pause', null, {
+            ...params,
+            pause
+        });
+    }
+
+    async clearPause(params = {}) {
+        return await this.pause(0, params);
+    }
+
+    async listDocuments(collectionName, offset = 0, limit = 20, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        this._validateParams(params, 'SAM document list params');
+
+        return await this.request.execute('GET', '/sam/documents', null, {
+            ...params,
+            collection: collectionName,
+            offset: Number(offset),
+            limit: Number(limit)
+        });
+    }
+
+    async getDocument(collectionName, documentId, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+        this._validateParams(params, 'SAM document params');
+
+        return await this.request.execute(
+            'GET',
+            `/sam/documents/${encodeURIComponent(collectionName)}/${encodeURIComponent(documentId)}`,
+            null,
+            params
+        );
+    }
+
+    async openDocument(collectionName, documentId, interactionQuery = null, params = {}) {
+        const queryParams = { ...params };
+
+        if (interactionQuery !== null && interactionQuery !== undefined && interactionQuery !== '') {
+            if (typeof interactionQuery !== 'string') {
+                throw new Error('SAM interaction query must be a string');
+            }
+            queryParams.interaction_query = interactionQuery;
+        }
+
+        return await this.getDocument(collectionName, documentId, queryParams);
+    }
 }
 
 module.exports = SAM;

package/lib/conformance.js

@@ -44,9 +44,15 @@ const NODE_CLIENT_ROUTE_COVERAGE = [
     { path: '/collections/{name}/vector_search', methods: ['GET', 'POST'], status: 'supported', client: 'search.vectorSearch' },
     { path: '/multi_search', methods: ['GET', 'POST'], status: 'supported', client: 'search.multiSearch' },
     { path: '/search', methods: ['GET', 'POST'], status: 'supported', client: 'search.globalSearch' },
+    { path: '/sql', methods: ['GET', 'POST'], status: 'supported', client: 'system.sql/execSql' },
+    { path: '/sam/rebuild', methods: ['POST'], status: 'supported', client: 'sam.rebuild' },
     { path: '/sam/search', methods: ['GET'], status: 'supported', client: 'sam.search' },
     { path: '/sam/status', methods: ['GET'], status: 'supported', client: 'sam.status' },
+    { path: '/sam/debug', methods: ['GET'], status: 'supported', client: 'sam.debug' },
     { path: '/sam/history', methods: ['GET'], status: 'supported', client: 'sam.history' },
+    { path: '/sam/pause', methods: ['POST'], status: 'supported', client: 'sam.pause/clearPause' },
+    { path: '/sam/documents', methods: ['GET'], status: 'supported', client: 'sam.listDocuments' },
+    { path: '/sam/documents/{collection}/{id}', methods: ['GET'], status: 'supported', client: 'sam.getDocument/openDocument' },
     { path: '/collections/{name}/documents/facet_counts', methods: ['GET', 'POST'], status: 'supported', client: 'documents.facetCounts' },
     { path: '/collections/{name}/documents/export', methods: ['GET', 'POST'], status: 'supported', client: 'documents.export' },
     { path: '/collections/{name}/synonyms', methods: ['GET'], status: 'supported', client: 'synonyms.list' },
@@ -67,6 +73,10 @@ const NODE_CLIENT_ROUTE_COVERAGE = [
     { path: '/keys/{id}', methods: ['GET', 'PUT', 'DELETE'], status: 'supported', client: 'keys.get/update/delete' },
     { path: '/update-counters', methods: ['GET', 'POST'], status: 'omitted', reason: 'Internal maintenance endpoint; intentionally left off the public Node client.' },
     { path: '/query', methods: ['GET'], status: 'omitted', reason: 'Alias of /status; client exposes status() instead of duplicate naming.' },
+    { path: '/search-config', methods: ['GET'], status: 'omitted', reason: 'Diagnostic configuration endpoint; stable client exposes raw executeRequest() for this route.' },
+    { path: '/ready', methods: ['GET'], status: 'omitted', reason: 'Readiness alias; client exposes startup() and bootStatus() instead of duplicate naming.' },
+    { path: '/llm', methods: ['GET', 'POST'], status: 'omitted', reason: 'LLM runtime endpoint is module/config dependent and not part of the stable SDK surface yet.' },
+    { path: '/repair', methods: ['POST'], status: 'omitted', reason: 'Administrative repair endpoint; intentionally left off the public Node client.' },
     { path: '/modules', methods: ['GET'], status: 'omitted', reason: 'Module APIs are intentionally omitted until the module surface is documented and stabilized for SDKs.' },
     { path: '/modules/{name}', methods: ['ANY'], status: 'omitted', reason: 'Module-specific routes are dynamic and intentionally not wrapped in the stable Node client.' },
     { path: '/modules/{name}/syntax', methods: ['GET'], status: 'omitted', reason: 'Module-specific routes are dynamic and intentionally not wrapped in the stable Node client.' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlquery-node-client",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Node.js client library for hlquery search engine",
   "main": "index.js",
   "type": "commonjs",

package/test/offline-smoke.js

@@ -36,6 +36,48 @@ async function main() {
       return;
     }
 
+    if (req.url === '/status') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ready' }));
+      return;
+    }
+
+    if (req.url === '/etc') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ protocol: 'http' }));
+      return;
+    }
+
+    if (req.url === '/links') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ links: [] }));
+      return;
+    }
+
+    if (req.url === '/links/ping') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+
+    if (req.url === '/links/connect' && req.method === 'POST') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ connected: true }));
+      return;
+    }
+
+    if (req.url === '/links/disconnect' && req.method === 'POST') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ disconnected: true }));
+      return;
+    }
+
+    if (req.url === '/flush' && req.method === 'POST') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ flushed: true }));
+      return;
+    }
+
     if (req.url === '/echo-auth') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({
@@ -73,6 +115,43 @@ async function main() {
     const clientHealth = await client.health();
     assert.strictEqual(clientHealth.isSuccess(), true);
     assert.deepStrictEqual(clientHealth.getBody(), { status: 'ok' });
+
+    const clientStatus = await client.status();
+    assert.deepStrictEqual(clientStatus.getBody(), { status: 'ready' });
+
+    const clientEtc = await client.etc();
+    assert.deepStrictEqual(clientEtc.getBody(), { protocol: 'http' });
+
+    const clientLinks = await client.links();
+    assert.deepStrictEqual(clientLinks.getBody(), { links: [] });
+
+    const clientLinksPing = await client.linksPing();
+    assert.deepStrictEqual(clientLinksPing.getBody(), { ok: true });
+
+    const clientLinksConnect = await client.linksConnect('http://node-b:9200');
+    assert.deepStrictEqual(clientLinksConnect.getBody(), { connected: true });
+
+    const clientLinksDisconnect = await client.linksDisconnect('http://node-b:9200');
+    assert.deepStrictEqual(clientLinksDisconnect.getBody(), { disconnected: true });
+
+    const clientFlush = await client.flush();
+    assert.deepStrictEqual(clientFlush.getBody(), { flushed: true });
+
+    assert.strictEqual(typeof client.executeRequest, 'function');
+    assert.strictEqual(typeof client.sql, 'function');
+    assert.strictEqual(typeof client.execSql, 'function');
+    assert.strictEqual(typeof client.sqlSearch, 'function');
+    assert.strictEqual(typeof client.sam().search, 'function');
+    assert.strictEqual(typeof client.sam().searchAll, 'function');
+    assert.strictEqual(typeof client.sam().rebuild, 'function');
+    assert.strictEqual(typeof client.sam().status, 'function');
+    assert.strictEqual(typeof client.sam().debug, 'function');
+    assert.strictEqual(typeof client.sam().history, 'function');
+    assert.strictEqual(typeof client.sam().pause, 'function');
+    assert.strictEqual(typeof client.sam().clearPause, 'function');
+    assert.strictEqual(typeof client.sam().listDocuments, 'function');
+    assert.strictEqual(typeof client.sam().getDocument, 'function');
+    assert.strictEqual(typeof client.sam().openDocument, 'function');
   } finally {
     await new Promise((resolve) => server.close(resolve));
   }