hlquery-node-client 1.0.0

package/lib/Request.js

@@ -0,0 +1,147 @@
+/**
+ * hlquery Node.js Client - HTTP Request Handler
+ * 
+ * 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 https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const { RequestException, AuthenticationException, DemoModeException } = require('./Exceptions');
+const Response = require('./Response');
+
+/**
+ * HTTP request handler
+ */
+class Request {
+    constructor(baseUrl, timeout = 30000, authToken = null, authMethod = 'bearer') {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.timeout = timeout;
+        this.authToken = authToken;
+        this.authMethod = authMethod;
+    }
+    
+    setAuthToken(token, method = 'bearer') {
+        this.authToken = token;
+        this.authMethod = method;
+    }
+    
+    clearAuth() {
+        this.authToken = null;
+    }
+    
+    /**
+     * Make HTTP request
+     * 
+     * @param {string} method HTTP method
+     * @param {string} path API path
+     * @param {object|string|null} body Request body
+     * @param {object} queryParams Query parameters
+     * @returns {Promise<Response>}
+     * @throws {RequestException}
+     */
+    async execute(method, path, body = null, queryParams = {}) {
+        const url = new URL(this.baseUrl + path);
+        
+        // Add query parameters
+        Object.keys(queryParams).forEach(key => {
+            if (queryParams[key] !== undefined && queryParams[key] !== null) {
+                url.searchParams.append(key, queryParams[key]);
+            }
+        });
+        
+        const headers = {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json'
+        };
+        
+        // Prepare body string if present
+        let bodyStr = null;
+        if (body !== null) {
+            bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
+            headers['Content-Length'] = Buffer.byteLength(bodyStr);
+        }
+        
+        // Add authentication header if token is set
+        if (this.authToken !== null) {
+            if (this.authMethod === 'api-key') {
+                headers['X-API-Key'] = this.authToken;
+            } else {
+                headers['Authorization'] = `Bearer ${this.authToken}`;
+            }
+        }
+        
+        const options = {
+            method: method,
+            headers: headers,
+            timeout: this.timeout
+        };
+        
+        const client = url.protocol === 'https:' ? https : http;
+        
+        return new Promise((resolve, reject) => {
+            const req = client.request(url, options, (res) => {
+                const responseHeaders = {};
+                Object.keys(res.headers).forEach(key => {
+                    responseHeaders[key.toLowerCase()] = res.headers[key];
+                });
+                
+                let data = '';
+                
+                res.on('data', (chunk) => {
+                    data += chunk;
+                });
+                
+                res.on('end', () => {
+                    let decoded;
+                    try {
+                        decoded = data ? JSON.parse(data) : null;
+                    } catch (e) {
+                        // If JSON parsing fails, return raw response
+                        decoded = data;
+                    }
+                    
+                    // Check for demo mode errors
+                    if (res.statusCode === 403 && decoded && typeof decoded === 'object') {
+                        const errorMsg = decoded.error || decoded.message || '';
+                        if (errorMsg.includes('Demo mode is enabled') || 
+                            errorMsg.includes('Operation not allowed') ||
+                            errorMsg.includes('Write operations are not allowed')) {
+                            return reject(new DemoModeException(
+                                `Demo mode is enabled on the server. Write operations are blocked. Only search and read operations are permitted. Server message: ${decoded.message || decoded.error}`
+                            ));
+                        }
+                        // Check if server rejected token because auth is disabled
+                        if (errorMsg.includes('Authentication is disabled') || 
+                            errorMsg.includes('Tokens are not accepted when authentication is disabled')) {
+                            return reject(new AuthenticationException(
+                                `Authentication is disabled on the server. Remove the token from your client configuration. Server message: ${decoded.message || decoded.error}`
+                            ));
+                        }
+                    }
+                    
+                    resolve(new Response(res.statusCode, decoded, responseHeaders));
+                });
+            });
+            
+            req.on('error', (error) => {
+                reject(new RequestException(`Request failed: ${error.message}`, 0));
+            });
+            
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new RequestException('Request timeout', 0));
+            });
+            
+            if (bodyStr !== null) {
+                req.write(bodyStr);
+            }
+            
+            req.end();
+        });
+    }
+}
+
+module.exports = Request;

package/lib/Response.js

@@ -0,0 +1,54 @@
+/**
+ * hlquery Node.js Client - Response Handler
+ * 
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ * 
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+/**
+ * Response wrapper for API responses
+ */
+class Response {
+    constructor(statusCode, body, headers = {}) {
+        this.statusCode = statusCode;
+        this.body = body;
+        this.headers = headers;
+    }
+    
+    getStatusCode() {
+        return this.statusCode;
+    }
+    
+    getBody() {
+        return this.body;
+    }
+    
+    getHeaders() {
+        return this.headers;
+    }
+    
+    isSuccess() {
+        return this.statusCode >= 200 && this.statusCode < 300;
+    }
+    
+    isError() {
+        return this.statusCode >= 400;
+    }
+    
+    getError() {
+        if (this.isError() && typeof this.body === 'object' && this.body !== null) {
+            return this.body.error || this.body.message || 'Unknown error';
+        }
+        return null;
+    }
+    
+    toArray() {
+        return {
+            status: this.statusCode,
+            body: this.body
+        };
+    }
+}
+
+module.exports = Response;

package/lib/Search.js

@@ -0,0 +1,350 @@
+/**
+ * hlquery Node.js Client - Search 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');
+
+/**
+ * Search API operations
+ */
+class Search {
+    constructor(request, collections) {
+        this.request = request;
+        this.collections = collections;
+    }
+    
+    /**
+     * Search documents
+     * 
+     * @param {string} collectionName
+     * @param {object} params Search parameters
+     * @returns {Promise<Response>}
+     */
+    async search(collectionName, params = {}) {
+        return await this._searchCollection(collectionName, params, false);
+    }
+
+    /**
+     * Execute a collection-bound SQL SELECT through the search endpoint.
+     *
+     * @param {string} collectionName
+     * @param {string} sql
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async sql(collectionName, sql, params = {}) {
+        Validator.validateCollectionName(collectionName);
+
+        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');
+        }
+
+        const queryParams = { ...params, sql };
+
+        return await this.request.execute(
+            'GET',
+            `/collections/${encodeURIComponent(collectionName)}/documents/search`,
+            null,
+            queryParams
+        );
+    }
+
+    /**
+     * Search documents through the legacy /documents/search route.
+     *
+     * @param {string} collectionName
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async searchLegacy(collectionName, params = {}) {
+        return await this._searchCollection(collectionName, params, true);
+    }
+
+    async _searchCollection(collectionName, params = {}, useLegacyPath = false) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateSearchParams(params);
+        
+        const queryParams = {};
+        
+        // Handle structured query object (Elasticsearch-like)
+        if (params.query) {
+            if (params.query.q) {
+                queryParams.q = params.query.q;
+            }
+            if (params.query.query_by) {
+                queryParams.query_by = Array.isArray(params.query.query_by)
+                    ? params.query.query_by.join(',')
+                    : params.query.query_by;
+            }
+        }
+        
+        // Direct query parameters
+        if (params.q) {
+            queryParams.q = params.q;
+        }
+        
+        // Fields to search in
+        if (params.query_by) {
+            queryParams.query_by = Array.isArray(params.query_by)
+                ? params.query_by.join(',')
+                : params.query_by;
+        } else if (params.q && params.q !== '') {
+            // Auto-detect searchable fields
+            const collection = await this.collections.get(collectionName);
+            if (collection.getStatusCode() === 200) {
+                const body = collection.getBody();
+                if (body.searchable_fields && body.searchable_fields.length > 0) {
+                    queryParams.query_by = body.searchable_fields.join(',');
+                }
+            }
+        }
+        
+        // Pagination
+        if (params.from !== undefined) {
+            queryParams.offset = params.from;
+        } else if (params.offset !== undefined) {
+            queryParams.offset = params.offset;
+        }
+        
+        if (params.size !== undefined) {
+            queryParams.limit = params.size;
+        } else if (params.limit !== undefined) {
+            queryParams.limit = params.limit;
+        }
+        
+        // Page-based pagination
+        if (params.page !== undefined) {
+            queryParams.page = params.page;
+        }
+        if (params.per_page !== undefined) {
+            queryParams.per_page = params.per_page;
+        }
+        
+        // Filter
+        if (params.filter_by) {
+            queryParams.filter_by = params.filter_by;
+        } else if (params.filter) {
+            queryParams.filter_by = typeof params.filter === 'object'
+                ? JSON.stringify(params.filter)
+                : params.filter;
+        }
+        
+        // Sort
+        if (params.sort) {
+            if (Array.isArray(params.sort)) {
+                const sortFields = [];
+                for (const sortItem of params.sort) {
+                    if (typeof sortItem === 'object') {
+                        for (const [field, order] of Object.entries(sortItem)) {
+                            sortFields.push(order === 'desc' ? `-${field}` : field);
+                        }
+                    } else {
+                        sortFields.push(sortItem);
+                    }
+                }
+                queryParams.sort_by = sortFields.join(',');
+            } else {
+                queryParams.sort_by = params.sort;
+            }
+        } else if (params.sort_by) {
+            queryParams.sort_by = Array.isArray(params.sort_by)
+                ? params.sort_by.join(',')
+                : params.sort_by;
+        }
+        
+        // Facets
+        if (params.facet_by) {
+            queryParams.facet_by = Array.isArray(params.facet_by)
+                ? params.facet_by.join(',')
+                : params.facet_by;
+        } else if (params.facets) {
+            queryParams.facet_by = Array.isArray(params.facets)
+                ? params.facets.join(',')
+                : params.facets;
+        }
+        
+        // Additional search parameters
+        if (params.typo_tolerance !== undefined) {
+            queryParams.typo_tolerance = params.typo_tolerance;
+        }
+        
+        if (params.num_typos !== undefined) {
+            queryParams.num_typos = params.num_typos;
+        }
+        
+        // Highlighting parameters
+        if (params.highlight !== undefined) {
+            queryParams.highlight = params.highlight === true || params.highlight === 'true' ? 'true' : 'false';
+        }
+        
+        if (params.highlight_fields !== undefined) {
+            queryParams.highlight_fields = Array.isArray(params.highlight_fields)
+                ? params.highlight_fields.join(',')
+                : params.highlight_fields;
+        }
+        
+        if (params.highlight_full_fields !== undefined) {
+            queryParams.highlight_full_fields = Array.isArray(params.highlight_full_fields)
+                ? params.highlight_full_fields.join(',')
+                : params.highlight_full_fields;
+        }
+        
+        // Determine HTTP method
+        const method = params.body ? 'POST' : 'GET';
+        const body = params.body || null;
+        
+        const path = useLegacyPath
+            ? `/collections/${encodeURIComponent(collectionName)}/documents/search`
+            : `/collections/${encodeURIComponent(collectionName)}/search`;
+
+        return await this.request.execute(method, path, body, queryParams);
+    }
+    
+    /**
+     * Multi-search across multiple collections
+     * 
+     * @param {Array} searches Array of search requests
+     * @returns {Promise<Response>}
+     */
+    async multiSearch(searches) {
+        return await this.request.execute('POST', '/multi_search', { searches: searches });
+    }
+
+    /**
+     * Global search across collections.
+     *
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async globalSearch(params = {}) {
+        Validator.validateSearchParams(params);
+
+        const method = params.body ? 'POST' : 'GET';
+        const body = params.body || (method === 'POST' ? params : null);
+        const queryParams = method === 'GET' ? params : {};
+
+        return await this.request.execute(method, '/search', body, queryParams);
+    }
+    
+    /**
+     * Vector search
+     * 
+     * @param {string} collectionName
+     * @param {object} params Vector search parameters:
+     *   - vector_query: Array of floats or JSON string
+     *   - vectorQuery: Array/object alias for vector_query
+     *   - vector: Array of floats or JSON string (alias for vector_query)
+     *   - embedding: Array of floats or JSON string (alias for vector_query)
+     *   - field_name/field/fieldName: Field name to search in (default: 'embedding')
+     *   - limit/topk/top_k/k/per_page: Number of results
+     *   - threshold: Similarity threshold (default: 0.0)
+     *   - normalize: Normalize vectors (default: true)
+     *   - output_fields/outputFields, include_vector/includeVector, include_distance/includeDistance
+     *   - radius/max_distance, range_filter/min_distance
+     *   - query_params/queryParams/params, filter/filter_by/filterBy
+     * @returns {Promise<Response>}
+     */
+    async vectorSearch(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        
+        const queryParams = {};
+        let forcePost = false;
+        
+        // Handle vector query
+        if (params.vector_query) {
+            queryParams.vector_query = Array.isArray(params.vector_query)
+                ? JSON.stringify(params.vector_query)
+                : params.vector_query;
+        } else if (params.vectorQuery) {
+            queryParams.vector_query = Array.isArray(params.vectorQuery) || typeof params.vectorQuery === 'object'
+                ? JSON.stringify(params.vectorQuery)
+                : params.vectorQuery;
+        } else if (params.vector) {
+            queryParams.vector_query = Array.isArray(params.vector)
+                ? JSON.stringify(params.vector)
+                : params.vector;
+        } else if (params.embedding) {
+            queryParams.vector_query = Array.isArray(params.embedding)
+                ? JSON.stringify(params.embedding)
+                : params.embedding;
+        }
+        
+        if (params.field_name || params.field || params.fieldName) {
+            queryParams.field_name = params.field_name || params.field || params.fieldName;
+        }
+        
+        if (params.limit !== undefined || params.topk !== undefined || params.top_k !== undefined || params.topK !== undefined ||
+            params.k !== undefined || params.per_page !== undefined) {
+            queryParams.limit = params.limit ?? params.topk ?? params.top_k ?? params.topK ?? params.k ?? params.per_page;
+        }
+        
+        if (params.threshold !== undefined) {
+            queryParams.threshold = params.threshold;
+        }
+        
+        if (params.normalize !== undefined) {
+            queryParams.normalize = params.normalize ? 'true' : 'false';
+        }
+
+        if (params.output_fields !== undefined || params.outputFields !== undefined) {
+            const outputFields = params.output_fields ?? params.outputFields;
+            queryParams.output_fields = Array.isArray(outputFields)
+                ? outputFields.join(',')
+                : outputFields;
+        }
+
+        if (params.include_vector !== undefined || params.includeVector !== undefined) {
+            const includeVector = params.include_vector ?? params.includeVector;
+            queryParams.include_vector = includeVector ? 'true' : 'false';
+        }
+
+        if (params.include_distance !== undefined || params.includeDistance !== undefined) {
+            const includeDistance = params.include_distance ?? params.includeDistance;
+            queryParams.include_distance = includeDistance ? 'true' : 'false';
+        }
+
+        if (params.filter_by !== undefined) {
+            queryParams.filter_by = params.filter_by;
+        } else if (params.filterBy !== undefined) {
+            queryParams.filter_by = params.filterBy;
+        } else if (params.filter !== undefined) {
+            queryParams.filter_by = typeof params.filter === 'object'
+                ? JSON.stringify(params.filter)
+                : params.filter;
+        }
+
+        if (params.radius !== undefined) {
+            queryParams.radius = params.radius;
+        }
+        if (params.max_distance !== undefined || params.maxDistance !== undefined) {
+            queryParams.max_distance = params.max_distance ?? params.maxDistance;
+        }
+        if (params.range_filter !== undefined || params.rangeFilter !== undefined) {
+            queryParams.range_filter = params.range_filter ?? params.rangeFilter;
+        }
+        if (params.min_distance !== undefined || params.minDistance !== undefined) {
+            queryParams.min_distance = params.min_distance ?? params.minDistance;
+        }
+
+        if (params.query_params !== undefined || params.queryParams !== undefined || params.params !== undefined ||
+            params.vector_queries !== undefined || params.vectorQueries !== undefined || params.vectorQuery !== undefined) {
+            forcePost = true;
+        }
+        
+        const path = `/collections/${encodeURIComponent(collectionName)}/vector_search`;
+        const method = params.body || forcePost ? 'POST' : 'GET';
+        const body = params.body || (forcePost ? params : null);
+        
+        return await this.request.execute(method, path, body, queryParams);
+    }
+}
+
+module.exports = Search;

package/lib/Stopwords.js

@@ -0,0 +1,60 @@
+/**
+ * hlquery Node.js Client - Stopwords 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');
+const { ValidationException } = require('./Exceptions');
+
+function validateWord(word, fieldName = 'word') {
+    if (!word || typeof word !== 'string' || word.trim() === '') {
+        throw new ValidationException(`${fieldName} must be a non-empty string`);
+    }
+}
+
+/**
+ * Stopwords API operations
+ */
+class Stopwords {
+    constructor(request) {
+        this.request = request;
+    }
+
+    async list(collectionName) {
+        Validator.validateCollectionName(collectionName);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/stopwords`);
+    }
+
+    async create(collectionName, params) {
+        Validator.validateCollectionName(collectionName);
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/stopwords`, params);
+    }
+
+    async delete(collectionName, word) {
+        Validator.validateCollectionName(collectionName);
+        validateWord(word);
+        return await this.request.execute('DELETE', `/collections/${encodeURIComponent(collectionName)}/stopwords/${encodeURIComponent(word)}`);
+    }
+
+    async listAll() {
+        return await this.request.execute('GET', '/stopwords');
+    }
+
+    async listGlobal() {
+        return await this.request.execute('GET', '/stopwords/global');
+    }
+
+    async createGlobal(params) {
+        return await this.request.execute('POST', '/stopwords/global', params);
+    }
+
+    async deleteGlobal(word) {
+        validateWord(word);
+        return await this.request.execute('DELETE', `/stopwords/global/${encodeURIComponent(word)}`);
+    }
+}
+
+module.exports = Stopwords;

package/lib/Synonyms.js

@@ -0,0 +1,85 @@
+/**
+ * hlquery Node.js Client - Synonyms 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');
+
+/**
+ * Synonyms API operations
+ */
+class Synonyms {
+    constructor(request) {
+        this.request = request;
+    }
+
+    async list(collectionName) {
+        Validator.validateCollectionName(collectionName);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/synonyms`);
+    }
+
+    async get(collectionName, id) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/synonyms/${encodeURIComponent(id)}`);
+    }
+
+    async create(collectionName, id, synonym) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/synonyms/${encodeURIComponent(id)}`, synonym);
+    }
+
+    async update(collectionName, id, synonym) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('PUT', `/collections/${encodeURIComponent(collectionName)}/synonyms/${encodeURIComponent(id)}`, synonym);
+    }
+
+    async upsert(collectionName, id, synonym) {
+        return await this.create(collectionName, id, synonym);
+    }
+
+    async delete(collectionName, id) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('DELETE', `/collections/${encodeURIComponent(collectionName)}/synonyms/${encodeURIComponent(id)}`);
+    }
+
+    async listAll() {
+        return await this.request.execute('GET', '/synonyms');
+    }
+
+    async listGlobal() {
+        return await this.request.execute('GET', '/synonyms/global');
+    }
+
+    async getGlobal(id) {
+        Validator.validateDocumentId(id);
+        return await this.request.execute('GET', `/synonyms/global/${encodeURIComponent(id)}`);
+    }
+
+    async createGlobal(id, synonym) {
+        Validator.validateDocumentId(id);
+        return await this.request.execute('POST', `/synonyms/global/${encodeURIComponent(id)}`, synonym);
+    }
+
+    async updateGlobal(id, synonym) {
+        Validator.validateDocumentId(id);
+        return await this.request.execute('PUT', `/synonyms/global/${encodeURIComponent(id)}`, synonym);
+    }
+
+    async upsertGlobal(id, synonym) {
+        return await this.createGlobal(id, synonym);
+    }
+
+    async deleteGlobal(id) {
+        Validator.validateDocumentId(id);
+        return await this.request.execute('DELETE', `/synonyms/global/${encodeURIComponent(id)}`);
+    }
+}
+
+module.exports = Synonyms;