hlquery-node-client 1.0.1 → 1.0.3

package/.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Node API CI
+name: Node build
 
 on:
   push:

package/README.md

@@ -6,35 +6,30 @@
 
 **A modular Node.js client library for hlquery, designed with a familiar and intuitive API structure.**
 
-[![Follow hlquery](https://img.shields.io/badge/Follow-%40hlquery-blue?logo=x&logoColor=white)](https://x.com/hlquery)
-[![Commit Activity](https://img.shields.io/github/commit-activity/m/hlquery/node-api)](https://github.com/hlquery/node-api/pulse)
-[![GitHub](https://img.shields.io/badge/GitHub-node--api-181717?logo=github&logoColor=white)](https://github.com/hlquery/node-api/stargazers)
-[![hlquery](https://img.shields.io/badge/GitHub-hlquery-blue?logo=github&logoColor=white)](https://github.com/hlquery/hlquery/stargazers)
-[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Follow hlquery](https://img.shields.io/badge/Follow-%40hlquery-blue?logo=x&logoColor=white&labelColor=000000)](https://x.com/hlquery)
+[![Node build](https://img.shields.io/badge/Node%20build-passing-brightgreen?logo=node.js&logoColor=white&labelColor=000000)](https://github.com/hlquery/node-api/actions/workflows/ci.yml)
+[![node-api](https://img.shields.io/badge/GitHub-node--api-purple?logo=github&logoColor=white&labelColor=000000)](https://github.com/hlquery/node-api/stargazers)
+[![hlquery](https://img.shields.io/badge/GitHub-hlquery-blue?logo=github&logoColor=white&labelColor=000000)](https://github.com/hlquery/hlquery/stargazers)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-a35a0f?logo=open-source-initiative&logoColor=white&labelColor=000000)](https://opensource.org/licenses/BSD-3-Clause)
 
 </div>
 
 ### What is the hlquery Node.js API?
 
-The hlquery Node.js API is the official Node.js client for 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, SQL, and SAM.
 
 It is a good fit for backend services, scripts, dashboards, and apps that want hlquery integration without repeating request code.
 
 ### 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.
 
-### Why choose it over raw HTTP?
-
-Choose the Node.js client over raw HTTP when you want less repetitive `fetch` or `axios` boilerplate, cleaner handling for auth headers and endpoint paths, and search or indexing code that stays easier to read.
+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.
 
 ### Install
 
 ```bash
-npm install hlquery-node-client
+$ npm install hlquery-node-client
 ```
 
 For local development inside this repository:
@@ -54,9 +49,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 +69,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,38 +126,34 @@ 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());
 ```
 
-### Reduce Text Example
-
-Use the raw request helper for custom module routes:
-
-```javascript
-const response = await client.executeRequest('GET', '/modules/<name>/<route>', null, {
-  q: 'example query'
-});
-
-console.log(response.getBody());
-```
-
 ### Contributing
 
 We welcome contributions from the community! All contributions must be released under the BSD 3-Clause license.

package/lib/Client.js

@@ -393,6 +393,80 @@ class Client {
     async getCollectionFields(name) {
         return await this._collections.getFields(name);
     }
+
+    /**
+     * Copy a collection into a new name (schema + documents).
+     *
+     * @param {string} sourceName
+     * @param {string} targetName
+     * @param {object} options
+     * @returns {Promise<Response>}
+     */
+    async copyCollection(sourceName, targetName, options = {}) {
+        const batchSize = Number.isInteger(options.batch_size) ? options.batch_size
+            : (Number.isInteger(options.batchSize) ? options.batchSize : 500);
+
+        const sourceResponse = await this._collections.get(sourceName);
+        if (sourceResponse.getStatusCode() !== 200) {
+            return sourceResponse;
+        }
+
+        const source = sourceResponse.getBody();
+        const schema = {};
+
+        if (source && source.fields && typeof source.fields === 'object' && !Array.isArray(source.fields) && Object.keys(source.fields).length > 0) {
+            const fieldNames = Object.keys(source.fields).sort();
+            schema.fields = fieldNames.map(name => ({ name, type: typeof source.fields[name] === 'string' ? source.fields[name] : 'string' }));
+        } else if (source && Array.isArray(source.searchable_fields) && source.searchable_fields.length > 0) {
+            schema.searchable_fields = source.searchable_fields;
+        } else {
+            schema.searchable_fields = ['title', 'content'];
+        }
+
+        if (source && Array.isArray(source.filterable_fields)) {
+            schema.filterable_fields = source.filterable_fields;
+        }
+        if (source && Array.isArray(source.sortable_fields)) {
+            schema.sortable_fields = source.sortable_fields;
+        }
+
+        if (source && source.metadata && typeof source.metadata === 'object' && !Array.isArray(source.metadata)) {
+            for (const [key, value] of Object.entries(source.metadata)) {
+                if (typeof key === 'string' && key.startsWith('_')) {
+                    schema[key] = value;
+                }
+            }
+        }
+
+        const createResponse = await this._collections.create(targetName, schema);
+        if (createResponse.getStatusCode() !== 201) {
+            return createResponse;
+        }
+
+        let offset = 0;
+
+        while (true) {
+            const listResponse = await this._documents.list(sourceName, { offset, limit: batchSize });
+            if (listResponse.getStatusCode() !== 200) {
+                return listResponse;
+            }
+
+            const body = listResponse.getBody() || {};
+            const documents = Array.isArray(body.documents) ? body.documents : [];
+            if (documents.length === 0) {
+                break;
+            }
+
+            const importResponse = await this._documents.import(targetName, documents);
+            if (!importResponse.isSuccess || !importResponse.isSuccess()) {
+                return importResponse;
+            }
+
+            offset += documents.length;
+        }
+
+        return createResponse;
+    }
     
     // ============================================================================
     // DOCUMENTS API
@@ -429,6 +503,30 @@ class Client {
         return await this._documents.get(collectionName, documentId);
     }
 
+    /**
+     * Copy a document to a new ID within the same collection.
+     *
+     * @param {string} collectionName
+     * @param {string} sourceId
+     * @param {string} targetId
+     * @returns {Promise<Response>}
+     */
+    async copyDocument(collectionName, sourceId, targetId) {
+        return await this._documents.copy(collectionName, sourceId, targetId);
+    }
+
+    /**
+     * Fetch most-recent documents (by timestamp desc).
+     *
+     * @param {string} collectionName
+     * @param {number} limit
+     * @param {number} offset
+     * @returns {Promise<Response>}
+     */
+    async recentDocuments(collectionName, limit = 20, offset = 0) {
+        return await this._documents.recent(collectionName, limit, offset);
+    }
+
     /**
      * Export documents from a collection.
      *
@@ -473,6 +571,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/Documents.js

@@ -7,6 +7,7 @@
  */
 
 const Validator = require('../utils/Validator');
+const Response = require('./Response');
 const PDFParser = require('../utils/PDFParser');
 const CSVParser = require('../utils/CSVParser');
 
@@ -167,16 +168,93 @@ class Documents {
         Validator.validateCollectionName(collectionName);
         
         // Validate each document in the array
-        if (Array.isArray(documents)) {
-            for (const doc of documents) {
-                Validator.validateDocumentFields(doc);
-            }
+        if (!Array.isArray(documents)) {
+            throw new Error('Documents import payload must be an array');
+        }
+
+        for (const doc of documents) {
+            Validator.validateDocumentFields(doc);
         }
         
-        // Server expects {documents: [...]} format
-        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/import`, {
+        // 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
         });
+
+        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);
+                const status = response.getStatusCode();
+                if (status !== 201) {
+                    return response;
+                }
+                inserted += 1;
+            }
+
+            return new Response(201, { imported: inserted, fallback: true });
+        }
+
+        return bulkResponse;
+    }
+
+    /**
+     * Copy one document to a new ID within the same collection.
+     *
+     * @param {string} collectionName
+     * @param {string} sourceId
+     * @param {string} targetId
+     * @returns {Promise<Response>}
+     */
+    async copy(collectionName, sourceId, targetId) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(sourceId);
+        Validator.validateDocumentId(targetId);
+
+        if (sourceId === targetId) {
+            throw new Error('Source and target document ids must differ');
+        }
+
+        const targetCheck = await this.get(collectionName, targetId);
+        if (targetCheck.getStatusCode() === 200) {
+            return targetCheck;
+        }
+        if (targetCheck.getStatusCode() !== 404) {
+            return targetCheck;
+        }
+
+        const sourceResponse = await this.get(collectionName, sourceId);
+        if (sourceResponse.getStatusCode() !== 200) {
+            return sourceResponse;
+        }
+
+        const doc = { ...sourceResponse.getBody(), id: targetId };
+        delete doc.collection_id;
+        delete doc.score;
+
+        const imported = await this.import(collectionName, [doc]);
+        return imported;
+    }
+
+    /**
+     * Convenience helper to fetch most-recent documents (by timestamp desc).
+     *
+     * @param {string} collectionName
+     * @param {number} limit
+     * @param {number} offset
+     * @returns {Promise<Response>}
+     */
+    async recent(collectionName, limit = 20, offset = 0) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validatePagination(offset, limit);
+
+        const sql = `select * from ${collectionName} order by timestamp desc limit ${limit} offset ${offset}`;
+        return await this.request.execute(
+            'GET',
+            `/collections/${encodeURIComponent(collectionName)}/documents/search`,
+            null,
+            { sql }
+        );
     }
 
     /**

package/lib/Keys.js

@@ -35,7 +35,7 @@ class Keys {
         if (!id) {
             throw new Error('Key ID is required');
         }
-        return await this.request.execute('GET', `/keys/${id}`);
+        return await this.request.execute('GET', `/keys/${encodeURIComponent(id)}`);
     }
     
     /**
@@ -64,7 +64,7 @@ class Keys {
         if (!id) {
             throw new Error('Key ID is required');
         }
-        return await this.request.execute('DELETE', `/keys/${id}`);
+        return await this.request.execute('DELETE', `/keys/${encodeURIComponent(id)}`);
     }
     
     /**
@@ -78,7 +78,7 @@ class Keys {
         if (!id) {
             throw new Error('Key ID is required');
         }
-        return await this.request.execute('PUT', `/keys/${id}`, params);
+        return await this.request.execute('PUT', `/keys/${encodeURIComponent(id)}`, params);
     }
 }
 

package/lib/Request.js

@@ -47,20 +47,33 @@ class Request {
         
         // Add query parameters
         Object.keys(queryParams).forEach(key => {
-            if (queryParams[key] !== undefined && queryParams[key] !== null) {
-                url.searchParams.append(key, queryParams[key]);
+            const value = queryParams[key];
+            if (value === undefined || value === null) {
+                return;
             }
+
+            if (Array.isArray(value)) {
+                url.searchParams.append(key, value.join(','));
+                return;
+            }
+
+            if (typeof value === 'object') {
+                url.searchParams.append(key, JSON.stringify(value));
+                return;
+            }
+
+            url.searchParams.append(key, value);
         });
         
         const headers = {
-            'Content-Type': 'application/json',
             'Accept': 'application/json'
         };
         
         // Prepare body string if present
         let bodyStr = null;
-        if (body !== null) {
+        if (body !== null && body !== undefined) {
             bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
+            headers['Content-Type'] = 'application/json';
             headers['Content-Length'] = Buffer.byteLength(bodyStr);
         }
         

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,14 +72,29 @@ class SAM {
         return await this.request.execute('GET', '/sam/status', null, queryParams);
     }
 
+    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 = {}) {
-        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
-            throw new Error('SAM history params must be an object');
+        this._validateParams(params, 'SAM history params');
+        const safeLimit = Number(limit);
+        if (!Number.isInteger(safeLimit) || safeLimit < 1) {
+            throw new Error('SAM history limit must be a positive integer');
         }
 
         const queryParams = {
             ...params,
-            limit: Number(limit)
+            limit: safeLimit
         };
 
         if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
@@ -66,6 +104,71 @@ 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');
+        const safeOffset = Number(offset);
+        const safeLimit = Number(limit);
+
+        if (!Number.isInteger(safeOffset) || safeOffset < 0) {
+            throw new Error('SAM document offset must be a non-negative integer');
+        }
+        if (!Number.isInteger(safeLimit) || safeLimit < 1) {
+            throw new Error('SAM document limit must be a positive integer');
+        }
+
+        return await this.request.execute('GET', '/sam/documents', null, {
+            ...params,
+            collection: collectionName,
+            offset: safeOffset,
+            limit: safeLimit
+        });
+    }
+
+    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.3",
   "description": "Node.js client library for hlquery search engine",
   "main": "index.js",
   "type": "commonjs",

package/test/offline-smoke.js

@@ -9,6 +9,7 @@ const Request = require('../lib/Request');
 const Response = require('../lib/Response');
 const Config = require('../utils/Config');
 const Validator = require('../utils/Validator');
+const CSVParser = require('../utils/CSVParser');
 
 async function main() {
   assert.strictEqual(typeof Hlquery, 'function', 'default export should be the Client constructor');
@@ -23,7 +24,11 @@ async function main() {
   Validator.validateSearchParams({ limit: 10, offset: 0 });
 
   assert.throws(() => Validator.validateCollectionName('123bad'), /letter or underscore/);
-  assert.throws(() => Validator.validateDocumentFields({ title: 'bad,value' }), /comma/);
+  assert.throws(() => Validator.validateSearchParams(null), /object/);
+  assert.throws(() => Validator.validateSearchParams({ limit: NaN }), /positive integer/);
+  assert.throws(() => Validator.validateSearchParams({ offset: 1.5 }), /non-negative integer/);
+  assert.throws(() => Validator.validateDocumentFields({ title: 'bad,value' }), /comma \(\,\)/);
+  assert.throws(() => CSVParser.parseCSV('a||b', '||'), /single character/);
 
   const response = new Response(200, { ok: true }, { 'content-type': 'application/json' });
   assert.strictEqual(response.isSuccess(), true);
@@ -36,15 +41,65 @@ async function main() {
       return;
     }
 
-    if (req.url === '/echo-auth') {
+    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.startsWith('/echo-auth')) {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({
         authorization: req.headers.authorization || null,
-        apiKey: req.headers['x-api-key'] || null
+        apiKey: req.headers['x-api-key'] || null,
+        contentType: req.headers['content-type'] || null,
+        url: req.url
       }));
       return;
     }
 
+    if (req.url === '/keys/key%2Fwith%20space') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ id: 'key/with space' }));
+      return;
+    }
+
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: 'not found' }));
   });
@@ -69,10 +124,63 @@ async function main() {
     const apiKeyEcho = await request.execute('GET', '/echo-auth');
     assert.strictEqual(apiKeyEcho.getBody().apiKey, 'scoped-key');
 
+    const queryEcho = await request.execute('GET', '/echo-auth', undefined, {
+      fields: ['title', 'body'],
+      filter: { published: true },
+      skip: null
+    });
+    assert.strictEqual(queryEcho.getBody().contentType, null);
+    assert.match(queryEcho.getBody().url, /fields=title%2Cbody/);
+    assert.match(queryEcho.getBody().url, /filter=%7B%22published%22%3Atrue%7D/);
+    assert.doesNotMatch(queryEcho.getBody().url, /skip=/);
+
     const client = new Client(`http://127.0.0.1:${port}`);
     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');
+    await assert.rejects(() => client.sam().history(null, 0), /positive integer/);
+    await assert.rejects(() => client.sam().listDocuments('books', NaN, 20), /non-negative integer/);
+
+    const keyResponse = await client.keys().get('key/with space');
+    assert.deepStrictEqual(keyResponse.getBody(), { id: 'key/with space' });
+    await assert.rejects(() => client.documents().import('books', { id: 'not-array' }), /array/);
   } finally {
     await new Promise((resolve) => server.close(resolve));
   }

package/utils/CSVParser.js

@@ -14,6 +14,7 @@ const { ValidationException } = require('../lib/Exceptions');
 class CSVParser {
     static parseFile(filePath, options = {}) {
         this.validateFilePath(filePath);
+        this.validateDelimiter(options.delimiter || ',');
 
         const resolvedPath = path.resolve(filePath);
         const stat = fs.statSync(resolvedPath);
@@ -62,6 +63,8 @@ class CSVParser {
     }
 
     static parseCSV(input, delimiter) {
+        this.validateDelimiter(delimiter);
+
         const rows = [];
         let row = [];
         let value = '';
@@ -155,6 +158,16 @@ class CSVParser {
             throw new ValidationException('CSV file path must be a non-empty string');
         }
     }
+
+    static validateDelimiter(delimiter) {
+        if (typeof delimiter !== 'string' || delimiter.length !== 1) {
+            throw new ValidationException('CSV delimiter must be a single character');
+        }
+
+        if (delimiter === '"' || delimiter === '\r' || delimiter === '\n') {
+            throw new ValidationException('CSV delimiter cannot be a quote or newline');
+        }
+    }
 }
 
 module.exports = CSVParser;

package/utils/Validator.js

@@ -69,35 +69,33 @@ class Validator {
      * Validate pagination parameters
      */
     static validatePagination(offset, limit) {
-        if (offset !== undefined && (typeof offset !== 'number' || offset < 0)) {
-            throw new ValidationException('Offset must be a non-negative number');
+        if (offset !== undefined && (!Number.isInteger(offset) || offset < 0)) {
+            throw new ValidationException('Offset must be a non-negative integer');
         }
-        if (limit !== undefined && (typeof limit !== 'number' || limit < 1)) {
-            throw new ValidationException('Limit must be a positive number');
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+            throw new ValidationException('Limit must be a positive integer');
         }
     }
     
     /**
      * Validate search parameters
      */
-    static validateSearchParams(params) {
-        if (params && typeof params !== 'object') {
+    static validateSearchParams(params = {}) {
+        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
             throw new ValidationException('Search parameters must be an object');
         }
         
-        if (params) {
-            if (params.offset !== undefined && (typeof params.offset !== 'number' || params.offset < 0)) {
-                throw new ValidationException('Offset must be a non-negative number');
-            }
-            if (params.limit !== undefined && (typeof params.limit !== 'number' || params.limit < 1)) {
-                throw new ValidationException('Limit must be a positive number');
-            }
-            if (params.from !== undefined && (typeof params.from !== 'number' || params.from < 0)) {
-                throw new ValidationException('From must be a non-negative number');
-            }
-            if (params.size !== undefined && (typeof params.size !== 'number' || params.size < 1)) {
-                throw new ValidationException('Size must be a positive number');
-            }
+        if (params.offset !== undefined && (!Number.isInteger(params.offset) || params.offset < 0)) {
+            throw new ValidationException('Offset must be a non-negative integer');
+        }
+        if (params.limit !== undefined && (!Number.isInteger(params.limit) || params.limit < 1)) {
+            throw new ValidationException('Limit must be a positive integer');
+        }
+        if (params.from !== undefined && (!Number.isInteger(params.from) || params.from < 0)) {
+            throw new ValidationException('From must be a non-negative integer');
+        }
+        if (params.size !== undefined && (!Number.isInteger(params.size) || params.size < 1)) {
+            throw new ValidationException('Size must be a positive integer');
         }
     }
     
@@ -120,7 +118,7 @@ class Validator {
             // Check string values for commas
             if (typeof value === 'string' && value.includes(',')) {
                 throw new ValidationException(
-                    `Field '${key}' contains invalid character: comma (`,`). ` +
+                    `Field '${key}' contains invalid character: comma (,). ` +
                     `Commas are not allowed in field values. Use underscores (_) or spaces instead, or use arrays for multiple values.`
                 );
             }
@@ -130,7 +128,7 @@ class Validator {
                 for (const item of value) {
                     if (typeof item === 'string' && item.includes(',')) {
                         throw new ValidationException(
-                            `Field '${key}' contains invalid character: comma (`,`). ` +
+                            `Field '${key}' contains invalid character: comma (,). ` +
                             `Array items cannot contain commas. Use underscores (_) or spaces instead.`
                         );
                     }