Class SupplierBaseShopifyAbstract

  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();
      } 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>> {
    const method = "POST";
    const mode = "cors";
    const referrer = this.baseURL;
    const referrerPolicy = "strict-origin-when-cross-origin";
    const signal = this.controller.signal;
    const bodyStr = typeof body === "string" ? body : (JSON.stringify(body) ?? null);
    const headersObj = new Headers({
      ...this.headers,
      ...headers,
    });
    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: ${httpResponse?.toString()}`);
    }

    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,
  }: 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();
      } else {
        this.logger.error("Error received during fetch:", {
          error,
          signal: this.controller.signal,
        });
      }
      return;
    }
  }
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);
    }

    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;
      }

      // eslint-disable-next-line @typescript-eslint/naming-convention
      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 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>> {
    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) {
      // If the cached limit is less than the requested limit, invalidate the cache
      if (
        typeof cached.__cacheMetadata.limit === "number" &&
        cached.__cacheMetadata.limit < limit
      ) {
        this.logger.debug("Invalidating query cache due to insufficient limit", {
          cachedLimit: cached.__cacheMetadata.limit,
          requestedLimit: limit,
        });
        await deleteSupplierQueryCacheEntry(key);
      } else {
        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));
      }
    }

    // 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.queryProducts(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 finishProduct(product: ProductBuilder<T>): Promise<Maybe<T>> {
    if (!isMinimalProduct(product.dump())) {
      this.logger.warn("Unable to finish product - Minimum data not set", { product });
      return;
    }

    // Set the country and shipping scope of the supplier
    // have different restrictions on different products or countries.
    product.setSupplierCountry(this.country);
    product.setSupplierShipping(this.shipping);

    if (this.paymentMethods.length > 0) {
      product.setSupplierPaymentMethods(this.paymentMethods);
    }

    const built = await product.build();
    return built;
  }
Copy

  protected href(path: string | URL, params?: Maybe<RequestParams>, host?: string): string {
    const href = new URL(path, this.baseURL);

    if (host) {
      href.host = host;
    }

    if (params && Object.keys(params).length > 0) {
      href.search = new URLSearchParams(
        Object.entries(params).reduce<QueryParams>((acc, [key, value]) => {
          acc[key] = String(value);
          return acc;
        }, {}),
      ).toString();
    }

    return href.toString();
  }
Copy

  protected async getProductDataWithCache(
    product: ProductBuilder<T>,
    fetcher: (builder: ProductBuilder<T>) => Promise<ProductBuilder<T> | void>,
    params?: QueryParams,
  ): Promise<ProductBuilder<T> | void> {
    const url = product.get("url");
    if (typeof url !== "string") {
      this.logger.error("Invalid URL in product:", { url });
      return undefined;
    }
    // See getProductData above: normalize only for the exclusion key so it
    // lines up with the absolute URL the UI context menu stores.
    const exclusionUrl = this.href(url);
    const shouldExclude = await shouldExcludeProduct(exclusionUrl, this.supplierName);
    if (shouldExclude) {
      this.logger.debug("Skipping excluded product", {
        url,
        exclusionUrl,
        supplierName: this.supplierName,
      });
      return undefined;
    }

    const cacheKey = this.cache.getProductDataCacheKey(url, params);
    this.logger.debug("[SupplierBase] Product detail cache key:", cacheKey, "for url:", url);
    try {
      const cachedData = await this.cache.getCachedProductData(cacheKey);
      if (cachedData) {
        // Safe: cache only stores values previously produced by ProductBuilder<T>.dump(),
        // so the round-tripped shape is structurally a Partial<T>.
        product.setData(cachedData as Partial<T>);
        return product;
      }
      // Cache miss: run setup (memoized) so any state subclasses rely on is
      // ready before the fetcher reads it, then call the fetcher.
      await this.ensureSetup();
      let resultBuilder: ProductBuilder<T> | void = undefined;
      try {
        resultBuilder = await fetcher(product);
      } catch (err: unknown) {
        this.logger.error("Error in product detail fetcher:", err);
        incrementParseError(this.supplierName);
        return undefined;
      }
      if (resultBuilder) {
        incrementProductCount(this.supplierName);
        await this.cache.cacheProductData(cacheKey, resultBuilder.dump());
      }
      return resultBuilder;
    } catch (outerErr: unknown) {
      this.logger.error("Error in getProductDataWithCache:", outerErr);
      incrementParseError(this.supplierName);
      return undefined;
    }
  }
Copy

  protected groupVariants<R>(data: R[]): R[] {
    const variants: GroupedItem<R>[] = data
      .map((item) => {
        const title = this.titleSelector(item);
        if (!title) {
          this.logger.error("No title found in product:", { item });
          return undefined;
        }
        const groupId = stripQuantityFromString(title.replace(/(?<=\d{1,3})\s(?=\d{3})/g, ""));
        const groupIdWithoutSpaces = groupId.replace(/[\s-]/g, "");
        return { ...item, groupId: groupIdWithoutSpaces };
      })
      .filter((item): item is GroupedItem<R> => item !== undefined);

    const products = Object.groupBy(variants, (item) => item.groupId);

    return Object.values(products)
      .filter((product): product is GroupedItem<R>[] => product !== undefined)
      .map((product) => {
        const main = product.splice(0, 1)[0];
        // eslint-disable-next-line @typescript-eslint/no-unused-vars
        const { groupId, ...newObject } = main;
        newObject.variants = product as GroupedItem<R>["variants"];

        return newObject;
      })
      .filter((item): item is GroupedItem<R> => item !== undefined);
  }
Copy

  protected async fetch(
    ...args: Parameters<typeof fetchDecorator>
  ): Promise<FetchDecoratorResponse> {
    const [input] = args;
    this.logger.debug(`Fetching: ${input}`);

    // One initial attempt plus up to `challengeRetryLimit` retries. A 403 from
    // a WAF cookie handshake plants a cookie on the first hit (stored because
    // credentials:"include"); the retry sends it back and usually passes.
    const maxAttempts = 1 + Math.max(0, this.challengeRetryLimit);

    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      // Each attempt is a real network request, so it counts toward the hard
      // limit. For non-retrying suppliers (maxAttempts === 1) this is
      // identical to the previous single increment.
      this.requestCount++;
      if (this.requestCount > this.httpRequestHardLimit) {
        this.logger.warn("Request count exceeded hard limit", { requestCount: this.requestCount });
        incrementFailure(this.supplierName);
        throw new Error("Request count exceeded hard limit");
      }

      try {
        const response = await fetchDecorator(...args);
        this.logger.debug(`Response Status: ${response.status}`);
        this.logger.debug("response hash:", response.requestHash);
        if (typeof response.data === "string" && response.data?.length === 0) {
          throw new EmptyResponseError(`Invalid response: ${response.data}`);
        }
        incrementSuccess(this.supplierName);
        return response;
      } catch (error: unknown) {
        if (this.shouldRetryChallenge(error) && attempt < maxAttempts) {
          this.logger.warn("Retrying after 403 (WAF cookie handshake)", {
            attempt,
            maxAttempts,
            input,
          });
          await new Promise((resolve) => setTimeout(resolve, this.challengeRetryDelayMs));
          continue;
        }
        incrementFailure(this.supplierName);
        throw error;
      }
    }

    // Unreachable: the loop always returns on success or throws on the final
    // failed attempt. Present only to satisfy the return-type checker.
    throw new Error("fetch: exhausted retries without resolving");
  }
Copy