hlquery-node-client 1.0.4 → 1.0.6

package/lib/conformance.js

@@ -14,6 +14,8 @@ const NODE_CLIENT_ROUTE_COVERAGE = [
     { 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: '/metrics/history', methods: ['GET'], status: 'supported', client: 'system.metricsHistory' },
+    { path: '/metrics-history', methods: ['GET'], status: 'supported', client: 'system.metricsHistoryAlias' },
     { 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' },
@@ -35,10 +37,16 @@ const NODE_CLIENT_ROUTE_COVERAGE = [
     { 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}/lang', methods: ['GET'], status: 'supported', client: 'collections.language' },
+    { path: '/collections/{name}/aliases', methods: ['GET'], status: 'supported', client: 'aliases.listCollection' },
     { 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}/documents/{id}/context', methods: ['GET'], status: 'supported', client: 'documents.context' },
+    { path: '/collections/{name}/documents/maybe', methods: ['GET', 'POST'], status: 'supported', client: 'documents.maybe' },
+    { path: '/collections/{name}/documents/_update_by_query', methods: ['POST'], status: 'supported', client: 'documents.updateByQuery' },
+    { path: '/collections/{name}/documents/_delete_by_query', methods: ['POST'], status: 'supported', client: 'documents.deleteByQuery' },
     { 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' },
@@ -51,8 +59,11 @@ const NODE_CLIENT_ROUTE_COVERAGE = [
     { 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/improve', methods: ['POST'], status: 'supported', client: 'sam.improve' },
+    { path: '/sam/flush_actor_metadata', methods: ['POST'], status: 'supported', client: 'sam.flushActorMetadata' },
     { path: '/sam/documents', methods: ['GET'], status: 'supported', client: 'sam.listDocuments' },
     { path: '/sam/documents/{collection}/{id}', methods: ['GET'], status: 'supported', client: 'sam.getDocument/openDocument' },
+    { path: '/sam/label/add/{collection}/{id}', methods: ['POST'], status: 'supported', client: 'sam.addDocumentLabel' },
     { 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' },
@@ -71,15 +82,25 @@ const NODE_CLIENT_ROUTE_COVERAGE = [
     { 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: '/users', methods: ['GET', 'POST'], status: 'supported', client: 'users.list/create' },
+    { path: '/users/{name}', methods: ['GET', 'PUT', 'DELETE'], status: 'supported', client: 'users.get/update/delete' },
+    { path: '/analytics/click', methods: ['POST'], status: 'supported', client: 'analytics.click' },
+    { path: '/update-counters', methods: ['GET', 'POST'], status: 'supported', client: 'system.updateCounters' },
+    { path: '/debug/counters', methods: ['GET'], status: 'supported', client: 'system.debugCounters' },
     { 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.' }
+    { path: '/search-config', methods: ['GET'], status: 'supported', client: 'system.searchConfig' },
+    { path: '/ready', methods: ['GET'], status: 'supported', client: 'system.ready' },
+    { path: '/llm', methods: ['GET'], status: 'supported', client: 'system.llm' },
+    { path: '/repair', methods: ['GET', 'POST'], status: 'supported', client: 'system.repair' },
+    { path: '/modules', methods: ['GET'], status: 'supported', client: 'modules.list' },
+    { path: '/modules/load', methods: ['POST'], status: 'omitted', reason: 'Prefix alias; modules.load(name) uses the explicit /loadmodule/{name} form.' },
+    { path: '/modules/unload', methods: ['POST'], status: 'omitted', reason: 'Prefix alias; modules.unload(name) uses the explicit /unloadmodule/{name} form.' },
+    { path: '/loadmodule', methods: ['POST'], status: 'omitted', reason: 'Body-based alias; modules.load(name) uses the explicit /loadmodule/{name} form.' },
+    { path: '/loadmodule/{name}', methods: ['POST'], status: 'supported', client: 'modules.load' },
+    { path: '/unloadmodule', methods: ['POST'], status: 'omitted', reason: 'Body-based alias; modules.unload(name) uses the explicit /unloadmodule/{name} form.' },
+    { path: '/unloadmodule/{name}', methods: ['POST'], status: 'supported', client: 'modules.unload' },
+    { path: '/modules/{name}', methods: ['ANY'], status: 'supported', client: 'modules.call' },
+    { path: '/modules/{name}/syntax', methods: ['GET'], status: 'supported', client: 'modules.syntax' }
 ];
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlquery-node-client",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Node.js client library for hlquery search engine",
   "main": "index.js",
   "type": "commonjs",

package/test/offline-smoke.js

@@ -5,8 +5,17 @@ const http = require('http');
 
 const Hlquery = require('..');
 const Client = require('../lib/Client');
+const Collections = require('../lib/Collections');
+const Documents = require('../lib/Documents');
+const Aliases = require('../lib/Aliases');
 const Request = require('../lib/Request');
 const Response = require('../lib/Response');
+const SAM = require('../lib/SAM');
+const Search = require('../lib/Search');
+const System = require('../lib/System');
+const Modules = require('../lib/Modules');
+const Users = require('../lib/Users');
+const Analytics = require('../lib/Analytics');
 const Config = require('../utils/Config');
 const Validator = require('../utils/Validator');
 const CSVParser = require('../utils/CSVParser');
@@ -16,23 +25,35 @@ async function main() {
   assert.strictEqual(Hlquery.Client, Client, 'named Client export should match default export');
 
   assert.strictEqual(Config.normalizeUrl('localhost:9200/'), 'http://localhost:9200');
+  assert.strictEqual(Config.normalizeUrl(new URL('http://localhost:9200///')), 'http://localhost:9200');
   assert.strictEqual(Config.isValidUrl('http://localhost:9200'), true);
+  assert.strictEqual(Config.isValidUrl('http://'), false);
   assert.strictEqual(Config.isValidUrl('notaurl'), false);
 
   Validator.validateCollectionName('books');
   Validator.validateDocumentId('doc_123');
+  Validator.validateDocumentId('doc/with space+plus');
   Validator.validateSearchParams({ limit: 10, offset: 0 });
+  Validator.validateDocumentFields({ title: 'good,value' });
 
   assert.throws(() => Validator.validateCollectionName('123bad'), /letter or underscore/);
   assert.throws(() => Validator.validateSearchParams(null), /object/);
   assert.throws(() => Validator.validateSearchParams({ limit: NaN }), /positive integer/);
   assert.throws(() => Validator.validateSearchParams({ offset: 1.5 }), /non-negative integer/);
-  assert.throws(() => Validator.validateDocumentFields({ title: 'bad,value' }), /comma \(\,\)/);
+  assert.throws(() => Validator.validateDocumentId('bad\nid'), /control characters/);
+  assert.throws(() => Validator.validateDocumentFields({ '': 'bad field' }), /field names/);
   assert.throws(() => CSVParser.parseCSV('a||b', '||'), /single character/);
 
-  const response = new Response(200, { ok: true }, { 'content-type': 'application/json' });
+  const response = new Response(200, { ok: true }, { 'content-type': 'application/json' }, {
+    statusMessage: 'OK',
+    rawBody: Buffer.from('{"ok":true}'),
+    request: { method: 'GET', url: 'http://localhost/health' }
+  });
   assert.strictEqual(response.isSuccess(), true);
   assert.deepStrictEqual(response.getBody(), { ok: true });
+  assert.strictEqual(response.getStatusMessage(), 'OK');
+  assert.strictEqual(response.getContentType(), 'application/json');
+  assert.strictEqual(response.getRawBody().toString(), '{"ok":true}');
 
   const server = http.createServer((req, res) => {
     if (req.url === '/health') {
@@ -53,6 +74,36 @@ async function main() {
       return;
     }
 
+    if (req.url === '/modules') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ modules: ['demo'] }));
+      return;
+    }
+
+    if (req.url === '/modules/demo/syntax') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ name: 'demo', syntax: 'demo <q>' }));
+      return;
+    }
+
+    if (req.url.startsWith('/modules/demo/search') && req.method === 'GET') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ module: 'demo', route: 'search', url: req.url }));
+      return;
+    }
+
+    if (req.url === '/modules/demo/index' && req.method === 'POST') {
+      let body = '';
+      req.on('data', chunk => {
+        body += chunk.toString();
+      });
+      req.on('end', () => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ indexed: JSON.parse(body) }));
+      });
+      return;
+    }
+
     if (req.url === '/links') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ links: [] }));
@@ -77,6 +128,26 @@ async function main() {
       return;
     }
 
+    if (req.url === '/slow') {
+      setTimeout(() => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ done: true }));
+      }, 100);
+      return;
+    }
+
+    if (req.url === '/large') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ data: 'x'.repeat(128) }));
+      return;
+    }
+
+    if (req.url === '/plain') {
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('plain response');
+      return;
+    }
+
     if (req.url === '/flush' && req.method === 'POST') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ flushed: true }));
@@ -134,6 +205,45 @@ async function main() {
     assert.match(queryEcho.getBody().url, /filter=%7B%22published%22%3Atrue%7D/);
     assert.doesNotMatch(queryEcho.getBody().url, /skip=/);
 
+    const repeatedQueryEcho = await request.execute('GET', '/echo-auth', undefined, {
+      fields: ['title', 'body']
+    }, {
+      query_array_format: 'repeat'
+    });
+    assert.match(repeatedQueryEcho.getBody().url, /fields=title&fields=body/);
+
+    const plain = await request.execute('GET', '/plain');
+    assert.strictEqual(plain.isParsed(), false);
+    assert.strictEqual(plain.getBody(), 'plain response');
+    assert.strictEqual(plain.getRawBody().toString(), 'plain response');
+    assert.match(plain.getRequest().url, /\/plain$/);
+
+    await assert.rejects(
+      () => request.execute('GET', '/large', null, {}, { max_response_bytes: 32 }),
+      (error) => error.code === 'MAX_RESPONSE_BYTES' && error.statusCode === 200
+    );
+
+    await assert.rejects(
+      () => request.execute('GET', '/missing', null, {}, { throw_on_error: true }),
+      (error) => error.statusCode === 404 && error.response && error.response.getError() === 'not found'
+    );
+
+    const controller = typeof AbortController === 'function' ? new AbortController() : null;
+    if (controller) {
+      const aborted = request.execute('GET', '/slow', null, {}, { signal: controller.signal });
+      controller.abort();
+      await assert.rejects(aborted, (error) => error.code === 'ABORT_ERR');
+    }
+
+    const keepAliveAgent = new http.Agent({ keepAlive: true });
+    const agentRequest = new Request(`http://127.0.0.1:${port}`, {
+      http_agent: keepAliveAgent,
+      headers: { 'X-Test-Default': '1' }
+    });
+    const agentEcho = await agentRequest.execute('GET', '/echo-auth');
+    assert.strictEqual(agentEcho.getStatusCode(), 200);
+    keepAliveAgent.destroy();
+
     const client = new Client(`http://127.0.0.1:${port}`);
     const clientHealth = await client.health();
     assert.strictEqual(clientHealth.isSuccess(), true);
@@ -145,6 +255,32 @@ async function main() {
     const clientEtc = await client.etc();
     assert.deepStrictEqual(clientEtc.getBody(), { protocol: 'http' });
 
+    const routeEtc = await client.route('etc').get();
+    assert.deepStrictEqual(routeEtc.body, { protocol: 'http' });
+
+    const modulesList = await client.modules().list();
+    assert.deepStrictEqual(modulesList.body, { modules: ['demo'] });
+
+    const moduleSyntax = await client.modules().syntax('demo');
+    assert.deepStrictEqual(moduleSyntax.body, { name: 'demo', syntax: 'demo <q>' });
+
+    const moduleSearch = await client.module('demo').route('search').get({
+      q: 'example query'
+    });
+    assert.strictEqual(moduleSearch.body.module, 'demo');
+    assert.strictEqual(moduleSearch.body.route, 'search');
+    assert.match(moduleSearch.body.url, /q=example\+query|q=example%20query/);
+
+    const modulePost = await client.module('demo').route('index').post({
+      id: 'doc_1'
+    });
+    assert.deepStrictEqual(modulePost.body.indexed, { id: 'doc_1' });
+
+    const moduleCall = await client.modules().call('demo', 'search', 'GET', null, {
+      q: 'from call'
+    });
+    assert.match(moduleCall.body.url, /q=from\+call|q=from%20call/);
+
     const clientLinks = await client.links();
     assert.deepStrictEqual(clientLinks.getBody(), { links: [] });
 
@@ -172,15 +308,140 @@ async function main() {
     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().improve, 'function');
+    assert.strictEqual(typeof client.sam().flushActorMetadata, 'function');
     assert.strictEqual(typeof client.sam().listDocuments, 'function');
     assert.strictEqual(typeof client.sam().getDocument, 'function');
     assert.strictEqual(typeof client.sam().openDocument, 'function');
+    assert.strictEqual(typeof client.sam().addDocumentLabel, 'function');
+    assert.strictEqual(typeof client.users().list, 'function');
+    assert.strictEqual(typeof client.analytics().click, 'function');
     await assert.rejects(() => client.sam().history(null, 0), /positive integer/);
     await assert.rejects(() => client.sam().listDocuments('books', NaN, 20), /non-negative integer/);
 
     const keyResponse = await client.keys().get('key/with space');
     assert.deepStrictEqual(keyResponse.getBody(), { id: 'key/with space' });
     await assert.rejects(() => client.documents().import('books', { id: 'not-array' }), /array/);
+
+    const strictClient = new Client(`http://127.0.0.1:${port}`, { throw_on_error: true });
+    await assert.rejects(
+      () => strictClient.executeRequest('GET', '/missing'),
+      (error) => error.statusCode === 404 && error.response.getStatusCode() === 404
+    );
+
+    const fakeCollections = new Collections({
+      async execute(method, path, body) {
+        assert.strictEqual(body.name, 'books');
+        assert.strictEqual(body.extra, true);
+        return new Response(201, body);
+      }
+    });
+    const created = await fakeCollections.create('books', { name: 'books', extra: true });
+    assert.strictEqual(created.getBody().name, 'books');
+    await assert.rejects(() => fakeCollections.create('books', { name: 'other' }), /must match/);
+
+    const fieldsApi = new Collections({
+      async execute() {
+        return new Response(200, {
+          fields: [{ name: 'title', type: 'string' }],
+          searchable_fields: ['body'],
+          filterable_fields: ['author']
+        });
+      }
+    });
+    const fields = await fieldsApi.getFields('books');
+    assert.deepStrictEqual(fields.getBody().fields.map(field => field.name), ['title', 'body', 'author']);
+
+    const capturedRequests = [];
+    const captureRequest = {
+      async execute(method, path, body = null, queryParams = {}) {
+        capturedRequests.push({ method, path, body, queryParams });
+        return new Response(200, { ok: true });
+      }
+    };
+    const capturedCollections = new Collections(captureRequest);
+    const capturedDocuments = new Documents(captureRequest);
+    const capturedAliases = new Aliases(captureRequest);
+    const capturedSam = new SAM(captureRequest);
+    const capturedSystem = new System(captureRequest);
+    const capturedModules = new Modules(captureRequest);
+    const capturedUsers = new Users(captureRequest);
+    const capturedAnalytics = new Analytics(captureRequest);
+
+    await capturedCollections.language('books');
+    await capturedAliases.listCollection('books');
+    await capturedDocuments.context('books', 'doc/one');
+    await capturedDocuments.maybe('books', { q: 'bok' });
+    await capturedDocuments.updateByQuery('books', { filter_by: 'author:alice', update: { featured: true } });
+    await capturedDocuments.deleteByQuery('books', { filter_by: 'author:alice' });
+    await capturedSam.improve({ limit: 2, force: true });
+    await capturedSam.flushActorMetadata();
+    await capturedSam.addDocumentLabel('books', 'doc/one', ['featured']);
+    await capturedUsers.list();
+    await capturedUsers.get('alice smith');
+    await capturedUsers.create({ name: 'alice smith', flags: ['user'] });
+    await capturedUsers.update('alice smith', { description: 'Updated' });
+    await capturedUsers.delete('alice smith');
+    await capturedAnalytics.click({ collection: 'books', doc_id: 'doc/one', query: 'book', rank: 1 });
+    await capturedSystem.ready();
+    await capturedSystem.metricsHistory();
+    await capturedSystem.metricsHistoryAlias();
+    await capturedSystem.searchConfig();
+    await capturedSystem.llm();
+    await capturedSystem.updateCounters({ prefix: 'bench_' });
+    await capturedSystem.debugCounters();
+    await capturedSystem.repair({ collection: 'books', rebuild_index: true });
+    await capturedModules.load('demo');
+    await capturedModules.unload('demo');
+
+    assert.deepStrictEqual(capturedRequests, [
+      { method: 'GET', path: '/collections/books/lang', body: null, queryParams: {} },
+      { method: 'GET', path: '/collections/books/aliases', body: null, queryParams: {} },
+      { method: 'GET', path: '/collections/books/documents/doc%2Fone/context', body: null, queryParams: {} },
+      { method: 'GET', path: '/collections/books/documents/maybe', body: null, queryParams: { q: 'bok' } },
+      { method: 'POST', path: '/collections/books/documents/_update_by_query', body: { filter_by: 'author:alice', update: { featured: true } }, queryParams: {} },
+      { method: 'POST', path: '/collections/books/documents/_delete_by_query', body: { filter_by: 'author:alice' }, queryParams: {} },
+      { method: 'POST', path: '/sam/improve', body: null, queryParams: { limit: 2, force: true } },
+      { method: 'POST', path: '/sam/flush_actor_metadata', body: null, queryParams: {} },
+      { method: 'POST', path: '/sam/label/add/books/doc%2Fone', body: { labels: ['featured'] }, queryParams: {} },
+      { method: 'GET', path: '/users', body: null, queryParams: {} },
+      { method: 'GET', path: '/users/alice%20smith', body: null, queryParams: {} },
+      { method: 'POST', path: '/users', body: { name: 'alice smith', flags: ['user'] }, queryParams: {} },
+      { method: 'PUT', path: '/users/alice%20smith', body: { description: 'Updated' }, queryParams: {} },
+      { method: 'DELETE', path: '/users/alice%20smith', body: null, queryParams: {} },
+      { method: 'POST', path: '/analytics/click', body: { collection: 'books', doc_id: 'doc/one', query: 'book', rank: 1 }, queryParams: {} },
+      { method: 'GET', path: '/ready', body: null, queryParams: {} },
+      { method: 'GET', path: '/metrics/history', body: null, queryParams: {} },
+      { method: 'GET', path: '/metrics-history', body: null, queryParams: {} },
+      { method: 'GET', path: '/search-config', body: null, queryParams: {} },
+      { method: 'GET', path: '/llm', body: null, queryParams: {} },
+      { method: 'POST', path: '/update-counters', body: null, queryParams: { prefix: 'bench_' } },
+      { method: 'GET', path: '/debug/counters', body: null, queryParams: {} },
+      { method: 'POST', path: '/repair', body: null, queryParams: { collection: 'books', rebuild_index: true } },
+      { method: 'POST', path: '/loadmodule/demo', body: null, queryParams: {} },
+      { method: 'POST', path: '/unloadmodule/demo', body: null, queryParams: {} }
+    ]);
+
+    let collectionFetches = 0;
+    const searchApi = new Search({
+      async execute(method, path, body, queryParams) {
+        return new Response(200, { queryParams });
+      }
+    }, {
+      async get() {
+        collectionFetches += 1;
+        return new Response(200, { searchable_fields: ['title', 'body'] });
+      }
+    });
+    await searchApi.search('books', { q: 'one' });
+    await searchApi.search('books', { q: 'two' });
+    assert.strictEqual(collectionFetches, 1);
+
+    const noAutoDetect = await searchApi.search('books', {
+      q: 'three',
+      auto_detect_query_by: false
+    });
+    assert.strictEqual(noAutoDetect.getBody().queryParams.query_by, undefined);
   } finally {
     await new Promise((resolve) => server.close(resolve));
   }

package/utils/Config.js

@@ -23,6 +23,14 @@ class Config {
             timeout: options.timeout || 30000,
             token: options.token || null,
             auth_method: options.auth_method || 'bearer',
+            agent: options.agent || null,
+            http_agent: options.http_agent || null,
+            https_agent: options.https_agent || null,
+            headers: options.headers || {},
+            max_response_bytes: options.max_response_bytes || 0,
+            throw_on_error: options.throw_on_error || false,
+            query_array_format: options.query_array_format || 'comma',
+            signal: options.signal || null,
             ...options
         };
     }
@@ -34,11 +42,17 @@ class Config {
         if (!url) {
             return Config.getDefaultBaseUrl();
         }
+        if (url instanceof URL) {
+            url = url.toString();
+        }
+        if (typeof url !== 'string') {
+            url = String(url);
+        }
         url = url.trim();
         if (!url.startsWith('http://') && !url.startsWith('https://')) {
             url = 'http://' + url;
         }
-        return url.replace(/\/$/, '');
+        return url.replace(/\/+$/, '');
     }
     
     /**
@@ -47,7 +61,8 @@ class Config {
     static isValidUrl(url) {
         try {
             const urlObj = new URL(url);
-            return urlObj.protocol === 'http:' || urlObj.protocol === 'https:';
+            return (urlObj.protocol === 'http:' || urlObj.protocol === 'https:') &&
+                Boolean(urlObj.hostname);
         } catch (e) {
             return false;
         }

package/utils/Validator.js

@@ -56,12 +56,12 @@ class Validator {
             throw new ValidationException('Document ID must be between 1 and 64 characters');
         }
         
-        // Document IDs should be URL-safe: alphanumeric, underscores, and hyphens only
-        if (!/^[a-zA-Z0-9_-]+$/.test(idStr)) {
-            throw new ValidationException(
-                'Document ID contains invalid characters. ' +
-                'Use only letters, numbers, underscores, and hyphens'
-            );
+        if (idStr.trim() === '') {
+            throw new ValidationException('Document ID must be a non-empty string or number');
+        }
+
+        if (/[\x00-\x1F\x7F]/.test(idStr)) {
+            throw new ValidationException('Document ID contains control characters');
         }
     }
     
@@ -100,8 +100,7 @@ class Validator {
     }
     
     /**
-     * Validate document field values for invalid characters
-     * Commas are not allowed in string field values as they're reserved for internal parsing
+     * Validate document field values.
      * 
      * @param {object} document - Document object to validate
      * @throws {ValidationException} If document contains invalid characters
@@ -111,28 +110,12 @@ class Validator {
             return; // Skip validation for non-objects or arrays (will be validated per-item)
         }
         
-        for (const [key, value] of Object.entries(document)) {
-            // Skip the 'id' field as it has its own validation
-            if (key === 'id') continue;
-            
-            // Check string values for commas
-            if (typeof value === 'string' && value.includes(',')) {
-                throw new ValidationException(
-                    `Field '${key}' contains invalid character: comma (,). ` +
-                    `Commas are not allowed in field values. Use underscores (_) or spaces instead, or use arrays for multiple values.`
-                );
+        for (const key of Object.keys(document)) {
+            if (key === '') {
+                throw new ValidationException('Document field names must be non-empty strings');
             }
-            
-            // Check array values - ensure they don't contain strings with commas
-            if (Array.isArray(value)) {
-                for (const item of value) {
-                    if (typeof item === 'string' && item.includes(',')) {
-                        throw new ValidationException(
-                            `Field '${key}' contains invalid character: comma (,). ` +
-                            `Array items cannot contain commas. Use underscores (_) or spaces instead.`
-                        );
-                    }
-                }
+            if (/[\x00-\x1F\x7F]/.test(key)) {
+                throw new ValidationException(`Field '${key}' contains control characters`);
             }
         }
     }