mbd-studio-sdk 2.0.3

package/V1/search/Search.js

@@ -0,0 +1,673 @@
+/**
+ * @typedef {{ field: string, order: "asc" | "desc" }} SortBy
+ */
+
+import {
+  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
+   */
+  constructor(options) {
+    if (!options || typeof options !== 'object') {
+      throw new Error('Search: options object is required');
+    }
+    const { url, apiKey, origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) {
+      throw new Error('Search: options.url is required and must be a non-empty string');
+    }
+    if (typeof apiKey !== 'string' || !apiKey.trim()) {
+      throw new Error('Search: options.apiKey is required and must be a non-empty string');
+    }
+    this._url = url.trim().replace(/\/$/, '');
+    this._apiKey = apiKey.trim();
+    this._origin = typeof origin === 'string' && origin.trim() ? origin.trim() : 'sdk';
+    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);
+    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,
+      };
+    }
+    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,
+      feed_type: feedType,
+      include_vector: this._include_vector,
+      size: this._size,
+      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 === '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;
+    }
+
+    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)');
+    }
+    if (this._es_query != null && (typeof this._es_query !== 'object' || Array.isArray(this._es_query))) {
+      throw new Error('Search.execute: esQuery() must be called with a plain object (e.g. { query: {...}, sort: [...] })');
+    }
+    const endpoint = this.getEndpoint();
+    const payload = this.getPayload();
+    const url = `${this._url}${endpoint}`;
+    this.log(`Sending request to ${url}`);
+    this.log(`Payload:\n${JSON.stringify(payload, null, 2)}`);
+    const startTime = performance.now();
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this._apiKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+    const frontendTime = Math.round(performance.now() - startTime);
+    if (!response.ok) {
+      const text = await response.text();
+      let message = `Search API error: ${response.status} ${response.statusText}`;
+      if (text) message += ` — ${text}`;
+      this.log(message);
+      throw new Error(message);
+    }
+    const result = await response.json();
+    if (result && typeof result.error !== 'undefined' && result.error !== null) {
+      const msg = typeof result.error === 'string' ? result.error : String(result.error);
+      this.log(msg);
+      throw new Error(msg);
+    }
+    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 ;
+    const infos = {
+      total_hits: res?.total_hits ?? 0,
+      fetched_hits: res?.hits?.length ?? 0,
+      took_es_ms: res?.took_es ?? 0,
+      took_backend_ms: res?.took_backend ?? 0,
+      took_frontend_ms: result.took_frontend,
+      max_score: res?.max_score ?? 0,
+    };
+    this._log('Search result:');
+    this._log(`  total_hits: ${infos.total_hits}`);
+    this._log(`  fetched_hits: ${infos.fetched_hits}`);
+    this._log(`  took_es_ms: ${infos.took_es_ms}`);
+    this._log(`  took_backend_ms: ${infos.took_backend_ms}`);
+    this._log(`  took_frontend_ms: ${infos.took_frontend_ms}`);
+    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)');
+    }
+    if (typeof docId !== 'string' || !docId.trim()) {
+      throw new Error('Search.lookup: docId must be a non-empty string');
+    }
+    const endpoint = `/search/document/${encodeURIComponent(this._index)}/${encodeURIComponent(docId.trim())}`;
+    const url = `${this._url}${endpoint}`;
+    this.log(`GET ${url}`);
+    const startTime = performance.now();
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${this._apiKey}`,
+      },
+    });
+    const frontendTime = Math.round(performance.now() - startTime);
+    if (!response.ok) {
+      const text = await response.text();
+      let message = `Search lookup error: ${response.status} ${response.statusText}`;
+      if (text) message += ` — ${text}`;
+      this.log(message);
+      throw new Error(message);
+    }
+    const result = await response.json();
+    if (result && typeof result.error !== 'undefined' && result.error !== null) {
+      const msg = typeof result.error === 'string' ? result.error : String(result.error);
+      this.log(msg);
+      throw new Error(msg);
+    }
+    result.took_frontend = frontendTime;
+    this.lastCall = { endpoint, payload: null };
+    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');
+    }
+    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) {
+      throw new Error('Search.size: size must be an integer > 0 and < 2000');
+    }
+    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');
+    }
+    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');
+    }
+    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');
+    }
+    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');
+    }
+    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');
+    }
+    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"');
+    }
+    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'
+      );
+    }
+  }
+
+  /**
+   * 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'
+      );
+    }
+  }
+
+  /**
+   * 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)'
+      );
+    }
+    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)
+    );
+    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)
+    );
+    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

@@ -0,0 +1,18 @@
+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;
+    this.path = path;
+  }
+}

package/V1/search/filters/CustomFilter.js

@@ -0,0 +1,16 @@
+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;
+  }
+}