hlquery-node-client 1.0.0 → 1.0.1

package/README.md

@@ -4,30 +4,40 @@
 
 <div align="center">
 
-**A modular Node.js client library for hlquery.**
+**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)
-[![node-api](https://img.shields.io/badge/GitHub-node--api-181717?logo=github&logoColor=white)](https://github.com/hlquery/node-api/stargazers)
+[![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)
 
 </div>
 
-# hlquery Node.js API Client
+### What is the hlquery Node.js API?
 
-### Installation
+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.
 
-Core client usage has no external dependencies. CSV support is built in.
+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.
+
+### 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
 npm install hlquery-node-client
 ```
 
-```javascript
-const Client = require('hlquery-node-client');
-```
-
-For local development in this repository:
+For local development inside this repository:
 
 ```javascript
 const Client = require('./lib/Client');
@@ -38,9 +48,9 @@ const Client = require('./lib/Client');
 ```javascript
 const Client = require('hlquery-node-client');
 
-const client = new Client(process.env.HLQ_BASE_URL || 'http://localhost:9200', {
+const client = new Client(process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200', {
   token: process.env.HLQ_TOKEN,
-  auth_method: 'bearer' // or 'api-key'
+  auth_method: 'bearer'
 });
 
 const health = await client.system().health();
@@ -48,269 +58,82 @@ console.log('status:', health.getStatusCode());
 
 const collections = await client.collections().list(0, 10);
 console.log(collections.getBody());
-
-await client.collections().create('books', {
-  fields: [
-    { name: 'title', type: 'string' },
-    { name: 'content', type: 'string' }
-  ]
-});
-
-await client.documents().add('books', {
-  id: 'book-1',
-  title: 'Designing Data-Intensive Applications',
-  content: 'Distributed systems, data models, replication, and indexing.'
-});
-
-const results = await client.searchApi().search('books', {
-  q: 'distributed systems',
-  query_by: 'title,content',
-  limit: 10
-});
-console.log(results.getBody());
 ```
 
-You can also set authentication later:
+### Auth
 
 ```javascript
-client.setAuthToken('your_token_here', 'bearer');
-client.setAuthToken('your_api_key_here', 'api-key');
-```
-
-### API Surface
-
-Use nested API objects: `client -> resource -> action`, for example `client.collections().create(...)`.
-
-```javascript
-client.system().health();
-client.system().stats();
-client.system().info();
-client.system().status();
-client.system().metrics();
-client.system().connections();
-client.system().rocksdb();
-
-client.collections().list(offset, limit);
-client.collections().get(name);
-client.collections().create(name, schema);
-client.collections().update(name, schema);
-client.collections().delete(name);
-client.collections().getFields(name);
-
-client.documents().list(collection, params);
-client.documents().get(collection, id);
-client.documents().add(collection, document);
-client.documents().update(collection, id, document);
-client.documents().delete(collection, id);
-client.documents().import(collection, documents);
-client.documents().export(collection, params);
-client.documents().facetCounts(collection, params);
-client.documents().addCSV(collection, filePath, options);
-
-client.searchApi().search(collection, params);
-client.searchApi().vectorSearch(collection, params);
-client.searchApi().multiSearch(searches);
-client.searchApi().globalSearch(params);
-client.searchApi().sql(collection, sql);
-
-client.aliases().create(name, params);
-client.aliases().update(name, params);
-client.aliases().delete(name);
-client.synonyms().create(collection, id, synonym);
-client.stopwords().create(collection, params);
-client.overrides().create(collection, id, override);
-client.keys().create(params);
-client.executeRequest(method, path, body, query);
-```
-
-### Collections
-
-```javascript
-const collections = client.collections();
-
-await collections.create('books', {
-  fields: [
-    { name: 'title', type: 'string' },
-    { name: 'content', type: 'string' },
-    { name: 'category', type: 'string', facet: true }
-  ]
+const client = new Client('http://localhost:9200', {
+  token: 'your_token_here',
+  auth_method: 'bearer'
 });
 
-await collections.get('books');
-await collections.getFields('books');
-await collections.update('books', schema);
-await collections.delete('books');
-```
-
-### Documents
-
-```javascript
-const documents = client.documents();
-
-await documents.add('books', {
-  id: 'book-1',
-  title: 'Designing Data-Intensive Applications',
-  content: 'Distributed systems, data models, replication, and indexing.'
-});
-
-await documents.update('books', 'book-1', { title: 'DDIA' });
-await documents.delete('books', 'book-1');
-
-await documents.import('books', [
-  { id: 'book-2', title: 'Database Internals', content: 'Storage engines and indexes.' }
-]);
-
-await documents.addCSV('reports', './files/metrics.csv', {
-  id: 'metrics_q1',
-  document: { source_type: 'csv' }
-});
+client.setAuthToken('your_token_here', 'bearer');
+client.setAuthToken('your_api_key_here', 'api-key');
 ```
 
-`addCSV()` parses a local CSV file, flattens rows into text, and indexes the generated document. It does not require extra packages.
+### SAM
 
-### Search
+SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.
 
 ```javascript
-const search = client.searchApi();
-
-await search.search('books', {
-  q: 'title:database OR content:index*',
-  query_by: 'title,content',
-  filter_by: 'category:technical',
-  sort_by: '_text_match:desc',
-  facet_by: 'category',
-  limit: 10,
-  offset: 0
-});
-
-await search.multiSearch([
-  { collection: 'books', q: 'database', query_by: 'title,content' },
-  { collection: 'articles', q: 'database', query_by: 'title,body' }
-]);
+const sam = client.sam();
 
-await search.vectorSearch('books', {
-  vector_query: [0.12, 0.34, 0.56],
-  vector_by: 'embedding',
+const status = await sam.status('books');
+const history = await sam.history('books', 5);
+const results = await sam.search('books', 'distributed systems', {
   limit: 10
 });
-```
-
-Common search parameters:
 
-- `q`: query string, including field clauses, phrases, boolean operators, and wildcards.
-- `query_by`: searchable fields as a string or array.
-- `filter_by`: filter expression.
-- `sort_by`: sort expression.
-- `facet_by`: facet fields.
-- `limit` / `offset`: pagination.
-- `page` / `per_page`: alternate pagination.
+console.log(status.getBody());
+console.log(history.getBody());
+console.log(results.getBody());
+```
 
 ### SQL
 
-SQL queries are supported through the search API and through the interactive talk shell.
-
 ```javascript
-const response = await client.searchApi().sql(
-  'products',
-  'SELECT id, title, price FROM products ORDER BY price DESC LIMIT 5;'
-);
+const sql = client.sql();
 
-const rows = response.getBody().rows || [];
+const rows = await sql.query('SHOW COLLECTIONS;');
+const books = await sql.search(
+  'books',
+  'SELECT id, title FROM books ORDER BY title ASC LIMIT 3;'
+);
 
-await client.sql('SHOW COLLECTIONS;');
-await client.execSql("INSERT INTO products (id, title) VALUES ('sku-9', 'Camp Stove');");
+console.log(rows.getBody());
+console.log(books.getBody());
 ```
 
-Talk shell example:
-
-```text
-localhost:9200> sql: select title,id from music LIMIT 2;
-
-SQL rows for `select title,id from music LIMIT 2;`:
-+--------------------------------+------------------------------------------+
-| id                             | title                                    |
-+--------------------------------+------------------------------------------+
-| music_artist-profile-beyonce   | Artist Profile: Beyonce                  |
-| music_artist-profile-kendrick- | Artist Profile: Kendrick Lamar           |
-| lamar                          |                                          |
-+--------------------------------+------------------------------------------+
-2 results shown.
-Search completed in 19 ms.
-```
+### Reduce Text Example
 
-### Search Management
+Use the raw request helper for custom module routes:
 
 ```javascript
-const aliases = client.aliases();
-const synonyms = client.synonyms();
-const stopwords = client.stopwords();
-const overrides = client.overrides();
-
-await aliases.create('books_current', { collection_name: 'books_v2' });
-
-await synonyms.create('books', 'cars', {
-  root: 'car',
-  synonyms: ['auto', 'automobile']
+const response = await client.executeRequest('GET', '/modules/<name>/<route>', null, {
+  q: 'example query'
 });
 
-await stopwords.create('books', { word: 'the' });
-
-await overrides.create('books', 'boost_featured', {
-  rule: { query: 'featured', match: 'exact' },
-  includes: [{ id: 'doc-1', position: 1 }],
-  excludes: []
-});
+console.log(response.getBody());
 ```
 
-### Responses
+### Contributing
 
-All API methods return a `Response` object.
+We welcome contributions from the community! All contributions must be released under the BSD 3-Clause license.
 
-```javascript
-const response = await client.system().health();
-
-response.getStatusCode();
-response.getBody();
-response.isSuccess();
-response.isError();
-response.getError();
-response.toArray();
-```
+### How to Contribute
 
-### Errors
-
-```javascript
-const { RequestException, AuthenticationException, ValidationException } = require('./lib/Exceptions');
-
-try {
-  const result = await client.searchApi().search('books', { q: 'test' });
-  if (result.isError()) {
-    console.log(result.getError());
-  }
-} catch (error) {
-  if (error instanceof RequestException) {
-    console.log('request failed:', error.message, error.statusCode);
-  } else if (error instanceof AuthenticationException) {
-    console.log('auth failed:', error.message);
-  } else if (error instanceof ValidationException) {
-    console.log('validation failed:', error.message);
-  } else {
-    throw error;
-  }
-}
-```
+- Check existing [issues](https://github.com/hlquery/hlquery/issues) or create new ones
+- Contribute to client libraries (Node.js, Go, Java, Python, PHP, Ruby, Rust, Perl, C++)
+- Test and report bugs
+- Improve documentation
 
-### Requirements
+### Community
 
-- Node.js >= 12.0.0
-- No external dependencies required for core client usage
+- 📖 [Documentation](https://docs.hlquery.com)
+- 🐦 [X (Twitter)](https://x.com/hlquery)
+- 📦 [GitHub](https://github.com/hlquery/hlquery)
 
-### Features
+### License
 
-- Modular classes for collections, documents, search, aliases, overrides, synonyms, stopwords, and system APIs.
-- Bearer token and X-API-Key authentication.
-- Flexible parameter formats.
-- Automatic searchable-field detection when fields are not specified.
-- SQL helpers for collection-bound and top-level SQL execution.
-- Response wrapper with status, body, and error helpers.
-- Built-in validation and async/await support.
+hlquery is licensed under the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause).

package/example.js

@@ -14,6 +14,7 @@
  *   Commands:
  *     cols   - Run collections API examples
  *     docs   - Run documents API examples
+ *     sql    - Run SQL API examples
  *     open   - List and open collections (interactive)
  *     status - Show server health and status information
  *     help   - Show this help message
@@ -34,7 +35,7 @@ let collectionName = null;
 
 if (process.argv.length > 2) {
     const firstArg = process.argv[2];
-    if (['cols', 'docs', 'open', 'status', 'help', 'all'].includes(firstArg)) {
+    if (['cols', 'docs', 'sql', 'open', 'status', 'help', 'all'].includes(firstArg)) {
         command = firstArg;
         // Parse pagination for cols command: cols [offset] [limit] [token]
         if (command === 'cols' && process.argv.length >= 4) {
@@ -84,6 +85,7 @@ if (command === 'help') {
     console.log('  docs   - Run documents API examples');
     console.log('          Usage: docs [collection_name] [token]');
     console.log('          Example: docs my_collection');
+    console.log('  sql    - Run SQL API examples');
     console.log('  open   - List and open collections (interactive)');
     console.log('  status - Show server health and status information');
     console.log('  help   - Show this help message');
@@ -221,6 +223,34 @@ async function main() {
         process.exit(0);
     }
     
+    // ----------------------------------------------------------------====================================
+    // SQL API
+    // ----------------------------------------------------------------====================================
+    if (command === 'all' || command === 'sql') {
+        console.log('\n' + '#'.repeat(70));
+        console.log('# SQL API');
+        console.log('#'.repeat(70) + '\n');
+
+        try {
+            // GET /sql
+            printResult('GET /sql (SHOW COLLECTIONS)', await client.sql('SHOW COLLECTIONS;'));
+
+            // Collection-bound SQL SELECT through /collections/{name}/documents/search
+            const sqlCollection = await getFirstCollection(client);
+            if (!sqlCollection) {
+                console.log('No collections available - skipping collection-bound SQL test\n');
+            } else {
+                const query = `SELECT id FROM ${sqlCollection} LIMIT 5;`;
+                printResult(
+                    'GET /collections/{name}/documents/search (SQL SELECT)',
+                    await client.sqlSearch(sqlCollection, query)
+                );
+            }
+        } catch (error) {
+            console.log(`Error in SQL API: ${error.message}\n`);
+        }
+    }
+
     // ----------------------------------------------------------------====================================
     // System APIs (only for 'all' command)
     // ----------------------------------------------------------------====================================
@@ -621,6 +651,7 @@ async function main() {
         console.log('    docs   - Run documents API examples');
         console.log('             Usage: docs [collection_name] [token]');
         console.log('             Example: docs my_collection');
+        console.log('    sql    - Run SQL API examples');
         console.log('    open   - List and open collections');
         console.log('    status - Show server health and status information');
         console.log('    help   - Show help message');

package/examples/sam.js

@@ -0,0 +1,39 @@
+/**
+ * Basic SAM example for the hlquery Node.js client.
+ */
+
+const Client = require('../index');
+
+async function main() {
+    const baseUrl = process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    const token = process.argv[2] || null;
+    const collection = process.argv[3] || 'music';
+    const query = process.argv[4] || 'queen of pop';
+
+    const client = new Client(baseUrl);
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
+
+    const sam = client.sam();
+
+    const status = await sam.status(collection);
+    console.log('=== SAM STATUS ===');
+    console.log(status.getBody());
+    console.log('');
+
+    const history = await sam.history(collection, 5);
+    console.log('=== SAM HISTORY ===');
+    console.log(history.getBody());
+    console.log('');
+
+    const results = await sam.search(collection, query, { limit: 10 });
+    console.log('=== SAM SEARCH ===');
+    console.log(results.getBody());
+}
+
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/examples/sql.js

@@ -0,0 +1,31 @@
+/**
+ * SQL Examples
+ *
+ * Demonstrates top-level and collection-bound SQL usage with the hlquery Node.js client
+ */
+
+const Client = require('../lib/Client');
+
+async function main() {
+    const client = new Client('http://localhost:9200');
+
+    // Top-level SQL through /sql
+    const rows = await client.sql('SHOW COLLECTIONS;');
+    console.log('SHOW COLLECTIONS:', rows.getBody());
+
+    // Top-level SQL statement execution through POST /sql
+    const execResult = await client.execSql(
+        "INSERT INTO logs_archive (id, title) VALUES ('row-1', 'warm cache');"
+    );
+    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;',
+        { highlight: false }
+    );
+    console.log('Products SQL results:', products.getBody());
+}
+
+main().catch(console.error);

package/index.js

@@ -24,6 +24,7 @@ module.exports.Overrides = require('./lib/Overrides');
 module.exports.Synonyms = require('./lib/Synonyms');
 module.exports.Stopwords = require('./lib/Stopwords');
 module.exports.System = require('./lib/System');
+module.exports.SAM = require('./lib/SAM');
 
 // Export exceptions
 module.exports.Exceptions = require('./lib/Exceptions');

package/lib/Client.js

@@ -17,6 +17,7 @@ const Overrides = require('./Overrides');
 const Synonyms = require('./Synonyms');
 const Stopwords = require('./Stopwords');
 const System = require('./System');
+const SAM = require('./SAM');
 const Config = require('../utils/Config');
 
 /**
@@ -49,6 +50,7 @@ class Client {
         this._synonyms = new Synonyms(this.request);
         this._stopwords = new Stopwords(this.request);
         this._system = new System(this.request);
+        this._sam = new SAM(this.request);
     }
     
     /**
@@ -462,6 +464,15 @@ class Client {
         return this._search;
     }
 
+    /**
+     * Get SAM API instance
+     *
+     * @returns {SAM}
+     */
+    sam() {
+        return this._sam;
+    }
+
     /**
      * Get aliases API instance
      *

package/lib/SAM.js

@@ -0,0 +1,71 @@
+/**
+ * hlquery Node.js Client - SAM API
+ *
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ *
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+const Validator = require('../utils/Validator');
+
+/**
+ * SAM API operations
+ */
+class SAM {
+    constructor(request) {
+        this.request = request;
+    }
+
+    async search(collectionName, query, params = {}) {
+        Validator.validateCollectionName(collectionName);
+
+        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');
+        }
+
+        return await this.request.execute('GET', '/sam/search', null, {
+            ...params,
+            collection: collectionName,
+            q: query
+        });
+    }
+
+    async status(collectionName = null, params = {}) {
+        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+            throw new Error('SAM status params must be an object');
+        }
+
+        const queryParams = { ...params };
+
+        if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
+            Validator.validateCollectionName(collectionName);
+            queryParams.collection = collectionName;
+        }
+
+        return await this.request.execute('GET', '/sam/status', null, queryParams);
+    }
+
+    async history(collectionName = null, limit = 100, params = {}) {
+        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+            throw new Error('SAM history params must be an object');
+        }
+
+        const queryParams = {
+            ...params,
+            limit: Number(limit)
+        };
+
+        if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
+            Validator.validateCollectionName(collectionName);
+            queryParams.collection = collectionName;
+        }
+
+        return await this.request.execute('GET', '/sam/history', null, queryParams);
+    }
+}
+
+module.exports = SAM;

package/lib/conformance.js

@@ -44,6 +44,9 @@ 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: '/sam/search', methods: ['GET'], status: 'supported', client: 'sam.search' },
+    { path: '/sam/status', methods: ['GET'], status: 'supported', client: 'sam.status' },
+    { path: '/sam/history', methods: ['GET'], status: 'supported', client: 'sam.history' },
     { 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' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlquery-node-client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Node.js client library for hlquery search engine",
   "main": "index.js",
   "type": "commonjs",
@@ -9,6 +9,7 @@
     "test:conformance": "node ../tests/test_node_client_conformance.js",
     "test:offline": "node test/offline-smoke.js",
     "example": "node example.js",
+    "example:sql": "node examples/sql.js",
     "example:pdf": "node examples/pdf.js",
     "example:csv": "node examples/csv.js"
   },
@@ -28,15 +29,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cferry/hlquery.git"
-  },
-  "directories": {
-    "example": "examples",
-    "lib": "lib",
-    "test": "test"
-  },
-  "bugs": {
-    "url": "https://github.com/cferry/hlquery/issues"
-  },
-  "homepage": "https://github.com/cferry/hlquery#readme"
+    "url": "https://github.com/cferry/hlquery"
+  }
 }