hlquery-node-client 1.0.0

package/lib/System.js

@@ -0,0 +1,110 @@
+/**
+ * hlquery Node.js Client - System 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.
+ */
+
+/**
+ * System and operational API operations
+ */
+class System {
+    constructor(request) {
+        this.request = request;
+    }
+
+    async health() {
+        return await this.request.execute('GET', '/health');
+    }
+
+    async status() {
+        return await this.request.execute('GET', '/status');
+    }
+
+    async startup() {
+        return await this.request.execute('GET', '/startup');
+    }
+
+    async bootStatus() {
+        return await this.request.execute('GET', '/boot-status');
+    }
+
+    async info() {
+        return await this.request.execute('GET', '/');
+    }
+
+    async stats() {
+        return await this.request.execute('GET', '/stats');
+    }
+
+    async metrics() {
+        return await this.request.execute('GET', '/metrics');
+    }
+
+    async metricsJson() {
+        return await this.request.execute('GET', '/metrics.json');
+    }
+
+    async connections() {
+        return await this.request.execute('GET', '/connections');
+    }
+
+    async rocksdb() {
+        return await this.request.execute('GET', '/rocksdb');
+    }
+
+    async rocksdbInternal() {
+        return await this.request.execute('GET', '/_rocksdb');
+    }
+
+    async docTotal() {
+        return await this.request.execute('GET', '/doctotal');
+    }
+
+    async etc() {
+        return await this.request.execute('GET', '/etc');
+    }
+
+    async sql(sql, params = {}) {
+        if (typeof sql !== 'string' || sql.trim() === '') {
+            throw new Error('SQL query must be a non-empty string');
+        }
+
+        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+            throw new Error('SQL params must be an object');
+        }
+
+        return await this.request.execute('GET', '/sql', null, { ...params, sql });
+    }
+
+    async execSql(sql) {
+        if (typeof sql !== 'string' || sql.trim() === '') {
+            throw new Error('SQL query must be a non-empty string');
+        }
+
+        return await this.request.execute('POST', '/sql', { exec: sql });
+    }
+
+    async ping() {
+        return await this.request.execute('GET', '/ping');
+    }
+
+    async integrity() {
+        return await this.request.execute('GET', '/integrity');
+    }
+
+    async consistency() {
+        return await this.request.execute('GET', '/consistency');
+    }
+
+    async selfCheck() {
+        return await this.request.execute('GET', '/self-check');
+    }
+
+    async storageStatus() {
+        return await this.request.execute('GET', '/admin/storage_status');
+    }
+}
+
+module.exports = System;

package/lib/conformance.js

@@ -0,0 +1,74 @@
+/**
+ * hlquery Node.js Client - Server conformance manifest
+ *
+ * This manifest maps routed server endpoints to the Node client wrapper that
+ * owns them. Any server route in scope must be marked as supported or omitted.
+ */
+
+const NODE_CLIENT_ROUTE_COVERAGE = [
+    { path: '/', methods: ['GET'], status: 'supported', client: 'system.info' },
+    { path: '/health', methods: ['GET'], status: 'supported', client: 'system.health' },
+    { path: '/status', methods: ['GET'], status: 'supported', client: 'system.status' },
+    { path: '/startup', methods: ['GET'], status: 'supported', client: 'system.startup' },
+    { path: '/boot-status', methods: ['GET'], status: 'supported', client: 'system.bootStatus' },
+    { path: '/stats', methods: ['GET'], status: 'supported', client: 'system.stats' },
+    { path: '/metrics', methods: ['GET'], status: 'supported', client: 'system.metrics' },
+    { path: '/metrics.json', methods: ['GET'], status: 'supported', client: 'system.metricsJson' },
+    { path: '/connections', methods: ['GET'], status: 'supported', client: 'system.connections' },
+    { path: '/rocksdb', methods: ['GET'], status: 'supported', client: 'system.rocksdb' },
+    { path: '/_rocksdb', methods: ['GET'], status: 'supported', client: 'system.rocksdbInternal' },
+    { path: '/doctotal', methods: ['GET'], status: 'supported', client: 'system.docTotal' },
+    { path: '/etc', methods: ['GET'], status: 'supported', client: 'system.etc' },
+    { path: '/ping', methods: ['GET'], status: 'supported', client: 'system.ping' },
+    { path: '/integrity', methods: ['GET'], status: 'supported', client: 'system.integrity' },
+    { path: '/consistency', methods: ['GET'], status: 'supported', client: 'system.consistency' },
+    { path: '/self-check', methods: ['GET'], status: 'supported', client: 'system.selfCheck' },
+    { path: '/admin/storage_status', methods: ['GET'], status: 'supported', client: 'system.storageStatus' },
+    { path: '/cluster/health', methods: ['GET'], status: 'supported', client: 'client.clusterHealth' },
+    { path: '/cluster/stats', methods: ['GET'], status: 'supported', client: 'client.clusterStats' },
+    { path: '/cluster/nodes', methods: ['GET'], status: 'supported', client: 'client.clusterNodes' },
+    { path: '/links', methods: ['GET'], status: 'supported', client: 'client.links' },
+    { path: '/links/ping', methods: ['GET'], status: 'supported', client: 'client.linksPing' },
+    { path: '/links/connect', methods: ['POST'], status: 'supported', client: 'client.linksConnect' },
+    { path: '/links/disconnect', methods: ['POST'], status: 'supported', client: 'client.linksDisconnect' },
+    { path: '/flush', methods: ['POST'], status: 'supported', client: 'client.flush' },
+    { path: '/collections/distributed', methods: ['GET'], status: 'supported', client: 'client.listCollectionsDistributed' },
+    { path: '/collections', methods: ['GET', 'POST'], status: 'supported', client: 'collections.list/create' },
+    { path: '/collections/{name}', methods: ['GET', 'DELETE'], status: 'supported', client: 'collections.get/delete' },
+    { path: '/collections/{name}/update', methods: ['POST'], status: 'supported', client: 'collections.update' },
+    { path: '/collections/{name}/documents', methods: ['GET', 'POST', 'DELETE'], status: 'supported', client: 'documents.list/add/deleteByFilter' },
+    { path: '/collections/{name}/documents/import', methods: ['POST'], status: 'supported', client: 'documents.import' },
+    { path: '/collections/{name}/documents/{id}', methods: ['GET', 'PUT', 'DELETE'], status: 'supported', client: 'documents.get/update/delete' },
+    { path: '/collections/{name}/search', methods: ['GET', 'POST'], status: 'supported', client: 'search.search' },
+    { path: '/collections/{name}/documents/search', methods: ['GET', 'POST'], status: 'supported', client: 'search.searchLegacy' },
+    { 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: '/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' },
+    { path: '/collections/{name}/synonyms/{id}', methods: ['GET', 'POST', 'PUT', 'DELETE'], status: 'supported', client: 'synonyms.get/create/update/delete' },
+    { path: '/synonyms', methods: ['GET'], status: 'supported', client: 'synonyms.listAll' },
+    { path: '/synonyms/global', methods: ['GET'], status: 'supported', client: 'synonyms.listGlobal' },
+    { path: '/synonyms/global/{id}', methods: ['GET', 'POST', 'PUT', 'DELETE'], status: 'supported', client: 'synonyms.getGlobal/createGlobal/updateGlobal/deleteGlobal' },
+    { path: '/collections/{name}/stopwords', methods: ['GET', 'POST'], status: 'supported', client: 'stopwords.list/create' },
+    { path: '/collections/{name}/stopwords/{word}', methods: ['DELETE'], status: 'supported', client: 'stopwords.delete' },
+    { path: '/stopwords', methods: ['GET'], status: 'supported', client: 'stopwords.listAll' },
+    { path: '/stopwords/global', methods: ['GET', 'POST'], status: 'supported', client: 'stopwords.listGlobal/createGlobal' },
+    { path: '/stopwords/global/{word}', methods: ['DELETE'], status: 'supported', client: 'stopwords.deleteGlobal' },
+    { path: '/collections/{name}/overrides', methods: ['GET'], status: 'supported', client: 'overrides.list' },
+    { path: '/collections/{name}/overrides/{id}', methods: ['GET', 'POST', 'PUT', 'DELETE'], status: 'supported', client: 'overrides.get/create/update/delete' },
+    { path: '/aliases', methods: ['GET'], status: 'supported', client: 'aliases.list' },
+    { path: '/aliases/{name}', methods: ['GET', 'POST', 'PUT', 'DELETE'], status: 'supported', client: 'aliases.get/create/update/delete' },
+    { path: '/keys', methods: ['GET', 'POST'], status: 'supported', client: 'keys.list/create' },
+    { 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: '/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.' }
+];
+
+module.exports = {
+    NODE_CLIENT_ROUTE_COVERAGE
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "hlquery-node-client",
+  "version": "1.0.0",
+  "description": "Node.js client library for hlquery search engine",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node ../tests/test_node_client_conformance.js",
+    "test:conformance": "node ../tests/test_node_client_conformance.js",
+    "test:offline": "node test/offline-smoke.js",
+    "example": "node example.js",
+    "example:pdf": "node examples/pdf.js",
+    "example:csv": "node examples/csv.js"
+  },
+  "dependencies": {
+    "pdf-parse": "^2.4.5"
+  },
+  "keywords": [
+    "hlquery",
+    "search",
+    "client",
+    "api"
+  ],
+  "author": "Carlos F. Ferry <carlos.ferry@gmail.com>",
+  "license": "BSD-3-Clause",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "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"
+}

package/test/offline-smoke.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+const assert = require('assert');
+const http = require('http');
+
+const Hlquery = require('..');
+const Client = require('../lib/Client');
+const Request = require('../lib/Request');
+const Response = require('../lib/Response');
+const Config = require('../utils/Config');
+const Validator = require('../utils/Validator');
+
+async function main() {
+  assert.strictEqual(typeof Hlquery, 'function', 'default export should be the Client constructor');
+  assert.strictEqual(Hlquery.Client, Client, 'named Client export should match default export');
+
+  assert.strictEqual(Config.normalizeUrl('localhost:9200/'), 'http://localhost:9200');
+  assert.strictEqual(Config.isValidUrl('http://localhost:9200'), true);
+  assert.strictEqual(Config.isValidUrl('notaurl'), false);
+
+  Validator.validateCollectionName('books');
+  Validator.validateDocumentId('doc_123');
+  Validator.validateSearchParams({ limit: 10, offset: 0 });
+
+  assert.throws(() => Validator.validateCollectionName('123bad'), /letter or underscore/);
+  assert.throws(() => Validator.validateDocumentFields({ title: 'bad,value' }), /comma/);
+
+  const response = new Response(200, { ok: true }, { 'content-type': 'application/json' });
+  assert.strictEqual(response.isSuccess(), true);
+  assert.deepStrictEqual(response.getBody(), { ok: true });
+
+  const server = http.createServer((req, res) => {
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok' }));
+      return;
+    }
+
+    if (req.url === '/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
+      }));
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'not found' }));
+  });
+
+  await new Promise((resolve, reject) => {
+    server.listen(0, '127.0.0.1', (err) => (err ? reject(err) : resolve()));
+  });
+
+  const { port } = server.address();
+
+  try {
+    const request = new Request(`http://127.0.0.1:${port}`);
+    const health = await request.execute('GET', '/health');
+    assert.strictEqual(health.getStatusCode(), 200);
+    assert.deepStrictEqual(health.getBody(), { status: 'ok' });
+
+    request.setAuthToken('secret-token', 'bearer');
+    const bearerEcho = await request.execute('GET', '/echo-auth');
+    assert.strictEqual(bearerEcho.getBody().authorization, 'Bearer secret-token');
+
+    request.setAuthToken('scoped-key', 'api-key');
+    const apiKeyEcho = await request.execute('GET', '/echo-auth');
+    assert.strictEqual(apiKeyEcho.getBody().apiKey, 'scoped-key');
+
+    const client = new Client(`http://127.0.0.1:${port}`);
+    const clientHealth = await client.health();
+    assert.strictEqual(clientHealth.isSuccess(), true);
+    assert.deepStrictEqual(clientHealth.getBody(), { status: 'ok' });
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+
+  process.stdout.write('Node offline smoke tests passed.\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.stack || error.message}\n`);
+  process.exit(1);
+});

package/utils/Auth.js

@@ -0,0 +1,34 @@
+/**
+ * hlquery Node.js Client - Authentication Utilities
+ * 
+ * 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 crypto = require('crypto');
+
+/**
+ * Authentication utilities
+ */
+class Auth {
+    /**
+     * Generate MD5 hash for a token (utility function for token generation)
+     * Note: Authentication only requires a token - no username/password needed
+     */
+    static generateToken(token) {
+        return crypto.createHash('md5').update(token).digest('hex');
+    }
+    
+    /**
+     * Validate token format
+     */
+    static validateToken(token) {
+        if (!token || typeof token !== 'string' || token.trim() === '') {
+            throw new Error('Token must be a non-empty string');
+        }
+        return true;
+    }
+}
+
+module.exports = Auth;

package/utils/CSVParser.js

@@ -0,0 +1,160 @@
+/**
+ * hlquery Node.js Client - CSV parsing helper
+ *
+ * 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 fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { ValidationException } = require('../lib/Exceptions');
+
+class CSVParser {
+    static parseFile(filePath, options = {}) {
+        this.validateFilePath(filePath);
+
+        const resolvedPath = path.resolve(filePath);
+        const stat = fs.statSync(resolvedPath);
+
+        if (!stat.isFile()) {
+            throw new ValidationException(`CSV path is not a file: ${resolvedPath}`);
+        }
+
+        const raw = fs.readFileSync(resolvedPath, 'utf8');
+        const rows = this.parseCSV(raw, options.delimiter || ',');
+        const header = rows.length > 0 ? rows[0] : [];
+        const dataRows = rows.length > 1 ? rows.slice(1) : [];
+        const content = this.normalizeRows(dataRows.length > 0 ? dataRows : rows, options);
+
+        return {
+            filePath: resolvedPath,
+            fileName: path.basename(resolvedPath),
+            title: this.resolveTitle(resolvedPath, options),
+            content: content,
+            rowCount: dataRows.length > 0 ? dataRows.length : rows.length,
+            columnCount: header.length || (rows[0] ? rows[0].length : 0),
+            header: header,
+            sizeBytes: stat.size
+        };
+    }
+
+    static buildDocumentFromParsedCSV(parsed, options = {}) {
+        const contentField = options.contentField || 'content';
+        const titleField = options.titleField || 'title';
+        const document = Object.assign({}, options.document || {});
+
+        document.id = options.id || document.id || this.generateDocumentId(parsed.fileName);
+        document[titleField] = options.title || document[titleField] || parsed.title;
+        document[contentField] = parsed.content;
+        document.file_name = parsed.fileName;
+        document.file_path = parsed.filePath;
+        document.mime_type = 'text/csv';
+        document.row_count = String(parsed.rowCount);
+        document.column_count = String(parsed.columnCount);
+
+        if (parsed.header.length > 0) {
+            document.columns = parsed.header.map((column) => this.normalizeText(column, options));
+        }
+
+        return document;
+    }
+
+    static parseCSV(input, delimiter) {
+        const rows = [];
+        let row = [];
+        let value = '';
+        let inQuotes = false;
+
+        for (let i = 0; i < input.length; i += 1) {
+            const char = input[i];
+            const next = input[i + 1];
+
+            if (char === '"') {
+                if (inQuotes && next === '"') {
+                    value += '"';
+                    i += 1;
+                } else {
+                    inQuotes = !inQuotes;
+                }
+                continue;
+            }
+
+            if (!inQuotes && char === delimiter) {
+                row.push(value);
+                value = '';
+                continue;
+            }
+
+            if (!inQuotes && (char === '\n' || char === '\r')) {
+                if (char === '\r' && next === '\n') {
+                    i += 1;
+                }
+                row.push(value);
+                value = '';
+                if (row.length > 1 || row[0] !== '') {
+                    rows.push(row);
+                }
+                row = [];
+                continue;
+            }
+
+            value += char;
+        }
+
+        if (value !== '' || row.length > 0) {
+            row.push(value);
+            rows.push(row);
+        }
+
+        return rows;
+    }
+
+    static normalizeRows(rows, options = {}) {
+        return rows
+            .map((row) => row.map((cell) => this.normalizeText(cell, options)).filter(Boolean).join(' '))
+            .filter(Boolean)
+            .join('\n')
+            .trim();
+    }
+
+    static normalizeText(text, options = {}) {
+        let output = String(text || '').replace(/\r\n/g, '\n').replace(/\0/g, '');
+        output = output.replace(/,/g, ' ');
+
+        if (options.collapseWhitespace !== false) {
+            output = output.replace(/[ \t]+/g, ' ');
+            output = output.replace(/\n{3,}/g, '\n\n');
+        }
+
+        return output.trim();
+    }
+
+    static resolveTitle(filePath, options = {}) {
+        if (options.title) {
+            return this.normalizeText(options.title, options);
+        }
+
+        return this.normalizeText(path.basename(filePath, path.extname(filePath)), options);
+    }
+
+    static generateDocumentId(fileName) {
+        const stem = path.basename(fileName, path.extname(fileName))
+            .toLowerCase()
+            .replace(/[^a-z0-9._-]+/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .slice(0, 40);
+        const suffix = crypto.randomBytes(4).toString('hex');
+
+        return `${stem || 'csv'}_${suffix}`;
+    }
+
+    static validateFilePath(filePath) {
+        if (!filePath || typeof filePath !== 'string') {
+            throw new ValidationException('CSV file path must be a non-empty string');
+        }
+    }
+}
+
+module.exports = CSVParser;

package/utils/Config.js

@@ -0,0 +1,57 @@
+/**
+ * hlquery Node.js Client - Configuration Utilities
+ * 
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ * 
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+/**
+ * Configuration management utilities
+ */
+class Config {
+    static getDefaultBaseUrl() {
+        return process.env.HLQ_BASE_URL || process.env.HLQUERY_BASE_URL || 'http://localhost:9200';
+    }
+
+    /**
+     * Merge options with defaults
+     */
+    static mergeDefaults(options = {}) {
+        return {
+            base_url: options.base_url || Config.getDefaultBaseUrl(),
+            timeout: options.timeout || 30000,
+            token: options.token || null,
+            auth_method: options.auth_method || 'bearer',
+            ...options
+        };
+    }
+    
+    /**
+     * Normalize URL
+     */
+    static normalizeUrl(url) {
+        if (!url) {
+            return Config.getDefaultBaseUrl();
+        }
+        url = url.trim();
+        if (!url.startsWith('http://') && !url.startsWith('https://')) {
+            url = 'http://' + url;
+        }
+        return url.replace(/\/$/, '');
+    }
+    
+    /**
+     * Validate URL
+     */
+    static isValidUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            return urlObj.protocol === 'http:' || urlObj.protocol === 'https:';
+        } catch (e) {
+            return false;
+        }
+    }
+}
+
+module.exports = Config;