hlquery-node-client 1.0.2 → 1.0.4

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)
+[![hlquery](https://img.shields.io/badge/GitHub-hlquery-blue?logo=github&logoColor=white&labelColor=000000)](https://github.com/hlquery/hlquery)
+[![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
@@ -143,7 +139,7 @@ console.log(results.getBody());
 ```javascript
 const rows = await client.sql('SHOW COLLECTIONS;');
 const execResult = await client.execSql(
-  "INSERT INTO logs_archive (id, title) VALUES ('row-1', 'warm cache');"
+  "INSERT INTO books (id, title) VALUES ('book_4', 'Inserted via SQL');"
 );
 const books = await client.sqlSearch(
   'books',
@@ -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/example.js

@@ -161,11 +161,6 @@ async function main() {
     // Create client
     const client = new Client(baseUrl);
     
-    // Optional: Set authentication token if provided
-    // Uncomment and set token if your server requires authentication:
-    // const authToken = 'your_token_here';
-    // client.setAuthToken(authToken, 'bearer');
-    
     if (testToken) {
         client.setAuthToken(testToken, 'bearer');
         console.log(`Using authentication token: ${testToken.substring(0, 8)}...\n`);

package/examples/basic_usage.js

@@ -7,8 +7,15 @@
 const Client = require('../lib/Client');
 
 async function main() {
+    const baseUrl = process.argv[2] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[3] || process.env.HLQUERY_TOKEN || null;
+
     // Initialize client
-    const client = new Client('http://localhost:9200');
+    const client = new Client(baseUrl);
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
     
     // Health check
     const health = await client.health();
@@ -22,14 +29,7 @@ async function main() {
         console.log(`Found ${body.collections ? body.collections.length : 0} collections`);
     }
     
-    // With authentication
-    const authenticatedClient = new Client('http://localhost:9200', {
-        token: 'your_token_here',
-        auth_method: 'bearer'
-    });
-    
-    // Or set token dynamically
-    client.setAuthToken('your_token_here', 'bearer');
+    console.log('Base URL:', baseUrl);
 }
 
 main().catch(console.error);

package/examples/collections.js

@@ -7,16 +7,19 @@
 const Client = require('../lib/Client');
 
 async function main() {
-    const client = new Client('http://localhost:9200');
+    const baseUrl = process.argv[2] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[3] || process.env.HLQUERY_TOKEN || null;
+    const client = new Client(baseUrl);
+    const collectionName = `node_collections_example_${process.pid}`;
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
     
     // List collections
     const collections = await client.collections().list(0, 10);
     console.log('Collections:', collections.getBody());
     
-    // Get collection
-    const collection = await client.collections().get('my_collection');
-    console.log('Collection details:', collection.getBody());
-    
     // Create collection
     const schema = {
         fields: [
@@ -25,15 +28,19 @@ async function main() {
             { name: 'embedding', type: 'float[]' }
         ]
     };
-    const createResult = await client.collections().create('new_collection', schema);
+    const createResult = await client.collections().create(collectionName, schema);
     console.log('Create result:', createResult.getBody());
+
+    // Get collection
+    const collection = await client.collections().get(collectionName);
+    console.log('Collection details:', collection.getBody());
     
     // Get formatted fields
-    const fields = await client.collections().getFields('my_collection');
+    const fields = await client.collections().getFields(collectionName);
     console.log('Formatted fields:', fields.getBody());
     
     // Delete collection
-    const deleteResult = await client.collections().delete('collection_name');
+    const deleteResult = await client.collections().delete(collectionName);
     console.log('Delete result:', deleteResult.getBody());
 }
 

package/examples/csv.js

@@ -2,21 +2,23 @@
  * CSV Parsing Example
  *
  * Usage:
- *   node examples/csv.js <collection> <csv-path> [token]
+ *   node examples/csv.js <collection> <csv-path> [base-url] [token]
  */
 
 const path = require('path');
 const Client = require('../lib/Client');
 
 async function main() {
-    const [, , collectionName, csvPath, token] = process.argv;
+    const [, , collectionName, csvPath, baseUrlArg, tokenArg] = process.argv;
 
     if (!collectionName || !csvPath) {
-        console.error('Usage: node examples/csv.js <collection> <csv-path> [token]');
+        console.error('Usage: node examples/csv.js <collection> <csv-path> [base-url] [token]');
         process.exit(1);
     }
 
-    const client = new Client('http://localhost:9200');
+    const baseUrl = baseUrlArg || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = tokenArg || process.env.HLQUERY_TOKEN || null;
+    const client = new Client(baseUrl);
 
     if (token) {
         client.setAuthToken(token, 'bearer');

package/examples/documents.js

@@ -7,38 +7,53 @@
 const Client = require('../lib/Client');
 
 async function main() {
-    const client = new Client('http://localhost:9200');
+    const baseUrl = process.argv[2] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[3] || process.env.HLQUERY_TOKEN || null;
+    const client = new Client(baseUrl);
+    const collectionName = `node_documents_example_${process.pid}`;
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
+
+    await client.collections().delete(collectionName);
+    await client.collections().create(collectionName, {
+        fields: [
+            { name: 'title', type: 'string' },
+            { name: 'content', type: 'string' }
+        ]
+    });
+
+    // Add document
+    const newDoc = {
+        id: 'doc_1',
+        title: 'New Document',
+        content: 'Document content'
+    };
+    const addResult = await client.documents().add(collectionName, newDoc);
+    console.log('Add result:', addResult.getBody());
     
     // List documents
-    const docs = await client.documents().list('collection', {
+    const docs = await client.documents().list(collectionName, {
         offset: 0,
         limit: 10
     });
     console.log('Documents:', docs.getBody());
     
     // Get document
-    const doc = await client.documents().get('collection', 'doc_id');
+    const doc = await client.documents().get(collectionName, 'doc_1');
     console.log('Document:', doc.getBody());
     
-    // Add document
-    const newDoc = {
-        id: 'doc_1',
-        title: 'New Document',
-        content: 'Document content'
-    };
-    const addResult = await client.documents().add('collection', newDoc);
-    console.log('Add result:', addResult.getBody());
-    
     // Update document
     const updatedDoc = {
         title: 'Updated Document',
         content: 'Updated content'
     };
-    const updateResult = await client.documents().update('collection', 'doc_id', updatedDoc);
+    const updateResult = await client.documents().update(collectionName, 'doc_1', updatedDoc);
     console.log('Update result:', updateResult.getBody());
     
     // Delete document
-    const deleteResult = await client.documents().delete('collection', 'doc_id');
+    const deleteResult = await client.documents().delete(collectionName, 'doc_1');
     console.log('Delete result:', deleteResult.getBody());
     
     // Bulk import
@@ -47,8 +62,11 @@ async function main() {
         { id: 'doc2', title: 'Doc 2' },
         { id: 'doc3', title: 'Doc 3' }
     ];
-    const importResult = await client.documents().import('collection', bulkDocs);
+    const importResult = await client.documents().import(collectionName, bulkDocs);
     console.log('Import result:', importResult.getBody());
+
+    const cleanup = await client.collections().delete(collectionName);
+    console.log('Cleanup result:', cleanup.getBody());
 }
 
 main().catch(console.error);

package/examples/flush.js

@@ -12,7 +12,13 @@
 const Client = require('../lib/Client');
 
 async function main() {
-    const client = new Client('http://localhost:9200');
+    const baseUrl = process.argv[2] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[3] || process.env.HLQUERY_TOKEN || null;
+    const client = new Client(baseUrl);
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
 
     console.log('='.repeat(70));
     console.log('FLUSH EXAMPLE');

package/examples/keys.js

@@ -6,13 +6,15 @@
 
 const Client = require('../index');
 
-// Replace with your hlquery master admin token
-const ADMIN_TOKEN = 'your_admin_token_here';
-const BASE_URL = 'http://localhost:9200';
+const ADMIN_TOKEN = process.argv[2] || process.env.HLQUERY_ADMIN_TOKEN || process.env.HLQUERY_TOKEN || null;
+const BASE_URL = process.argv[3] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
 
 async function run() {
     try {
         const client = new Client(BASE_URL);
+        if (!ADMIN_TOKEN) {
+            throw new Error('Admin token required. Pass it as argv[2] or set HLQUERY_ADMIN_TOKEN.');
+        }
         client.setAuthToken(ADMIN_TOKEN);
 
         console.log('1. Creating a scoped search key for "products" collection...');

package/examples/pdf.js

@@ -3,21 +3,23 @@
  *
  * Usage:
  *   npm install
- *   node examples/pdf.js <collection> <pdf-path> [token]
+ *   node examples/pdf.js <collection> <pdf-path> [base-url] [token]
  */
 
 const path = require('path');
 const Client = require('../lib/Client');
 
 async function main() {
-    const [, , collectionName, pdfPath, token] = process.argv;
+    const [, , collectionName, pdfPath, baseUrlArg, tokenArg] = process.argv;
 
     if (!collectionName || !pdfPath) {
-        console.error('Usage: node examples/pdf.js <collection> <pdf-path> [token]');
+        console.error('Usage: node examples/pdf.js <collection> <pdf-path> [base-url] [token]');
         process.exit(1);
     }
 
-    const client = new Client('http://localhost:9200');
+    const baseUrl = baseUrlArg || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = tokenArg || process.env.HLQUERY_TOKEN || null;
+    const client = new Client(baseUrl);
 
     if (token) {
         client.setAuthToken(token, 'bearer');

package/examples/search.js

@@ -7,18 +7,41 @@
 const Client = require('../lib/Client');
 
 async function main() {
-    const client = new Client('http://localhost:9200');
+    const baseUrl = process.argv[2] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[3] || process.env.HLQUERY_TOKEN || null;
+    const collectionName = process.argv[4] || `node_search_example_${process.pid}`;
+    const client = new Client(baseUrl);
     const search = client.searchApi();
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
+
+    await client.collections().delete(collectionName);
+    await client.collections().create(collectionName, {
+        fields: [
+            { name: 'title', type: 'string' },
+            { name: 'content', type: 'string' },
+            { name: 'category', type: 'string' },
+            { name: 'price', type: 'float' },
+            { name: 'embedding', type: 'float[]' }
+        ]
+    });
+    await client.documents().import(collectionName, [
+        { id: 'prod_laptop_001', title: 'Laptop Computer', content: 'Portable work machine', category: 'electronics', price: 1299.99, embedding: [0.1, 0.2, 0.3, 0.4, 0.5] },
+        { id: 'prod_keyboard_001', title: 'Wireless Keyboard', content: 'Compact Bluetooth keyboard', category: 'electronics', price: 49.99, embedding: [0.2, 0.1, 0.4, 0.3, 0.5] },
+        { id: 'prod_notebook_001', title: 'Paper Notebook', content: 'Plain paper writing notebook', category: 'office', price: 9.99, embedding: [0.5, 0.4, 0.3, 0.2, 0.1] }
+    ]);
     
     // Simple search. The SDK uses the canonical /collections/{name}/search route.
-    const results = await search.search('collection_name', {
+    const results = await search.search(collectionName, {
         q: 'search query',
         query_by: 'title,content',
         limit: 10
     });
     
     // Search with filters
-    const filteredResults = await client.search('collection_name', {
+    const filteredResults = await client.search(collectionName, {
         q: 'query',
         query_by: 'title',
         filter_by: 'category:electronics',
@@ -28,49 +51,49 @@ async function main() {
     
     // Supported query semantics
     // Field-specific search
-    const fieldResults = await client.search('collection_name', {
+    const fieldResults = await client.search(collectionName, {
         q: 'title:laptop',
         query_by: 'title,content',
         limit: 10
     });
     
     // Boolean OR query
-    const orResults = await client.search('collection_name', {
+    const orResults = await client.search(collectionName, {
         q: 'title:laptop OR title:notebook',
         query_by: 'title,content',
         limit: 10
     });
     
     // Boolean NOT query
-    const notResults = await client.search('collection_name', {
+    const notResults = await client.search(collectionName, {
         q: 'title:laptop NOT title:refurbished',
         query_by: 'title,content',
         limit: 10
     });
     
     // Phrase search
-    const phraseResults = await client.search('collection_name', {
+    const phraseResults = await client.search(collectionName, {
         q: '"wireless keyboard"',
         query_by: 'title',
         limit: 10
     });
     
     // Wildcard search
-    const wildcardResults = await client.search('collection_name', {
+    const wildcardResults = await client.search(collectionName, {
         q: 'laptop*',
         query_by: 'title,content',
         limit: 10
     });
     
     // query_by restriction
-    const restrictedResults = await client.search('collection_name', {
+    const restrictedResults = await client.search(collectionName, {
         q: 'laptop',
         query_by: 'title',
         limit: 10
     });
     
     // Filter operators belong in filter_by
-    const combinedResults = await client.search('collection_name', {
+    const combinedResults = await client.search(collectionName, {
         q: '*',
         query_by: 'title,content',
         filter_by: 'price:>100&&category:electronics',
@@ -78,7 +101,7 @@ async function main() {
     });
     
     // Vector search
-    const vectorResults = await client.vectorSearch('collection_name', {
+    const vectorResults = await client.vectorSearch(collectionName, {
         body: {
             vector: [0.1, 0.2, 0.3, 0.4, 0.5],
             field_name: 'embedding',
@@ -91,11 +114,23 @@ async function main() {
     
     // Multi-search
     const multiResults = await search.multiSearch([
-        { collection: 'col1', q: 'query1', query_by: 'title' },
-        { collection: 'col2', q: 'query2', query_by: 'content' }
+        { collection: collectionName, q: 'laptop', query_by: 'title' },
+        { collection: collectionName, q: 'keyboard', query_by: 'content' }
     ]);
     
     console.log('Search results:', results.getBody());
+    console.log('Filtered results:', filteredResults.getBody());
+    console.log('Field results:', fieldResults.getBody());
+    console.log('Boolean OR results:', orResults.getBody());
+    console.log('Boolean NOT results:', notResults.getBody());
+    console.log('Phrase results:', phraseResults.getBody());
+    console.log('Wildcard results:', wildcardResults.getBody());
+    console.log('Restricted results:', restrictedResults.getBody());
+    console.log('Combined results:', combinedResults.getBody());
+    console.log('Vector results:', vectorResults.getBody());
+    console.log('Multi-search results:', multiResults.getBody());
+
+    await client.collections().delete(collectionName);
 }
 
 main().catch(console.error);

package/examples/sql.js

@@ -7,7 +7,28 @@
 const Client = require('../lib/Client');
 
 async function main() {
-    const client = new Client('http://localhost:9200');
+    const baseUrl = process.argv[2] || process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[3] || process.env.HLQUERY_TOKEN || null;
+    const collectionName = `node_sql_example_${process.pid}`;
+    const client = new Client(baseUrl);
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
+
+    await client.collections().delete(collectionName);
+    await client.collections().create(collectionName, {
+        fields: [
+            { name: 'title', type: 'string' },
+            { name: 'category', type: 'string' },
+            { name: 'price', type: 'float' }
+        ]
+    });
+    await client.documents().import(collectionName, [
+        { id: 'book_1', title: 'Algebra Basics', category: 'math', price: 19.99 },
+        { id: 'book_2', title: 'Geometry Proofs', category: 'math', price: 29.99 },
+        { id: 'book_3', title: 'Cooking Basics', category: 'food', price: 14.99 }
+    ]);
 
     // Top-level SQL through /sql
     const rows = await client.sql('SHOW COLLECTIONS;');
@@ -15,17 +36,20 @@ async function main() {
 
     // Top-level SQL statement execution through POST /sql
     const execResult = await client.execSql(
-        "INSERT INTO logs_archive (id, title) VALUES ('row-1', 'warm cache');"
+        `INSERT INTO ${collectionName} (id, title, category, price) VALUES ('book_4', 'Inserted via SQL', 'ops', 39.99);`
     );
     console.log('Exec result:', execResult.getBody());
 
     // Collection-bound SQL SELECT through /collections/{name}/documents/search
-    const products = await client.sqlSearch(
-        'products',
-        'SELECT id, title, price FROM products WHERE price > 100 ORDER BY price DESC LIMIT 3;',
+    const books = await client.sqlSearch(
+        collectionName,
+        `SELECT id, title, price FROM ${collectionName} WHERE price > 10 ORDER BY price DESC LIMIT 3;`,
         { highlight: false }
     );
-    console.log('Products SQL results:', products.getBody());
+    console.log('Books SQL results:', books.getBody());
+
+    const cleanup = await client.collections().delete(collectionName);
+    console.log('Cleanup:', cleanup.getBody());
 }
 
 main().catch(console.error);

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.4",
   "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.`
                         );
                     }