mbd-studio-sdk 2.1.2 → 2.2.1

package/V1/search/Search.js

@@ -1,43 +1,24 @@
-/**
- * @typedef {{ field: string, order: "asc" | "desc" }} SortBy
- */
-
 import {
-  Filter,
-  TermFilter,
-  TermsFilter,
-  NumericFilter,
-  MatchFilter,
-  GeoFilter,
-  DateFilter,
-  IsNullFilter,
-  NotNullFilter,
-  CustomFilter,
-  GroupBoostFilter,
-  TermsLookupFilter,
-  ConsoleAccountFilter,
+  Filter, TermFilter, TermsFilter, NumericFilter, MatchFilter, GeoFilter, DateFilter,
+  IsNullFilter, NotNullFilter, CustomFilter, GroupBoostFilter, TermsLookupFilter, ConsoleAccountFilter,
 } from './filters/index.js';
 
-/**
- * Search client for MBD Studio SDK.
- * Fluent API: methods return the instance for chaining.
- */
 export class Search {
-  /** @type {string} */
-  _url;
-
-  /** @type {string} */
-  _apiKey;
-
-
-  /**
-   * @param {Object} options
-   * @param {string} options.url - Search service base URL
-   * @param {string} options.apiKey - API key for authentication
-   * @param {string} [options.origin='sdk'] - origin sent in backend call payloads
-   * @param {function(string): void} [options.log] - Optional override for log(); defaults to console.log
-   * @param {function(*): void} [options.show] - Optional override for show(); defaults to console.log
-   */
+  _index = null;
+  _es_query = null;
+  _size = 100;
+  _only_ids = false;
+  _include_vector = false;
+  _select_fields = null;
+  _text = null;
+  _vector = null;
+  _sort_by = null;
+  _include = [];
+  _exclude = [];
+  _boost = [];
+  _active_array = null;
+  lastCall = null;
+  lastResult = null;
   constructor(options) {
     if (!options || typeof options !== 'object') {
       throw new Error('Search: options object is required');
@@ -55,91 +36,20 @@ export class Search {
     this._log = typeof log === 'function' ? log : console.log.bind(console);
     this._show = typeof show === 'function' ? show : console.log.bind(console);
   }
-
-  /** @type {string | null} */
-  _index = null;
-
-  /** @type {object | null} - Raw ES query for es_query endpoint */
-  _es_query = null;
-
-  /** @type {number} */
-  _size = 100;
-
-  /** @type {boolean} */
-  _only_ids = false;
-
-  /** @type {boolean} */
-  _include_vector = false;
-
-  /** @type {string[] | null} */
-  _select_fields = null;
-
-  /** @type {string | null} */
-  _text = null;
-
-  /** @type {number[] | null} */
-  _vector = null;
-
-  /** @type {SortBy | null} */
-  _sort_by = null;
-
-  /** @type {Filter[]} */
-  _include = [];
-
-  /** @type {Filter[]} */
-  _exclude = [];
-
-  /** @type {Filter[]} */
-  _boost = [];
-
-  /** @type {Filter[] | null} */
-  _active_array = null;
-
-  /** @type {{ endpoint: string, payload: object } | null} */
-  lastCall = null;
-
-  /** @type {object | null} */
-  lastResult = null;
-
-  
-  /**
-   * Return the endpoint path for the current query configuration.
-   * es_query if set; semantic if text or vector is set; boost if any boost filter; otherwise filter_and_sort.
-   * @returns {string}
-   */
   getEndpoint() {
     if (this._es_query != null) return '/search/es_query';
-    const hasTextOrVector =
-      (typeof this._text === 'string' && this._text.length > 0) ||
-      (Array.isArray(this._vector) && this._vector.length > 0);
+    const hasTextOrVector = (typeof this._text === 'string' && this._text.length > 0) || (Array.isArray(this._vector) && this._vector.length > 0);
     if (hasTextOrVector) return '/search/semantic';
     if (this._boost.length > 0) return '/search/boost';
     return '/search/filter_and_sort';
   }
-
-  /**
-   * Build the request payload for the current query.
-   * @returns {object}
-   */
   getPayload() {
     const endpoint = this.getEndpoint();
     if (endpoint === '/search/es_query') {
-      return {
-        index: this._index,
-        origin: this._origin,
-        feed_type: 'es_query',
-        query: this._es_query,
-      };
+      return { index: this._index, origin: this._origin, feed_type: 'es_query', query: this._es_query };
     }
-    const feedType =
-      endpoint === '/search/semantic'
-        ? 'semantic'
-        : endpoint === '/search/boost'
-          ? 'boost'
-          : 'filter_and_sort';
-
+    const feedType = endpoint === '/search/semantic' ? 'semantic' : endpoint === '/search/boost' ? 'boost' : 'filter_and_sort';
     const serializeFilters = (arr) => arr.map((f) => ({ ...f }));
-
     const payload = {
       index: this._index,
       origin: this._origin,
@@ -149,29 +59,16 @@ export class Search {
       include: serializeFilters(this._include),
       exclude: serializeFilters(this._exclude),
     };
-
-    if (feedType === 'boost') {
-      payload.boost = serializeFilters(this._boost);
-    }
-    if (feedType === 'filter_and_sort' && this._sort_by) {
-      payload.sort_by = this._sort_by;
-    }
+    if (feedType === 'boost') payload.boost = serializeFilters(this._boost);
+    if (feedType === 'filter_and_sort' && this._sort_by) payload.sort_by = this._sort_by;
     if (feedType === 'semantic') {
       if (typeof this._text === 'string' && this._text.length > 0) payload.text = this._text;
       if (Array.isArray(this._vector) && this._vector.length > 0) payload.vector = this._vector;
     }
     if (this._only_ids) payload.only_ids = true;
-    if (Array.isArray(this._select_fields) && this._select_fields.length > 0) {
-      payload.select_fields = this._select_fields;
-    }
-
+    if (Array.isArray(this._select_fields) && this._select_fields.length > 0) payload.select_fields = this._select_fields;
     return payload;
   }
-
-  /**
-   * Execute the search request. Sets lastCall and lastResult on success; throws on error.
-   * @returns {Promise<object>}
-   */
   async execute() {
     if (!this._index || typeof this._index !== 'string' || !this._index.trim()) {
       throw new Error('Search.execute: index must be set (call index(name) first)');
@@ -187,10 +84,7 @@ export class Search {
     const startTime = performance.now();
     const response = await fetch(url, {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this._apiKey}`,
-      },
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` },
       body: JSON.stringify(payload),
     });
     const frontendTime = Math.round(performance.now() - startTime);
@@ -210,13 +104,8 @@ export class Search {
     result.took_frontend = frontendTime;
     this.lastCall = { endpoint, payload };
     this.lastResult = result;
-
-    if (!result.result) {
-      throw new Error('Search.execute: result.result is undefined');
-    }
-
-    // Log query infos (same as InfoColumn.js)
-    const res = result.result ;
+    if (!result.result) throw new Error('Search.execute: result.result is undefined');
+    const res = result.result;
     const infos = {
       total_hits: res?.total_hits ?? 0,
       fetched_hits: res?.hits?.length ?? 0,
@@ -234,12 +123,6 @@ export class Search {
     this._log(`  max_score: ${infos.max_score}`);
     return res.hits;
   }
-
-  /**
-   * Look up a document by ID. Uses the index set by index().
-   * @param {string} docId - Document ID
-   * @returns {Promise<object>} Full response (use result.result for the document)
-   */
   async lookup(docId) {
     if (!this._index || typeof this._index !== 'string' || !this._index.trim()) {
       throw new Error('Search.lookup: index must be set (call index(name) first)');
@@ -253,9 +136,7 @@ export class Search {
     const startTime = performance.now();
     const response = await fetch(url, {
       method: 'GET',
-      headers: {
-        Authorization: `Bearer ${this._apiKey}`,
-      },
+      headers: { Authorization: `Bearer ${this._apiKey}` },
     });
     const frontendTime = Math.round(performance.now() - startTime);
     if (!response.ok) {
@@ -276,12 +157,6 @@ export class Search {
     this.lastResult = result;
     return result;
   }
-
-  /**
-   * Set the index to search.
-   * @param {string} selected_index - Index name to search
-   * @returns {this}
-   */
   index(selected_index) {
     if (typeof selected_index !== 'string' || !selected_index.trim()) {
       throw new Error('Search.index: selected_index must be a non-empty string');
@@ -289,12 +164,6 @@ export class Search {
     this._index = selected_index.trim();
     return this;
   }
-
-  /**
-   * Set the number of results to return.
-   * @param {number} size - Number of results (must be > 0 and < 2000)
-   * @returns {this}
-   */
   size(size) {
     const n = Number(size);
     if (!Number.isInteger(n) || n <= 0 || n >= 2000) {
@@ -303,79 +172,35 @@ export class Search {
     this._size = n;
     return this;
   }
-
-  /**
-   * Set whether to return only IDs in results. Call with no argument or true to enable, false to disable.
-   * @param {boolean} [value=true] - When omitted, sets to true
-   * @returns {this}
-   */
   onlyIds(value) {
     this._only_ids = value == null ? true : Boolean(value);
     return this;
   }
-
-  /**
-   * Set whether to include vectors in results. Call with no argument or true to enable, false to disable.
-   * @param {boolean} [value=true] - When omitted, sets to true
-   * @returns {this}
-   */
   includeVectors(value) {
     this._include_vector = value == null ? true : Boolean(value);
     return this;
   }
-
-  /**
-   * Set which fields to include in results. Pass an array of field names; pass null to clear.
-   * @param {string[] | null} fields - Array of field names, or null
-   * @returns {this}
-   */
   selectFields(fields) {
     if (fields === null) {
       this._select_fields = null;
       return this;
     }
-    if (!Array.isArray(fields)) {
-      throw new Error('Search.selectFields: fields must be an array of strings or null');
-    }
+    if (!Array.isArray(fields)) throw new Error('Search.selectFields: fields must be an array of strings or null');
     const normalized = fields.map((f) => (typeof f === 'string' ? f.trim() : String(f)));
-    if (normalized.some((f) => !f)) {
-      throw new Error('Search.selectFields: each field must be a non-empty string');
-    }
+    if (normalized.some((f) => !f)) throw new Error('Search.selectFields: each field must be a non-empty string');
     this._select_fields = normalized;
     return this;
   }
-
-  /**
-   * Set the text query for search.
-   * @param {string} text - Text to search
-   * @returns {this}
-   */
   text(text) {
-    if (typeof text !== 'string' || !text.trim()) {
-      throw new Error('Search.text: text must be a non-empty string');
-    }
+    if (typeof text !== 'string' || !text.trim()) throw new Error('Search.text: text must be a non-empty string');
     this._text = text.trim();
     return this;
   }
-
-  /**
-   * Set the vector for vector search.
-   * @param {number[]} vector - Vector embedding
-   * @returns {this}
-   */
   vector(vector) {
-    if (!Array.isArray(vector)) {
-      throw new Error('Search.vector: vector must be an array of numbers');
-    }
+    if (!Array.isArray(vector)) throw new Error('Search.vector: vector must be an array of numbers');
     this._vector = vector;
     return this;
   }
-
-  /**
-   * Set a raw Elasticsearch query for the es_query endpoint. Call index() before execute().
-   * @param {object} rawQuery - Raw ES query object (e.g. { query: {...}, sort: [...], size: 10 })
-   * @returns {this}
-   */
   esQuery(rawQuery) {
     if (rawQuery == null || typeof rawQuery !== 'object' || Array.isArray(rawQuery)) {
       throw new Error('Search.esQuery: rawQuery must be a plain object');
@@ -383,291 +208,118 @@ export class Search {
     this._es_query = rawQuery;
     return this;
   }
-
-  /**
-   * Set sort by field and direction.
-   * @param {string} field - Field name to sort by
-   * @param {"asc" | "desc"} [direction="desc"] - Sort direction
-   * @returns {this}
-   */
   sortBy(field, direction = 'desc') {
-    if (typeof field !== 'string' || !field.trim()) {
-      throw new Error('Search.sortBy: field must be a non-empty string');
-    }
-    if (direction !== 'asc' && direction !== 'desc') {
-      throw new Error('Search.sortBy: direction must be "asc" or "desc"');
-    }
+    if (typeof field !== 'string' || !field.trim()) throw new Error('Search.sortBy: field must be a non-empty string');
+    if (direction !== 'asc' && direction !== 'desc') throw new Error('Search.sortBy: direction must be "asc" or "desc"');
     this._sort_by = { field: field.trim(), order: direction };
     return this;
   }
-
-  /**
-   * Set the active array to include. Subsequent add operations will target _include.
-   * @returns {this}
-   */
   include() {
     this._active_array = this._include;
     return this;
   }
-
-  /**
-   * Set the active array to exclude. Subsequent add operations will target _exclude.
-   * @returns {this}
-   */
   exclude() {
     this._active_array = this._exclude;
     return this;
   }
-
-  /**
-   * Set the active array to boost. Subsequent add operations will target _boost.
-   * @returns {this}
-   */
   boost() {
     this._active_array = this._boost;
     return this;
   }
-
-  /**
-   * Ensure an active array is set. Throws if include(), exclude() or boost() was not called.
-   * @private
-   */
   _requireActiveArray() {
-    if (this._active_array === null) {
-      throw new Error(
-        'Search: call include(), exclude(), or boost() before adding filters'
-      );
-    }
+    if (this._active_array === null) throw new Error('Search: call include(), exclude(), or boost() before adding filters');
   }
-
-  /**
-   * When the active array is _boost, require a non-null boost (group_boost filter type is exempt).
-   * @private
-   * @param {number | null} boost - Boost value for convenience methods
-   */
   _requireBoostForBoostArray(boost) {
     if (this._active_array === this._boost && boost == null) {
-      throw new Error(
-        'Search: when adding to boost array, a non-null boost is required'
-      );
+      throw new Error('Search: when adding to boost array, a non-null boost is required');
     }
   }
-
-  /**
-   * Add any Filter instance to the active array (include, exclude, or boost).
-   * @param {Filter} filterInstance - A filter instance (TermFilter, NumericFilter, etc.)
-   * @returns {this}
-   */
   filter(filterInstance) {
     this._requireActiveArray();
     if (filterInstance == null || !(filterInstance instanceof Filter)) {
       throw new Error('Search.filter: argument must be a Filter instance');
     }
-    if (
-      this._active_array === this._boost &&
-      filterInstance.filter !== 'group_boost' &&
-      filterInstance.boost == null
-    ) {
-      throw new Error(
-        'Search: when adding to boost array, the filter must have a non-null boost (group_boost is exempt)'
-      );
+    if (this._active_array === this._boost && filterInstance.filter !== 'group_boost' && filterInstance.boost == null) {
+      throw new Error('Search: when adding to boost array, the filter must have a non-null boost (group_boost is exempt)');
     }
     this._active_array.push(filterInstance);
     return this;
   }
-
-  /**
-   * Add a term filter (exact match on a single value).
-   * @param {string} field - Field to filter on
-   * @param {string} value - Exact value to match
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   term(field, value, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new TermFilter(field, value, boost));
     return this;
   }
-
-  /**
-   * Add a terms filter (at least one of the values must match).
-   * @param {string} field - Field to filter on
-   * @param {string[]} values - Values to match
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   terms(field, values, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new TermsFilter(field, values, boost));
     return this;
   }
-
-  /**
-   * Add a numeric filter (range comparison).
-   * @param {string} field - Field to filter on
-   * @param {">" | ">=" | "<" | "<="} operator - Comparison operator
-   * @param {number} value - Numeric threshold
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   numeric(field, operator, value, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new NumericFilter(field, operator, value, boost));
     return this;
   }
-
-  /**
-   * Add a date range filter.
-   * @param {string} field - Date field to filter on
-   * @param {string | null} [dateFrom=null] - Start date (ISO 8601)
-   * @param {string | null} [dateTo=null] - End date (ISO 8601)
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   date(field, dateFrom = null, dateTo = null, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new DateFilter(field, dateFrom, dateTo, boost));
     return this;
   }
-
-  /**
-   * Add a geo filter (distance from coordinates).
-   * @param {string} field - Geo point field
-   * @param {string[]} value - Coordinates, e.g. ["geo:40.7128,-74.0060"]
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   geo(field, value, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new GeoFilter(field, value, boost));
     return this;
   }
-
-  /**
-   * Add a match filter (full-text keywords).
-   * @param {string} field - Text field to match against
-   * @param {string[]} value - Keywords to match
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   match(field, value, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new MatchFilter(field, value, boost));
     return this;
   }
-
-  /**
-   * Add an is_null filter (field must be missing/null).
-   * @param {string} field - Field that must be empty
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   isNull(field, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new IsNullFilter(field, boost));
     return this;
   }
-
-  /**
-   * Add a not_null filter (field must exist and have a value).
-   * @param {string} field - Field that must exist
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   notNull(field, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new NotNullFilter(field, boost));
     return this;
   }
-
-  /**
-   * Add a custom filter (raw Elasticsearch clause).
-   * @param {string} field - Ignored; use empty string if required by schema
-   * @param {Record<string, unknown>} value - Custom Elasticsearch query clause
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   custom(field, value, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new CustomFilter(field, value, boost));
     return this;
   }
-
-  /**
-   * Add a group_boost filter (hierarchical boosting from lookup index).
-   * @param {string} lookup_index - Lookup index name
-   * @param {string} field - Target field in the lookup index
-   * @param {string} value - Lookup document ID
-   * @param {string} group - Group path prefix (e.g. "label")
-   * @param {number | null} [min_boost=null] - Minimum boost
-   * @param {number | null} [max_boost=null] - Maximum boost
-   * @param {number | null} [n=null] - Number of groups
-   * @returns {this}
-   */
   groupBoost(lookup_index, field, value, group, min_boost = null, max_boost = null, n = null) {
     this._requireActiveArray();
-    this._active_array.push(
-      new GroupBoostFilter(lookup_index, field, value, group, min_boost, max_boost, n)
-    );
+    this._active_array.push(new GroupBoostFilter(lookup_index, field, value, group, min_boost, max_boost, n));
     return this;
   }
-
-  /**
-   * Add a terms_lookup filter (match from another ES document).
-   * @param {string} lookup_index - Index to look up terms from
-   * @param {string} field - Target field in the current index
-   * @param {string} value - Document ID in lookup_index
-   * @param {string} path - JSON path in the lookup document
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   termsLookup(lookup_index, field, value, path, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
-    this._active_array.push(
-      new TermsLookupFilter(lookup_index, field, value, path, boost)
-    );
+    this._active_array.push(new TermsLookupFilter(lookup_index, field, value, path, boost));
     return this;
   }
-
-  /**
-   * Add a console_account filter (match from console-accounts document).
-   * @param {string} field - Target field to match
-   * @param {string} value - Console account ID
-   * @param {string} path - JSON path in the account document
-   * @param {number | null} [boost=null] - Optional boost multiplier
-   * @returns {this}
-   */
   consoleAccount(field, value, path, boost = null) {
     this._requireActiveArray();
     this._requireBoostForBoostArray(boost);
     this._active_array.push(new ConsoleAccountFilter(field, value, path, boost));
     return this;
   }
-
-  /**
-   * Log a string.
-   * @param {string} string
-   */
   log(string) {
     this._log(string);
   }
-
-  /**
-   * Show results.
-   * @param {*} results
-   */
   show(results) {
     this._show(results);
   }
-
 }

package/V1/search/filters/ConsoleAccountFilter.js

@@ -1,15 +1,5 @@
 import { Filter } from './Filter.js';
-
-/**
- * Match field values against data from a console account document (index: console-accounts).
- */
 export class ConsoleAccountFilter extends Filter {
-  /**
-   * @param {string} field - Target field to match (e.g. "user_id", "item_id")
-   * @param {string} value - Console account ID
-   * @param {string} path - JSON path in the account document (e.g. "include_user_ids", "exclude_item_ids")
-   * @param {number | null} [boost=null] - Optional boost multiplier (0.1–100)
-   */
   constructor(field, value, path, boost = null) {
     super('console_account', field, boost);
     this.value = value;

package/V1/search/filters/CustomFilter.js

@@ -1,14 +1,5 @@
 import { Filter } from './Filter.js';
-
-/**
- * Custom Elasticsearch query clause. field is ignored by the API but required by the schema.
- */
 export class CustomFilter extends Filter {
-  /**
-   * @param {string} field - Ignored for custom filters; use empty string or placeholder if required
-   * @param {Record<string, unknown>} value - Custom Elasticsearch query clause
-   * @param {number | null} [boost=null] - Optional boost multiplier (0.1–100)
-   */
   constructor(field, value, boost = null) {
     super('custom', field, boost);
     this.value = value;