Class SupplierOrbitNaturalProductDerivatives

  protected effectiveQueryCandidates(): string[] {
    if (this.effectiveQueryCandidatesCache === undefined) {
      this.effectiveQueryCandidatesCache = this.resolveEffectiveQueryCandidates();
    }
    return this.effectiveQueryCandidatesCache;
  }
Copy

  protected getAst(): ParsedSearchQuery {
    const effective = this.effectiveQuery;
    if (effective !== this.query) {
      return parseSearchQuery(effective);
    }
    return this.parsedQuery ?? parseSearchQuery(this.query);
  }
Copy

  protected async setup(): Promise<void> {}
Copy

  protected async httpGetHeaders(url: string | URL): Promise<Maybe<HeadersInit>> {
    const requestObj = new Request(this.href(url), {
      signal: this.controller.signal,
      headers: new Headers(this.headers),
      referrer: this.baseURL,
      referrerPolicy: 'strict-origin-when-cross-origin',
      body: null,
      method: 'HEAD',
      mode: 'cors',
      credentials: 'include',
    });

    try {
      const httpResponse = await this.fetch(requestObj);
      return Object.fromEntries(httpResponse.headers.entries()) satisfies HeadersInit;
    } catch (error: unknown) {
      if (error instanceof Error && error.name === 'AbortError') {
        this.logger.warn('Request was aborted', { error, signal: this.controller.signal });
        this.controller.abort('Abort signal detected');
      } else {
        this.logger.error('Error received during fetch:', {
          error,
          signal: this.controller.signal,
        });
      }
      return;
    }
  }
Copy

  protected async httpPost({
    path,
    host,
    body,
    params,
    headers,
  }: RequestOptions): Promise<Maybe<Response>> {
    this.logger.log('httpPost| Requesting:', {
      path,
      host,
      body,
      params,
      headers,
    });
    const method = 'POST';
    const mode = 'cors';
    const referrer = this.baseURL;
    const referrerPolicy = 'strict-origin-when-cross-origin';
    const signal = this.controller.signal;
    const headersObj = new Headers({
      ...this.headers,
      ...headers,
    });

    let bodyStr = null;
    if (body instanceof FormData) {
      headersObj.set('Content-Type', 'application/x-www-form-urlencoded; charset=UTF-8');
      bodyStr = body;
    } else if (typeof body === 'string') {
      bodyStr = body;
    } else if (typeof body === 'object' && body !== null) {
      bodyStr = JSON.stringify(body);
    }
    const url = this.href(path, params, host);

    const requestObj = new Request(url, {
      signal,
      headers: headersObj,
      referrer,
      referrerPolicy,
      body: bodyStr,
      method,
      mode,
      credentials: 'include',
    });

    // Fetch the goods
    const httpResponse = await this.fetch(requestObj);

    if (!isHttpResponse(httpResponse) || !httpResponse.ok) {
      const badResponse = await httpResponse.text();
      this.logger.error('Invalid POST response: ', badResponse);
      throw new TypeError(`Invalid POST response: ${String(httpResponse)}`);
    }

    return httpResponse;
  }
Copy

  protected async httpPostFormData({
    path,
    host,
    body,
    params,
    headers,
  }: RequestOptions): Promise<Maybe<Response>> {
    if (typeof body !== 'object' || body === null) {
      throw new TypeError('httpPostFormData| Body must be an object');
    }

    headers = {
      ...headers,
      'Content-Type': 'application/x-www-form-urlencoded',
    };
    const formData = new FormData();
    for (const [key, value] of Object.entries(body)) {
      formData.append(key, value);
    }
    const httpResponse = await this.httpPost({ path, host, body: formData, params, headers });
    if (!isHttpResponse(httpResponse) || !httpResponse.ok) {
      const badResponse = await httpResponse?.text();
      this.logger.error('Invalid POST response: ', badResponse);
      throw new TypeError(`Invalid POST response: ${String(httpResponse)}`);
    }
    this.logger.log('httpPostFormData| Successfully sent POST request to:', path);
    return httpResponse;
  }
Copy

  protected async httpPostJson({
    path,
    host,
    body,
    params,
    headers,
  }: RequestOptions): Promise<Maybe<JsonValue>> {
    const httpResponse = await this.httpPost({ path, host, body, params, headers });
    if (!isJsonResponse(httpResponse) || !httpResponse.ok) {
      this.logger.error('httpPostJson| Invalid POST response: ', {
        httpResponse,
        path,
        host,
        body,
        params,
        headers,
      });
      throw new TypeError(`httpPostJson| Invalid POST response: ${httpResponse}`);
    }
    return await httpResponse.json();
  }
Copy

  protected async httpPostHtml({
    path,
    host,
    body,
    params,
    headers,
  }: RequestOptions): Promise<Maybe<string>> {
    const httpResponse = await this.httpPost({ path, host, body, params, headers });
    if (!isHtmlResponse(httpResponse)) {
      throw new TypeError(`httpPostHtml| Invalid POST response: ${httpResponse}`);
    }
    return await httpResponse.text();
  }
Copy

  protected async httpGet({
    path,
    params,
    headers,
    host,
    rethrowErrors,
  }: RequestOptions): Promise<Maybe<Response>> {
    // Check if the request has been aborted before proceeding
    if (this.controller.signal.aborted) {
      this.logger.warn('Request was aborted before fetch', {
        signal: this.controller.signal,
      });
      return;
    }

    const headersRaw = { ...this.headers };

    Object.assign(headersRaw, {
      accept: [
        'text/html',
        'application/xhtml+xml',
        'application/xml;q=0.9',
        'image/avif',
        'image/webp',
        'image/apng',
        '*/*;q=0.8',
      ].join(','),
      ...(headers ?? {}),
    });

    const requestObj = new Request(this.href(path, params, host), {
      signal: this.controller.signal,
      headers: new Headers(headersRaw),
      referrer: this.baseURL,
      referrerPolicy: 'no-referrer',
      body: null,
      method: 'GET',
      mode: 'cors',
      credentials: 'include',
      redirect: 'follow',
    });

    try {
      // Fetch the goods
      const httpResponse = await this.fetch(requestObj.url, requestObj);

      const responseHeaders = Object.fromEntries(
        httpResponse.headers.entries(),
      ) satisfies HeadersInit;
      this.logger.debug('responseHeaders:', responseHeaders);
      this.logger.debug('responseHeaders.location:', responseHeaders.location);

      return httpResponse;
    } catch (error: unknown) {
      if (error instanceof Error && error.name === 'AbortError') {
        this.logger.warn('Request was aborted', { error, signal: this.controller.signal });
        this.controller.abort('Abort signal detected');
        return;
      }
      this.logger.error('Error received during fetch:', {
        error,
        signal: this.controller.signal,
      });
      // Opt-in: surface the failure (e.g. an HttpError 429) so the caller can apply
      // status-aware retry/backoff. Default behavior remains swallow-and-return-undefined.
      if (rethrowErrors) {
        throw error;
      }
      return;
    }
  }
Copy

  protected fuzzyScore(text: string): number {
    const activeScorer = this.fuzzScorerOverride ?? this.fuzzScorer;
    // Score against every effective-query candidate and keep the best — for an
    // identifier query these are the resolved name + synonyms, so a product
    // matches whichever name it names. A plain query has a single candidate.
    let best = 0;
    for (const candidate of this.effectiveQueryCandidates()) {
      const score = activeScorer(candidate, text);
      if (score > best) {
        best = score;
      }
    }
    return best;
  }
Copy

  protected fuzzyFilter<X>(
    query: string,
    data: X[],
    minMatchPercentage: number = this.minMatchPercentage,
  ): X[] {
    // User's Advanced-settings override wins over the subclass default.
    const activeScorer = this.fuzzScorerOverride ?? this.fuzzScorer;

    // console.log(
    //   `[fuzzyFilter] ${this.supplierName} query="${query}" — scorer comparison (cutoff=${minMatchPercentage})`,
    // );

    if (IS_DEV_BUILD) {
      this.showFuzzScorerComparisonTable(query, data);
    }

    if (this.fuzzyFilterRankOnly) {
      // Rank every candidate by score (no cutoff) and return them in score order; the
      // caller slices the top N. Avoids dropping clear matches whose ratio-style score
      // falls under minMatchPercentage purely because the title dwarfs the query.
      return extract(query, data, {
        scorer: activeScorer,
        processor: this.titleSelector,
        sortBySimilarity: true,
      }).map(([obj, score, idx]) => this.attachFuzz(obj, score, idx));
    }

    const results = extract(query, data, {
      scorer: activeScorer,
      processor: this.titleSelector,
      cutoff: minMatchPercentage,
      sortBySimilarity: true,
    }).reduce<FuzzyMatchResult<X>[]>((acc, [obj, score, idx]) => {
      if (score < minMatchPercentage) {
        this.logger.debug('fuzzyFilter: score below minimum match percentage, excluding product', {
          product: obj,
          score,
          idx,
          minMatchPercentage: minMatchPercentage,
        });
        return acc;
      }

      acc[idx] = Object.assign(obj, { _fuzz: { score, idx }, matchPercentage: score });
      return acc;
    }, []);

    this.logger.debug('[fuzzyFilter]', {
      supplierName: this.supplierName,
      query,
      minMatchPercentage,
      activeScorer,
      results,
    });

    // Get rid of any empty items that didn't match closely enough
    return results.filter((item) => !!item);
  }
Copy

  protected fuzzyFilterAst<X>(
    data: X[],
    minMatchPercentage: number = this.minMatchPercentage,
  ): X[] {
    const parsed = this.getAst();

    if (!parsed.isAdvanced) {
      // Plain query: no filtering when disabled; the multi-candidate path for a
      // resolved identifier query (several candidate names); else the legacy
      // single-query fuzzy path.
      if (this.fuzzyFilteringDisabled) {
        return data;
      }
      if (this.effectiveQueryCandidates().length > 1) {
        return this.fuzzyFilterCandidates(data, minMatchPercentage);
      }
      return this.fuzzyFilter(parsed.raw.trim(), data, minMatchPercentage);
    }

    const scorer = this.fuzzScorerOverride ?? this.fuzzScorer;
    // Rank-only floors the leaf score at 0 so predicate-matching items are never dropped
    // for a low fuzz score; the sort below still ranks them. Otherwise enforce the cutoff.
    const threshold = this.fuzzyFilteringDisabled
      ? 1
      : this.fuzzyFilterRankOnly
        ? 0
        : minMatchPercentage;
    const fuzzyWords = !this.fuzzyFilteringDisabled;

    const matched = data.reduce<FuzzyMatchResult<X>[]>((acc, obj, idx) => {
      const title = this.titleSelector(obj) ?? '';
      const score = scoreAstMatch(title, parsed.ast, { scorer, threshold, fuzzyWords });
      if (score === null) {
        return acc;
      }
      acc.push(this.attachFuzz(obj, score, idx));
      return acc;
    }, []);

    // Rank by relevance when fuzzing; preserve backend order when disabled.
    if (!this.fuzzyFilteringDisabled) {
      matched.sort((a, b) => (b.matchPercentage ?? 0) - (a.matchPercentage ?? 0));
    }
    return matched;
  }
Copy

  protected fuzzyScoreAst(text: string): number | null {
    const parsed = this.getAst();

    if (!parsed.isAdvanced) {
      if (this.fuzzyFilteringDisabled) {
        return 100;
      }
      const score = this.fuzzyScore(text);
      return score >= this.minMatchPercentage ? score : null;
    }

    const scorer = this.fuzzScorerOverride ?? this.fuzzScorer;
    const threshold = this.fuzzyFilteringDisabled ? 1 : this.minMatchPercentage;
    return scoreAstMatch(text, parsed.ast, {
      scorer,
      threshold,
      fuzzyWords: !this.fuzzyFilteringDisabled,
    });
  }
Copy

  protected deriveFallbackTerms(): string[] {
    const groups = extractOrGroups(this.getAst().ast);

    // How many AND-groups each term appears in — a term shared across groups (a
    // common factor, e.g. "Hydroxide" in "(Sodium OR Potassium) AND Hydroxide")
    // covers more of the query in fewer requests, so prefer it; break ties by
    // length (more selective). Picking one representative term per group keeps
    // each request's result set a superset of that group's matches.
    const frequency = new Map<string, number>();
    for (const group of groups) {
      for (const term of new Set(group)) {
        frequency.set(term, (frequency.get(term) ?? 0) + 1);
      }
    }

    const terms = groups
      .map(
        (group) =>
          group.slice().sort((a, b) => {
            const byFrequency = (frequency.get(b) ?? 0) - (frequency.get(a) ?? 0);
            return byFrequency !== 0 ? byFrequency : b.length - a.length;
          })[0],
      )
      .filter((term): term is string => Boolean(term));

    return [...new Set(terms)].slice(0, this.maxFallbackQueries);
  }
Copy

  protected async httpGetHtml({
    path,
    params,
    headers,
    host,
  }: RequestOptions): Promise<Maybe<string>> {
    const httpResponse = await this.httpGet({ path, params, headers, host });
    if (!isHtmlResponse(httpResponse)) {
      throw new TypeError(`httpGetHtml| Invalid GET response: ${httpResponse}`);
    }
    return await httpResponse.text();
  }
Copy

  protected async httpGetJson({
    path,
    params,
    headers = {},
    host,
  }: RequestOptions): Promise<Maybe<JsonValue>> {
    if (
      typeof headers?.accept === 'undefined' ||
      !Array.isArray(headers?.accept) ||
      !headers?.accept.includes('application/json')
    ) {
      headers.accept = ['application/json', 'text/plain', '*/*'].join(',');
    }
    const httpRequest = await this.httpGet({ path, params, headers, host });

    if (!isJsonResponse(httpRequest)) {
      const badResponse = isHttpResponse(httpRequest) ? await httpRequest.text() : undefined;
      this.logger.error('Invalid HTTP GET JSON response:', {
        badResponse,
        httpRequest,
        path,
        params,
        headers,
        host,
      });
      return;
    }

    return await httpRequest.json();
  }
Copy

  protected async queryProductsWithCache(
    query: string,
    limit: number = this.limit,
  ): Promise<ProductBuilder<T>[] | void> {
    // Check cache first (processed product data)
    this.logger.debug(
      'queryProductsWithCache: called for',
      this.supplierName,
      'query:',
      query,
      'limit:',
      limit,
    );
    const key = this.cache.generateCacheKey(query);
    const cached = await this.cache.getCachedQueryEntry(key);
    this.logger.debug('queryProductsWithCache: cache hit:', !!cached, 'key:', key);
    if (cached) {
      const cachedLimit = cached.__cacheMetadata.limit;
      const insufficientLimit = typeof cachedLimit === 'number' && cachedLimit < limit;
      if (!insufficientLimit) {
        this.logger.debug('Returning cached query results');
        // Re-initialize product builders from cached processed data
        return ProductBuilder.createFromCache<T>(this.baseURL, cached.data.slice(0, limit));
      }
      // Cached entry was built with a smaller limit than requested — drop it and re-query below.
      this.logger.debug('Invalidating query cache due to insufficient limit', {
        cachedLimit,
        requestedLimit: limit,
      });
      await deleteSupplierQueryCacheEntry(key);
    }

    // If not in cache, perform the actual query. Run setup first so any
    // subclass state it mutates (headers, localStorage, tokens, etc.) is
    // in place before `queryProducts` reads it. Memoized, so this is cheap
    // on repeat calls within the same supplier instance.
    await this.ensureSetup();
    const results = await this.queryProductsResolved(query, limit);
    if (results) {
      // Store processed results in cache (dumped/serialized form) and the limit used
      await this.cache.cacheQueryResults(
        query,
        results.map((b) => b.dump()),
        limit,
      );
    }
    return results;
  }
Copy

  protected async queryProductsResolved(
    query: string,
    limit: number,
  ): Promise<ProductBuilder<T>[] | void> {
    const parsed = this.getAst();
    if (!parsed.isAdvanced || this.supportsNativeAdvancedSearch) {
      return this.queryProducts(query, limit);
    }

    const terms = this.deriveFallbackTerms();
    if (terms.length <= 1) {
      // Nothing to union (single positive term, or a purely negative query):
      // run the raw query once and let fuzzyFilterAst enforce the predicate.
      return this.queryProducts(terms[0] ?? query, limit);
    }

    const seen = new Set<string>();
    const union: ProductBuilder<T>[] = [];
    for (const term of terms) {
      if (this.requestCount >= this.httpRequestHardLimit) {
        this.logger.warn('queryProductsResolved: httpRequestHardLimit reached, stopping fallback', {
          term,
          requestCount: this.requestCount,
        });
        break;
      }
      const batch = await this.queryProducts(term, limit);
      if (!batch) {
        continue;
      }
      for (const builder of batch) {
        const key = String(builder.get('url') ?? builder.get('id') ?? builder.get('title') ?? '');
        if (key === '' || seen.has(key)) {
          continue;
        }
        seen.add(key);
        union.push(builder);
      }
    }
    return union.length > 0 ? union : undefined;
  }
Copy