blackbox_db 0.1.0

package/index.js

@@ -0,0 +1,195 @@
+/**
+ * BlackBox DB HTTP client.
+ * Uses global fetch (Node 18+). Throws on HTTP/network errors.
+ */
+export class BlackBoxClient {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.url="http://127.0.0.1"] - Base URL including protocol/host.
+   * @param {number} [options.port=8080] - Port to connect to.
+   */
+  constructor({ url = "http://127.0.0.1", port = 8080 } = {}) {
+    this.baseUrl = this._buildBaseUrl(url, port);
+  }
+
+  _buildBaseUrl(url, port) {
+    if (!url) throw new Error("url is required");
+    const normalized = url.endsWith("/") ? url.slice(0, -1) : url;
+    return port ? `${normalized}:${port}` : normalized;
+  }
+
+  _toQuery(params = {}) {
+    const query = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value === undefined || value === null) return;
+      query.append(key, String(value));
+    });
+    const qs = query.toString();
+    return qs ? `?${qs}` : "";
+  }
+
+  async _request(path, options = {}) {
+    const endpoint = `${this.baseUrl}${path}`;
+    const headers = { ...(options.headers || {}) };
+    if (options.body && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    const response = await fetch(endpoint, { ...options, headers });
+    const contentType = response.headers.get("content-type") || "";
+    const isJson = contentType.includes("application/json");
+    const payload = isJson ? await response.json().catch(() => null) : null;
+
+    if (!response.ok) {
+      const message = payload?.error?.message || response.statusText || "Request failed";
+      throw new Error(`HTTP ${response.status} ${message}`);
+    }
+
+    return payload ?? (await response.text());
+  }
+
+  // Health & config
+  async health() {
+    return this._request("/v1/health");
+  }
+
+  async metrics() {
+    return this._request("/v1/metrics");
+  }
+
+  async prometheusMetrics() {
+    return this._request("/metrics", { headers: { Accept: "text/plain" } });
+  }
+
+  async config() {
+    return this._request("/v1/config");
+  }
+
+  // Index management
+  async createIndex(body) {
+    return this._request("/v1/indexes", { method: "POST", body: JSON.stringify(body) });
+  }
+
+  async listIndexes() {
+    return this._request("/v1/indexes");
+  }
+
+  // Snapshots / shipping
+  async saveSnapshot(path) {
+    const qs = this._toQuery(path ? { path } : {});
+    return this._request(`/v1/snapshot${qs}`, { method: "POST" });
+  }
+
+  async loadSnapshot(path) {
+    const qs = this._toQuery(path ? { path } : {});
+    return this._request(`/v1/snapshot/load${qs}`, { method: "POST" });
+  }
+
+  async shipPlan() {
+    return this._request("/v1/ship");
+  }
+
+  async shipApply(path) {
+    if (!path) throw new Error("path is required");
+    return this._request(`/v1/ship/apply${this._toQuery({ path })}`, { method: "POST" });
+  }
+
+  async shipFetchApply(base) {
+    if (!base) throw new Error("base is required");
+    return this._request(`/v1/ship/fetch_apply${this._toQuery({ base })}`, { method: "POST" });
+  }
+
+  // Documents
+  async indexDocument(index, doc) {
+    if (!index) throw new Error("index is required");
+    return this._request(`/v1/${encodeURIComponent(index)}/doc`, {
+      method: "POST",
+      body: JSON.stringify(doc),
+    });
+  }
+
+  async bulkIndex(index, docs, { continueOnError = true } = {}) {
+    if (!index) throw new Error("index is required");
+    return this._request(`/v1/${encodeURIComponent(index)}/_bulk?continue_on_error=${continueOnError}`, {
+      method: "POST",
+      body: JSON.stringify(Array.isArray(docs) ? docs : { docs }),
+    });
+  }
+
+  async getDocument(index, id) {
+    if (!index || id === undefined || id === null) throw new Error("index and id are required");
+    return this._request(`/v1/${encodeURIComponent(index)}/doc/${encodeURIComponent(id)}`);
+  }
+
+  async replaceDocument(index, id, doc) {
+    if (!index || id === undefined || id === null) throw new Error("index and id are required");
+    return this._request(`/v1/${encodeURIComponent(index)}/doc/${encodeURIComponent(id)}`, {
+      method: "PUT",
+      body: JSON.stringify(doc),
+    });
+  }
+
+  async updateDocument(index, id, doc) {
+    if (!index || id === undefined || id === null) throw new Error("index and id are required");
+    return this._request(`/v1/${encodeURIComponent(index)}/doc/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: JSON.stringify(doc),
+    });
+  }
+
+  async deleteDocument(index, id) {
+    if (!index || id === undefined || id === null) throw new Error("index and id are required");
+    return this._request(`/v1/${encodeURIComponent(index)}/doc/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+    });
+  }
+
+  async storedMatch(index, { field, value }) {
+    if (!index) throw new Error("index is required");
+    if (!field) throw new Error("field is required");
+    if (value === undefined || value === null) throw new Error("value is required");
+    return this._request(
+      `/v1/${encodeURIComponent(index)}/stored_match${this._toQuery({ field, value })}`
+    );
+  }
+
+  /**
+   * Run a search query.
+   * @param {string} index - Index name.
+   * @param {Object} params - Querystring parameters (e.g., q, mode, from, size, vec).
+   */
+  async search(index, params = {}) {
+    if (!index) throw new Error("index is required");
+    return this._request(
+      `/v1/${encodeURIComponent(index)}/search${this._toQuery(params)}`
+    );
+  }
+
+  // Custom aggregations/templates
+  async listCustomTemplates() {
+    return this._request("/v1/custom");
+  }
+
+  async getCustomTemplate(name) {
+    if (!name) throw new Error("name is required");
+    return this._request(`/v1/custom/${encodeURIComponent(name)}`);
+  }
+
+  async putCustomTemplate(name, template) {
+    if (!name) throw new Error("name is required");
+    return this._request(`/v1/custom/${encodeURIComponent(name)}`, {
+      method: "PUT",
+      body: JSON.stringify(template),
+    });
+  }
+
+  async executeCustomTemplate(name, params = {}) {
+    if (!name) throw new Error("name is required");
+    return this._request(`/v1/custom/${encodeURIComponent(name)}`, {
+      method: "POST",
+      body: JSON.stringify(params),
+    });
+  }
+}
+
+export default BlackBoxClient;

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "blackbox_db",
+  "version": "0.1.0",
+  "description": "",
+  "license": "ISC",
+  "author": "Skidaux",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}