hlquery-node-client 1.0.2 → 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,17 +6,17 @@
 
 **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.
 
@@ -26,10 +26,6 @@ Use the Node.js client when you want hlquery calls to read like regular applicat
 
 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?
-
-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.
-
 ### Install
 
 ```bash
@@ -158,19 +154,6 @@ console.log(execResult.getBody());
 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'
-});
-
-/* Print the custom module route response body. */
-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.
      *

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

@@ -87,10 +87,14 @@ class SAM {
 
     async history(collectionName = null, limit = 100, params = {}) {
         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 !== '') {
@@ -122,12 +126,21 @@ class SAM {
     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: Number(offset),
-            limit: Number(limit)
+            offset: safeOffset,
+            limit: safeLimit
         });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlquery-node-client",
-  "version": "1.0.2",
+  "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);
@@ -78,15 +83,23 @@ async function main() {
       return;
     }
 
-    if (req.url === '/echo-auth') {
+    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' }));
   });
@@ -111,6 +124,16 @@ 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);
@@ -152,6 +175,12 @@ async function main() {
     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.`
                         );
                     }