hlquery-node-client 1.0.0

package/lib/Collections.js

@@ -0,0 +1,159 @@
+/**
+ * hlquery Node.js Client - Collections 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 Response = require('./Response');
+
+/**
+ * Collections API operations
+ */
+class Collections {
+    constructor(request) {
+        this.request = request;
+    }
+    
+    /**
+     * List all collections
+     * 
+     * @param {number} offset Pagination offset
+     * @param {number} limit Number of results
+     * @returns {Promise<Response>}
+     */
+    async list(offset = 0, limit = 10) {
+        Validator.validatePagination(offset, limit);
+        return await this.request.execute('GET', '/collections', null, {
+            offset: offset,
+            limit: limit
+        });
+    }
+    
+    /**
+     * Get collection details
+     * 
+     * @param {string} name Collection name
+     * @returns {Promise<Response>}
+     */
+    async get(name) {
+        Validator.validateCollectionName(name);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(name)}`);
+    }
+    
+    /**
+     * Create a new collection
+     * 
+     * @param {string} name Collection name
+     * @param {object} schema Collection schema
+     * @returns {Promise<Response>}
+     */
+    async create(name, schema) {
+        Validator.validateCollectionName(name);
+        // Merge schema with name at top level (server expects fields/searchable_fields at root)
+        const requestBody = {
+            name: name,
+            ...schema
+        };
+        return await this.request.execute('POST', '/collections', requestBody);
+    }
+    
+    /**
+     * Delete a collection
+     * 
+     * @param {string} name Collection name
+     * @returns {Promise<Response>}
+     */
+    async delete(name) {
+        Validator.validateCollectionName(name);
+        return await this.request.execute('DELETE', `/collections/${encodeURIComponent(name)}`);
+    }
+    
+    /**
+     * Update collection schema
+     * 
+     * @param {string} name Collection name
+     * @param {object} schema Updated schema
+     * @returns {Promise<Response>}
+     */
+    async update(name, schema) {
+        Validator.validateCollectionName(name);
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(name)}/update`, schema);
+    }
+    
+    /**
+     * Get collection fields (formatted)
+     * 
+     * @param {string} name Collection name
+     * @returns {Promise<Response>}
+     */
+    async getFields(name) {
+        const response = await this.get(name);
+        
+        if (response.getStatusCode() !== 200) {
+            return response;
+        }
+        
+        const body = response.getBody();
+        const allFields = [];
+        const fieldTypes = {};
+        
+        // Collect searchable fields
+        if (body.searchable_fields) {
+            for (const field of body.searchable_fields) {
+                if (!allFields.includes(field)) {
+                    allFields.push(field);
+                }
+                if (!fieldTypes[field]) {
+                    fieldTypes[field] = [];
+                }
+                fieldTypes[field].push('searchable');
+            }
+        }
+        
+        // Collect filterable fields
+        if (body.filterable_fields) {
+            for (const field of body.filterable_fields) {
+                if (!allFields.includes(field)) {
+                    allFields.push(field);
+                }
+                if (!fieldTypes[field]) {
+                    fieldTypes[field] = [];
+                }
+                fieldTypes[field].push('filterable');
+            }
+        }
+        
+        // Collect sortable fields
+        if (body.sortable_fields) {
+            for (const field of body.sortable_fields) {
+                if (!allFields.includes(field)) {
+                    allFields.push(field);
+                }
+                if (!fieldTypes[field]) {
+                    fieldTypes[field] = [];
+                }
+                fieldTypes[field].push('sortable');
+            }
+        }
+        
+        // Format fields
+        const fields = allFields.map(field => ({
+            name: field,
+            type: fieldTypes[field].join(', ')
+        }));
+        
+        return new Response(200, {
+            collection: name,
+            fields: fields,
+            field_count: fields.length,
+            searchable_fields: body.searchable_fields || [],
+            filterable_fields: body.filterable_fields || [],
+            sortable_fields: body.sortable_fields || []
+        });
+    }
+}
+
+module.exports = Collections;

package/lib/Documents.js

@@ -0,0 +1,244 @@
+/**
+ * hlquery Node.js Client - Documents 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 PDFParser = require('../utils/PDFParser');
+const CSVParser = require('../utils/CSVParser');
+
+/**
+ * Documents API operations
+ */
+class Documents {
+    constructor(request) {
+        this.request = request;
+    }
+    
+    /**
+     * List documents in a collection
+     * 
+     * @param {string} collectionName
+     * @param {object} params Pagination parameters
+     * @returns {Promise<Response>}
+     */
+    async list(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateSearchParams(params);
+        
+        const offset = params.offset !== undefined ? params.offset : (params.from !== undefined ? params.from : 0);
+        const limit = params.limit !== undefined ? params.limit : (params.size !== undefined ? params.size : 10);
+        
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/documents`, null, {
+            offset: offset,
+            limit: limit
+        });
+    }
+    
+    /**
+     * Get a single document by ID
+     * 
+     * @param {string} collectionName
+     * @param {string} documentId
+     * @returns {Promise<Response>}
+     */
+    async get(collectionName, documentId) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+        
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}`);
+    }
+    
+    /**
+     * Add a document
+     * 
+     * @param {string} collectionName
+     * @param {object} document
+     * @returns {Promise<Response>}
+     */
+    async add(collectionName, document) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentFields(document);
+        
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, document);
+    }
+
+    /**
+     * Parse a local PDF file into normalized text/metadata.
+     *
+     * @param {string} filePath
+     * @param {object} options
+     * @returns {Promise<object>}
+     */
+    async parsePDF(filePath, options = {}) {
+        return await PDFParser.parseFile(filePath, options);
+    }
+
+    /**
+     * Parse a local PDF and add it as a standard hlquery document.
+     *
+     * @param {string} collectionName
+     * @param {string} filePath
+     * @param {object} options
+     * @returns {Promise<Response>}
+     */
+    async addPDF(collectionName, filePath, options = {}) {
+        Validator.validateCollectionName(collectionName);
+
+        const parsed = await this.parsePDF(filePath, options);
+        const document = PDFParser.buildDocumentFromParsedPDF(parsed, options);
+
+        Validator.validateDocumentFields(document);
+
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, document);
+    }
+
+    /**
+     * Parse a local CSV file into normalized text/metadata.
+     *
+     * @param {string} filePath
+     * @param {object} options
+     * @returns {Promise<object>}
+     */
+    async parseCSV(filePath, options = {}) {
+        return CSVParser.parseFile(filePath, options);
+    }
+
+    /**
+     * Parse a local CSV and add it as a standard hlquery document.
+     *
+     * @param {string} collectionName
+     * @param {string} filePath
+     * @param {object} options
+     * @returns {Promise<Response>}
+     */
+    async addCSV(collectionName, filePath, options = {}) {
+        Validator.validateCollectionName(collectionName);
+
+        const parsed = await this.parseCSV(filePath, options);
+        const document = CSVParser.buildDocumentFromParsedCSV(parsed, options);
+
+        Validator.validateDocumentFields(document);
+
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, document);
+    }
+    
+    /**
+     * Update a document
+     * 
+     * @param {string} collectionName
+     * @param {string} documentId
+     * @param {object} document
+     * @returns {Promise<Response>}
+     */
+    async update(collectionName, documentId, document) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+        Validator.validateDocumentFields(document);
+        
+        return await this.request.execute('PUT', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}`, document);
+    }
+    
+    /**
+     * Delete a document
+     * 
+     * @param {string} collectionName
+     * @param {string} documentId
+     * @returns {Promise<Response>}
+     */
+    async delete(collectionName, documentId) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+        
+        return await this.request.execute('DELETE', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}`);
+    }
+    
+    /**
+     * Import documents (bulk)
+     * 
+     * @param {string} collectionName
+     * @param {Array} documents
+     * @returns {Promise<Response>}
+     */
+    async import(collectionName, documents) {
+        Validator.validateCollectionName(collectionName);
+        
+        // Validate each document in the array
+        if (Array.isArray(documents)) {
+            for (const doc of documents) {
+                Validator.validateDocumentFields(doc);
+            }
+        }
+        
+        // Server expects {documents: [...]} format
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/import`, {
+            documents: documents
+        });
+    }
+
+    /**
+     * Compute facet counts for a collection.
+     *
+     * @param {string} collectionName
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async facetCounts(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        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,
+            `/collections/${encodeURIComponent(collectionName)}/documents/facet_counts`,
+            body,
+            queryParams
+        );
+    }
+
+    /**
+     * Export documents from a collection.
+     *
+     * @param {string} collectionName
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async export(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        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,
+            `/collections/${encodeURIComponent(collectionName)}/documents/export`,
+            body,
+            queryParams
+        );
+    }
+    
+    /**
+     * Delete documents by filter
+     * 
+     * @param {string} collectionName
+     * @param {string} filter
+     * @returns {Promise<Response>}
+     */
+    async deleteByFilter(collectionName, filter) {
+        Validator.validateCollectionName(collectionName);
+        
+        return await this.request.execute('DELETE', `/collections/${encodeURIComponent(collectionName)}/documents`, null, {
+            filter_by: filter
+        });
+    }
+}
+
+module.exports = Documents;

package/lib/Exceptions.js

@@ -0,0 +1,101 @@
+/**
+ * hlquery Node.js Client - Exceptions
+ * 
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ * 
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+/**
+ * Base exception class for hlquery client
+ */
+class HlqueryException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HlqueryException';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * Exception thrown when authentication fails
+ */
+class AuthenticationException extends HlqueryException {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationException';
+    }
+}
+
+/**
+ * Exception thrown when a request fails
+ */
+class RequestException extends HlqueryException {
+    constructor(message, statusCode = 0, responseBody = null) {
+        super(message);
+        this.name = 'RequestException';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+
+/**
+ * Exception thrown when validation fails
+ */
+class ValidationException extends HlqueryException {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationException';
+    }
+}
+
+/**
+ * Exception thrown when a collection operation fails
+ */
+class CollectionException extends HlqueryException {
+    constructor(message) {
+        super(message);
+        this.name = 'CollectionException';
+    }
+}
+
+/**
+ * Exception thrown when a document operation fails
+ */
+class DocumentException extends HlqueryException {
+    constructor(message) {
+        super(message);
+        this.name = 'DocumentException';
+    }
+}
+
+/**
+ * Exception thrown when a search operation fails
+ */
+class SearchException extends HlqueryException {
+    constructor(message) {
+        super(message);
+        this.name = 'SearchException';
+    }
+}
+
+/**
+ * Exception thrown when demo mode is enabled and write operations are blocked
+ */
+class DemoModeException extends HlqueryException {
+    constructor(message) {
+        super(message);
+        this.name = 'DemoModeException';
+    }
+}
+
+module.exports = {
+    HlqueryException,
+    AuthenticationException,
+    RequestException,
+    ValidationException,
+    CollectionException,
+    DocumentException,
+    SearchException,
+    DemoModeException
+};

package/lib/Keys.js

@@ -0,0 +1,85 @@
+/**
+ * hlquery Node.js Client - API Keys
+ * 
+ * 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');
+
+/**
+ * API Keys management operations
+ */
+class Keys {
+    constructor(request) {
+        this.request = request;
+    }
+    
+    /**
+     * List all API keys
+     * 
+     * @returns {Promise<Response>}
+     */
+    async list() {
+        return await this.request.execute('GET', '/keys');
+    }
+    
+    /**
+     * Get API key details
+     * 
+     * @param {string} id Key ID
+     * @returns {Promise<Response>}
+     */
+    async get(id) {
+        if (!id) {
+            throw new Error('Key ID is required');
+        }
+        return await this.request.execute('GET', `/keys/${id}`);
+    }
+    
+    /**
+     * Create a new API key
+     * 
+     * @param {object} params Key parameters
+     * @returns {Promise<Response>}
+     */
+    async create(params) {
+        if (!params.collections || !Array.isArray(params.collections)) {
+            throw new Error('Collections array is required');
+        }
+        if (!params.actions || !Array.isArray(params.actions)) {
+            throw new Error('Actions array is required');
+        }
+        return await this.request.execute('POST', '/keys', params);
+    }
+    
+    /**
+     * Delete an API key
+     * 
+     * @param {string} id Key ID
+     * @returns {Promise<Response>}
+     */
+    async delete(id) {
+        if (!id) {
+            throw new Error('Key ID is required');
+        }
+        return await this.request.execute('DELETE', `/keys/${id}`);
+    }
+    
+    /**
+     * Update an API key
+     * 
+     * @param {string} id Key ID
+     * @param {object} params Updated parameters
+     * @returns {Promise<Response>}
+     */
+    async update(id, params) {
+        if (!id) {
+            throw new Error('Key ID is required');
+        }
+        return await this.request.execute('PUT', `/keys/${id}`, params);
+    }
+}
+
+module.exports = Keys;

package/lib/Overrides.js

@@ -0,0 +1,53 @@
+/**
+ * hlquery Node.js Client - Overrides 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');
+
+/**
+ * Overrides API operations
+ */
+class Overrides {
+    constructor(request) {
+        this.request = request;
+    }
+
+    async list(collectionName) {
+        Validator.validateCollectionName(collectionName);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/overrides`);
+    }
+
+    async get(collectionName, id) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/overrides/${encodeURIComponent(id)}`);
+    }
+
+    async create(collectionName, id, override) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/overrides/${encodeURIComponent(id)}`, override);
+    }
+
+    async update(collectionName, id, override) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('PUT', `/collections/${encodeURIComponent(collectionName)}/overrides/${encodeURIComponent(id)}`, override);
+    }
+
+    async upsert(collectionName, id, override) {
+        return await this.create(collectionName, id, override);
+    }
+
+    async delete(collectionName, id) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(id);
+        return await this.request.execute('DELETE', `/collections/${encodeURIComponent(collectionName)}/overrides/${encodeURIComponent(id)}`);
+    }
+}
+
+module.exports = Overrides;