hlquery-node-client 1.0.0 → 1.0.2

package/README.md

@@ -4,30 +4,39 @@
 
 <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.
 
-```bash
-npm install hlquery-node-client
-```
+### Why use it?
 
-```javascript
-const Client = require('hlquery-node-client');
+Use the Node.js client when you want hlquery calls to read like regular application code. The client is organized around familiar modules such as `client.collections()`, `client.documents()`, and `client.sam()`, so collection management, document indexing, search, SQL, and SAM workflows stay easy to find.
+
+It also keeps the repetitive parts in one place: authentication, request parameters, endpoint paths, and parsed responses are handled consistently across the client. Common hlquery workflows are covered by default, while raw request access is still available when you need a custom route.
+
+### Why choose it over raw HTTP?
+
+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
 ```
 
-For local development in this repository:
+For local development inside this repository:
 
 ```javascript
 const Client = require('./lib/Client');
@@ -38,279 +47,147 @@ 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();
+/* 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());
-
-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
+const client = new Client('http://localhost:9200', {
+  token: 'your_token_here',
+  auth_method: 'bearer'
+});
+
 client.setAuthToken('your_token_here', 'bearer');
 client.setAuthToken('your_api_key_here', 'api-key');
 ```
 
-### API Surface
+### Operational routes
 
-Use nested API objects: `client -> resource -> action`, for example `client.collections().create(...)`.
+The client includes wrappers for the common server and cluster routes used by dashboards, scripts, and maintenance jobs:
 
 ```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);
-```
+const status = await client.status();
+const health = await client.health();
+const etc = await client.etc();
 
-### 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 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');
 
-await collections.get('books');
-await collections.getFields('books');
-await collections.update('books', schema);
-await collections.delete('books');
+const flush = await client.flush();
 ```
 
-### Documents
+Routes that do not have a dedicated wrapper can still be called through `executeRequest()`:
 
 ```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.'
+const response = await client.executeRequest('GET', '/modules/<name>/<route>', null, {
+  q: 'example query'
 });
 
-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' }
-});
+/* 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());
 ```
 
-`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.
+/* 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
 
-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 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;'
 );
 
-const rows = response.getBody().rows || [];
-
-await client.sql('SHOW COLLECTIONS;');
-await client.execSql("INSERT INTO products (id, title) VALUES ('sku-9', 'Camp Stove');");
+/* 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());
 ```
 
-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: []
-});
+/* Print the custom module route response body. */
+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();
-```
-
-### Errors
+### How to Contribute
 
-```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,59 @@ class Client {
         return this._search;
     }
 
+    /**
+     * Get SAM API instance
+     *
+     * @returns {SAM}
+     */
+    sam() {
+        return this._sam;
+    }
+
+    async samSearch(collectionName, query, params = {}) {
+        return await this._sam.search(collectionName, query, params);
+    }
+
+    async samSearchAll(query, params = {}) {
+        return await this._sam.searchAll(query, params);
+    }
+
+    async samRebuild(collectionName, params = {}) {
+        return await this._sam.rebuild(collectionName, params);
+    }
+
+    async samStatus(collectionName = null, params = {}) {
+        return await this._sam.status(collectionName, params);
+    }
+
+    async samDebug(collectionName = null, params = {}) {
+        return await this._sam.debug(collectionName, params);
+    }
+
+    async samHistory(collectionName = null, limit = 100, params = {}) {
+        return await this._sam.history(collectionName, limit, params);
+    }
+
+    async samPause(pauseUntilMs, params = {}) {
+        return await this._sam.pause(pauseUntilMs, params);
+    }
+
+    async samClearPause(params = {}) {
+        return await this._sam.clearPause(params);
+    }
+
+    async samDocuments(collectionName, offset = 0, limit = 20, params = {}) {
+        return await this._sam.listDocuments(collectionName, offset, limit, params);
+    }
+
+    async samDocument(collectionName, documentId, params = {}) {
+        return await this._sam.getDocument(collectionName, documentId, params);
+    }
+
+    async samOpenDocument(collectionName, documentId, interactionQuery = null, params = {}) {
+        return await this._sam.openDocument(collectionName, documentId, interactionQuery, params);
+    }
+
     /**
      * Get aliases API instance
      *

package/lib/SAM.js

@@ -0,0 +1,161 @@
+/**
+ * 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;
+    }
+
+    _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');
+        }
+
+        this._validateParams(params, 'SAM search params');
+
+        const queryParams = {
+            ...params,
+            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 = {}) {
+        this._validateParams(params, 'SAM status params');
+
+        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 debug(collectionName = null, params = {}) {
+        this._validateParams(params, 'SAM debug params');
+
+        const queryParams = { ...params };
+
+        if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
+            Validator.validateCollectionName(collectionName);
+            queryParams.collection = collectionName;
+        }
+
+        return await this.request.execute('GET', '/sam/debug', null, queryParams);
+    }
+
+    async history(collectionName = null, limit = 100, params = {}) {
+        this._validateParams(params, 'SAM history params');
+
+        const queryParams = {
+            ...params,
+            limit: Number(limit)
+        };
+
+        if (collectionName !== null && collectionName !== undefined && collectionName !== '') {
+            Validator.validateCollectionName(collectionName);
+            queryParams.collection = collectionName;
+        }
+
+        return await this.request.execute('GET', '/sam/history', null, queryParams);
+    }
+
+    async pause(pauseUntilMs, params = {}) {
+        this._validateParams(params, 'SAM pause params');
+
+        const pause = Number(pauseUntilMs);
+        if (!Number.isFinite(pause) || pause < 0) {
+            throw new Error('SAM pause value must be a non-negative unix millisecond timestamp, or 0 to clear');
+        }
+
+        return await this.request.execute('POST', '/sam/pause', null, {
+            ...params,
+            pause
+        });
+    }
+
+    async clearPause(params = {}) {
+        return await this.pause(0, params);
+    }
+
+    async listDocuments(collectionName, offset = 0, limit = 20, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        this._validateParams(params, 'SAM document list params');
+
+        return await this.request.execute('GET', '/sam/documents', null, {
+            ...params,
+            collection: collectionName,
+            offset: Number(offset),
+            limit: Number(limit)
+        });
+    }
+
+    async getDocument(collectionName, documentId, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+        this._validateParams(params, 'SAM document params');
+
+        return await this.request.execute(
+            'GET',
+            `/sam/documents/${encodeURIComponent(collectionName)}/${encodeURIComponent(documentId)}`,
+            null,
+            params
+        );
+    }
+
+    async openDocument(collectionName, documentId, interactionQuery = null, params = {}) {
+        const queryParams = { ...params };
+
+        if (interactionQuery !== null && interactionQuery !== undefined && interactionQuery !== '') {
+            if (typeof interactionQuery !== 'string') {
+                throw new Error('SAM interaction query must be a string');
+            }
+            queryParams.interaction_query = interactionQuery;
+        }
+
+        return await this.getDocument(collectionName, documentId, queryParams);
+    }
+}
+
+module.exports = SAM;

package/lib/conformance.js

@@ -44,6 +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' },
@@ -64,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.0",
+  "version": "1.0.2",
   "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"
+  }
 }

package/test/offline-smoke.js

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