Class SupplierBase<S, T>Abstract

export abstract class SupplierBase<S, T extends Product> implements ISupplier {
  /** The name of the supplier (used for display name, lists, etc). */
  public abstract readonly supplierName: string;

  /** The base URL for the supplier. */
  public abstract readonly baseURL: string;

  /** The minimum match percentage for a product to be considered a match. */
  protected readonly minMatchPercentage: number = 55;

  /**
   * Fuzz scorer used by `fuzzyFilter` to score each candidate's title against
   * the query. Any function from `fuzzball` with the
   * `(str1, str2, opts?) => number` shape works. Subclasses override this when
   * a supplier's title format needs a different scorer (e.g. a catalog that
   * pads titles with boilerplate might prefer `partial_ratio`). Defaults to
   * `ratio`.
   *
   * Overridable at runtime from `userSettings.fuzzScorerOverride` — see
   * `setFuzzScorerOverride` and `fuzzyFilter` below. The user's Advanced
   * settings selection wins over this subclass default when set.
   */
  protected readonly fuzzScorer: FuzzScorerFn = ratio;

  /**
   * Runtime override resolved from `userSettings.fuzzScorerOverride`. When
   * set, `fuzzyFilter` uses this instead of `this.fuzzScorer`. Undefined
   * (the default) means "use whatever the supplier class picked". Mutated
   * by `setFuzzScorerOverride` so it can't be `readonly`.
   */
  protected fuzzScorerOverride?: FuzzScorerFn;

  /**
   * The shipping scope of the supplier. Used to determine the shipping scope
   * of the supplier.
   */
  public abstract readonly shipping: ShippingRange;

  /**
   * The country code of the supplier. Used to determine the currency and other
   * country-specific information.
   */
  public abstract readonly country: CountryCode;

  /**
   * The payment methods accepted by the supplier. Used to determine the
   * payment methods accepted by the supplier.
   */
  public abstract readonly paymentMethods: PaymentMethod[];

  /**
   * Optional external API hostname used by some suppliers (e.g., Typesense,
   * Searchanise). When set, automatically included in `requiredHosts` for
   * permission checks.
   */
  protected readonly apiURL?: string;

  /**
   * All host origin patterns required for this supplier to function.
   * Automatically includes `baseURL` and, if defined, `apiURL`. Used by the
   * factory to check chrome permissions before querying.
   */
  public get requiredHosts(): string[] {
    const hosts = [`${this.baseURL}/*`];
    if (this.apiURL) {
      hosts.push(`https://${this.apiURL}/*`);
    }
    return hosts;
  }

  /**
   * String to query for (product name, CAS, etc.). The search term that will
   * be used to find products. Set during construction and used throughout the
   * supplier's lifecycle.
   */
  protected query: string;

  /**
   * If the products first require a query of a search page that gets iterated
   * over, those results are stored here. Acts as a cache for the initial
   * search results before they are processed into full product objects.
   */
  protected queryResults: S[] = [];

  /**
   * The base search parameters that are always included in search requests.
   * These parameters are merged with any additional search parameters
   * when making requests to the supplier's API.
   *
   * @example
   * ```typescript
   * class MySupplier extends SupplierBase<Product> {
   *   constructor() {
   *     super();
   *     this.baseSearchParams = {
   *       format: "json",
   *       version: "2.0"
   *     };
   *   }
   * }
   * ```
   * @source
   */
  protected baseSearchParams: Record<string, string | number> = {};

  /**
   * The AbortController instance used to manage and cancel ongoing requests.
   * This allows for cancellation of in-flight requests when needed,
   * such as when a new search is started or the supplier is disposed.
   *
   * @example
   * ```typescript
   * const controller = new AbortController();
   * const supplier = new MySupplier("acetone", 5, controller);
   *
   * // Later, to cancel all pending requests:
   * controller.abort();
   * ```
   * @source
   */
  protected controller: AbortController;

  /**
   * The maximum number of results to return for a search query.
   * This is not a limit on HTTP requests, but rather the number of
   * products that will be returned to the caller.
   *
   * @example
   * ```typescript
   * const supplier = new MySupplier("acetone", 5); // Limit to 5 results
   * for await (const product of supplier) {
   *   // Will yield at most 5 products
   * }
   * ```
   * @source
   */
  protected limit: number;

  /**
   * The products that are currently being built by the supplier.
   * This array holds ProductBuilder instances that are in the process
   * of being transformed into complete Product objects.
   *
   * @example
   * ```typescript
   * await supplier.queryProducts("acetone");
   * console.log(`Building ${supplier.products.length} products`);
   * for (const builder of supplier.products) {
   *   const product = await builder.build();
   *   console.log("Built product:", product.title);
   * }
   * ```
   * @source
   */
  protected products: ProductBuilder<T>[] = [];

  /**
   * Maximum number of HTTP requests allowed per search query.
   * This is a hard limit to prevent excessive requests to the supplier's API.
   * If this limit is reached, the supplier will stop making new requests.
   *
   * @defaultValue 50
   * @example
   * ```typescript
   * class MySupplier extends SupplierBase<Product> {
   *   constructor() {
   *     super();
   *     this.httpRequestHardLimit = 100; // Allow more requests
   *   }
   * }
   * ```
   * @source
   */
  protected httpRequestHardLimit: number = 50;

  /**
   * Counter for HTTP requests made during the current query execution.
   * This is used to track the number of requests and ensure we don't
   * exceed the httpRequestHardLimit.
   *
   * @defaultValue 0
   * @example
   * ```typescript
   * await supplier.queryProducts("acetone");
   * console.log(`Made ${supplier.requestCount} requests`);
   * if (supplier.requestCount >= supplier.httpRequestHardLimit) {
   *   console.log("Reached request limit");
   * }
   * ```
   * @source
   */
  protected requestCount: number = 0;

  /**
   * Number of requests to process in parallel when fetching product details.
   * This controls the batch size for concurrent requests to avoid overwhelming
   * the supplier's API and the user's bandwidth.
   *
   * @defaultValue 10
   * @example
   * ```typescript
   * class MySupplier extends SupplierBase<Product> {
   *   constructor() {
   *     super();
   *     // Process 5 requests at a time
   *     this.maxConcurrentRequests = 5;
   *   }
   * }
   * ```
   * @source
   */
  protected maxConcurrentRequests: number = 3;

  /**
   * Minimum number of milliseconds between two consecutive tasks
   * @source
   */
  protected minConcurrentCycle: number = 100;

  /**
   * HTTP headers used as a basis for all requests to the supplier.
   * These headers are merged with any request-specific headers when
   * making HTTP requests.
   *
   * @example
   * ```typescript
   * class MySupplier extends SupplierBase<Product> {
   *   constructor() {
   *     super();
   *     this.headers = {
   *       "Accept": "application/json",
   *       "User-Agent": "ChemPal/1.0"
   *     };
   *   }
   * }
   * ```
   * @source
   */
  protected headers: HeadersInit = {};

  /**
   * Cookies that must be written into the browser jar before any request runs
   * — e.g. a currency or session-preference cookie the backend reads. Seeded
   * once per instance by `ensureSetup` (before `setup`) via `chrome.cookies`,
   * since the `Cookie` request header is on the fetch-forbidden list and can't
   * be set through `this.headers`. Each entry's `url` defaults to `baseURL`.
   * Subclasses override this instead of hand-rolling a `setup` that calls
   * `chrome.cookies.set` directly.
   * @defaultValue []
   * @example
   * ```typescript
   * class MySupplier extends SupplierBase<Partial<Product>, Product> {
   *   protected readonly requiredCookies: SupplierCookieSeed[] = [
   *     { name: "currency", value: "2" },
   *   ];
   * }
   * ```
   * @source
   */
  protected readonly requiredCookies: SupplierCookieSeed[] = [];

  /**
   * Number of times `fetch` retries a request that comes back `403`. Some
   * suppliers sit behind a WAF that 403s the first hit while planting a
   * session cookie (a "cookie handshake"); because every request now sets
   * `credentials: "include"`, that cookie lands in the jar and the retry
   * carries it back, usually passing. We can't gate on the `Set-Cookie`
   * header (it's fetch-forbidden and invisible to JS), so this per-supplier
   * flag is the gate — `0` (the default) means never retry. Only enable it
   * for suppliers known to do this handshake.
   * @defaultValue 0
   * @source
   */
  protected readonly challengeRetryLimit: number = 0;

  /**
   * Delay in milliseconds between `403` challenge retries. Gives the WAF a
   * brief beat before re-requesting with the freshly-planted cookie.
   * @defaultValue 300
   * @source
   */
  protected readonly challengeRetryDelayMs: number = 300;

  /**
   * Logger for the supplier. Initialized in the constructor with the name of
   * the inheriting class.
   */
  protected logger: Logger;

  /**
   * Default values for products. These will get overridden if they're found in
   * the product data.
   */
  protected productDefaults: ProductDefaults = {
    uom: UOM.EA,
    quantity: 1,
    currencyCode: "USD",
    currencySymbol: "$",
  };

  /**
   * Cache instance for this supplier.
   *
   * Initialized after construction by `initCache()` (called from
   * `SupplierFactory` once `supplierName` is set). The `!` assertion is safe
   * here because every code path that reads `this.cache`
   * (`queryProductsWithCache`, `getProductData`, `getProductDataWithCache`)
   * runs only after `execute()` is called on a factory-built instance, and the
   * factory always calls `initCache()` before handing the instance out.
   */
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
  protected cache!: SupplierCache;

  /**
   * Product-data cache keys the user has explicitly excluded via the "Ignore
   * Product" context menu action. Loaded once per `execute()` from
   * `storage.local` so membership checks are synchronous on the hot path
   * (see `getProductData`). Newly-ignored products take effect on the next
   * search, which matches the stated feature requirement.
   */
  protected excludedProductKeys: Set<string> = new Set();

  /**
   * Memoizes `setup()` so it runs at most once per supplier instance, lazily,
   * only when the search is about to do real work. The gate lives at the
   * phase boundaries in `queryProductsWithCache` (before `queryProducts`)
   * and `getProductData` / `getProductDataWithCache` (before the fetcher),
   * so setup runs strictly before any code that reads its mutated state
   * (`this.headers`, `this.localStorage`, etc.) — including subclasses whose
   * request path reads `localStorage` synchronously. If every query and
   * product lookup is a cache hit, the promise stays null and setup is never
   * invoked.
   *
   * @defaultValue null
   * @example
   * ```typescript
   * // First cache miss sets the promise; subsequent awaits share it.
   * await this.ensureSetup();
   * console.log(this.setupPromise); // Promise<void> (resolved)
   * ```
   * @source
   */
  private setupPromise: Promise<void> | null = null;

  /**
   * Creates a new instance of the supplier base class.
   * Initializes the supplier with query parameters, request limits, and abort controller.
   * Sets up logging and default product values.
   *
   * @param query - The search term to query products for
   * @param limit - The maximum number of results to return (default: 5)
   * @param controller - AbortController instance for managing request cancellation
   *
   * @example
   * ```typescript
   * // Create a supplier with default limit
   * const supplier = new MySupplier("sodium chloride", undefined, new AbortController());
   *
   * // Create a supplier with custom limit
   * const supplier = new MySupplier("acetone", 10, new AbortController());
   *
   * // Create a supplier and handle cancellation
   * const controller = new AbortController();
   * const supplier = new MySupplier("ethanol", 5, controller);
   *
   * // Later, to cancel all pending requests:
   * controller.abort();
   * ```
   * @source
   */
  public constructor(
    query: string,
    limit: number = defaultResultsLimit,
    controller?: AbortController,
  ) {
    // Initialize required properties
    this.query = query;
    this.limit = limit;
    this.controller = controller ?? new AbortController();
    this.logger = new Logger(this.constructor.name);
  }

  /**
   * Initializes the cache for the supplier.
   * This is called after construction to ensure supplierName is set.
   *
   * @remarks
   * The cache is initialized with the supplier's name and is used to store
   * both query results and product data. This method should be called after
   * the supplier's name is set to ensure proper cache key generation.
   *
   * @example
   * ```typescript
   * class MySupplier extends SupplierBase<Product> {
   *   constructor() {
   *     super("acetone", 5);
   *     // supplierName is set here
   *     this.initCache(); // Initialize cache after supplierName is set
   *   }
   * }
   * ```
   * @source
   */
  public initCache(
    enabled: boolean = true,
    doNotCacheEmptyResults: boolean = false,
    cacheTtlMinutes: number = 0,
  ): void {
    this.cache = new SupplierCache(
      this.supplierName,
      this.constructor.name,
      enabled,
      doNotCacheEmptyResults,
      cacheTtlMinutes,
    );
  }

  /**
   * Applies (or clears) a runtime override for the fuzz scorer. Driven by
   * `userSettings.fuzzScorerOverride` — when the user picks a scorer in the
   * Advanced drawer section, `SupplierFactory` calls this on each instance
   * so the choice takes effect uniformly across every supplier.
   *
   * Silently ignores unknown names so an outdated / corrupted setting can't
   * blow up the search flow — callers fall back to the subclass default.
   * @param name - Name of a scorer from `FUZZ_SCORERS`, or `undefined` to
   *   clear the override and use the subclass default.
   * @example
   * ```ts
   * const supplier = new MySupplier("acetone", 5, controller);
   * supplier.setFuzzScorerOverride("token_set_ratio");
   * // fuzzyFilter now uses token_set_ratio regardless of MySupplier's default
   * supplier.setFuzzScorerOverride(undefined);
   * // back to MySupplier's default
   * ```
   * @source
   */
  public setFuzzScorerOverride(name: string | undefined): void {
    if (isFuzzScorerName(name)) {
      this.fuzzScorerOverride = FUZZ_SCORERS[name];
    } else {
      this.fuzzScorerOverride = undefined;
    }
  }

  /**
   * Placeholder for any setup that needs to be done before the query is made.
   * Override this in subclasses if you need to perform setup (e.g., authentication, token fetching).
   *
   * @returns A promise that resolves when the setup is complete.
   *
   * @example
   * ```typescript
   * await supplier.setup();
   * ```
   * @source
   */
  protected async setup(): Promise<void> {}

  /**
   * Lazy, single-shot wrapper around `setup()`. Invoked at the phase
   * boundaries in `queryProductsWithCache` and `getProductData` /
   * `getProductDataWithCache`, so setup runs only when the search is about
   * to do real work — a fully cached search never triggers setup at all.
   * Concurrency-safe: parallel callers share the same promise and all await
   * its real resolution, so no worker can race past setup. Because the gate
   * lives above `fetch()`, `setup()` itself can freely call `this.httpGet`
   * / `this.httpPost` — there is no re-entry to defend against. If
   * `setup()` throws, the rejected promise is memoized — callers won't
   * silently retry a broken supplier.
   *
   * @returns A promise that resolves once `setup()` has completed.
   *
   * @example
   * ```typescript
   * // Called internally before any code path that reads setup-mutated state:
   * await this.ensureSetup();
   * const response = await this.queryProducts(query, limit);
   * ```
   * @source
   */
  private async ensureSetup(): Promise<void> {
    if (!this.setupPromise) {
      this.setupPromise = (async () => {
        await this.seedRequiredCookies();
        await this.setup();
      })();
    }
    return this.setupPromise;
  }

  /**
   * Writes every entry in `requiredCookies` into the browser jar before
   * `setup` runs. Each cookie's `url` defaults to `baseURL`. Failures are
   * swallowed and logged by `setCookie`, so a missing cookie permission never
   * aborts the query — affected prices/preferences just fall back to the
   * session default.
   * @returns A promise that resolves once all cookies have been seeded.
   * @source
   */
  private async seedRequiredCookies(): Promise<void> {
    for (const cookie of this.requiredCookies) {
      await setCookie({ url: this.baseURL, ...cookie });
    }
  }

  /**
   * Retrieves HTTP headers from a URL using a HEAD request.
   * Useful for checking content types, caching headers, and other metadata without downloading the full response.
   *
   * @param url - The URL to fetch headers from
   * @returns Promise resolving to the response headers or void if request fails
   *
   * @example
   * ```typescript
   * // Basic usage
   * const headers = await supplier.httpGetHeaders('https://example.com/product/123');
   * if (headers) {
   *   console.log('Content-Type:', headers['content-type']);
   * }
   * ```
   *
   * @example
   * ```typescript
   * // With error handling
   * try {
   *   const headers = await supplier.httpGetHeaders('https://example.com/product/123');
   *   if (headers) {
   *     console.log('Headers:', headers);
   *   }
   * } catch (err) {
   *   console.error('Failed to fetch headers:', err);
   * }
   * ```
   * @source
   */
  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;
    }
  }

  /**
   * Sends a POST request to the given URL with the given body and headers.
   * Handles request setup, error handling, and response caching.
   *
   * @param options - The request configuration options
   * @returns Promise resolving to the Response object or void if request fails
   *
   * @example
   * ```typescript
   * // Basic POST request
   * const response = await supplier.httpPost({
   *   path: '/api/v1/products',
   *   body: { name: 'Test Chemical' }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // POST with custom headers
   * const response = await supplier.httpPost({
   *   path: '/api/v1/products',
   *   body: { name: 'Test Chemical' },
   *   headers: {
   *     'Authorization': 'Bearer token123',
   *     'Content-Type': 'application/json'
   *   }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // POST with custom host and params
   * const response = await supplier.httpPost({
   *   path: '/api/v1/products',
   *   host: 'api.example.com',
   *   body: { name: 'Test Chemical' },
   *   params: { version: '2' }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // Error handling
   * try {
   *   const response = await supplier.httpPost({ path: '/api/v1/products', body: { name: 'Test' } });
   *   if (response && response.ok) {
   *     const data = await response.json();
   *     console.log('Created:', data);
   *   }
   * } catch (err) {
   *   console.error('POST failed:', err);
   * }
   * ```
   * @source
   */
  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;
  }

  /**
   * Sends a POST request and returns the response as a JSON object.
   *
   * @param params - The parameters for the POST request.
   * @returns The response from the POST request as a JSON object.
   *
   * @example
   * ```typescript
   * // Basic usage
   * const data = await supplier.httpPostJson({
   *   path: '/api/v1/products',
   *   body: { name: 'John' }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // With custom headers and error handling
   * try {
   *   const data = await supplier.httpPostJson({
   *     path: '/api/v1/products',
   *     body: { name: 'John' },
   *     headers: { 'Authorization': 'Bearer token123' }
   *   });
   *   if (data) {
   *     console.log('Created:', data);
   *   }
   * } catch (err) {
   *   console.error('POST JSON failed:', err);
   * }
   * ```
   * @source
   */
  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();
  }

  /**
   * Sends a POST request and returns the response as a HTML string.
   *
   * @param options - The request configuration options
   * @returns Promise resolving to the HTML response as a string or void if request fails
   * @throws TypeError - If the response is not valid HTML content
   *
   * @example
   * ```typescript
   * // Basic usage
   * const html = await supplier.httpPostHtml({
   *   path: '/api/v1/products',
   *   body: { name: 'John' }
   * });
   * ```
   * @source
   */
  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();
  }

  /**
   * Sends a GET request to the given URL with the specified options.
   * Handles request setup, error handling, and response caching.
   *
   * @param options - The request configuration options
   * @returns Promise resolving to the Response object or void if request fails
   *
   * @example
   * ```typescript
   * // Basic GET request
   * const response = await supplier.httpGet({
   *   path: '/products/search',
   *   params: { query: 'sodium chloride' }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // GET with custom headers
   * const response = await supplier.httpGet({
   *   path: '/products/search',
   *   headers: { 'Accept': 'application/json' }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // GET with custom host
   * const response = await supplier.httpGet({
   *   path: '/products/search',
   *   host: 'api.example.com',
   *   params: { category: 'chemicals' }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // Error handling
   * try {
   *   const response = await supplier.httpGet({ path: '/products/search' });
   *   if (response && response.ok) {
   *     const data = await response.json();
   *     console.log('Products:', data);
   *   }
   * } catch (err) {
   *   console.error('GET failed:', err);
   * }
   * ```
   * @source
   */
  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;
    }
  }

  /**
   * Evaluation logging: run every candidate scorer against the same
   * query/title pair so we can compare which fuzz filter ranks this
   * supplier's results best. Emitted as one console.table per call so the
   * rows are side-by-side readable in devtools. Remove once we've picked
   * a scorer.
   * @param query - The query to compare the data against
   * @param data - The data to compare the query against
   * @returns void
   * @source
   * ```typescript
   * // Example usage
   * this.showFuzzScorerComparisonTable("sodium chloride", products);
   * ```
   */
  private showFuzzScorerComparisonTable<X>(query: string, data: X[]): void {
    const scorerComparison = data.map((obj, idx) => {
      const title = String(this.titleSelector(obj) ?? "");
      return {
        idx,
        title,
        distance: distance(query, title),
        ratio: ratio(query, title),
        partial_ratio: partial_ratio(query, title),
        token_sort_ratio: token_sort_ratio(query, title),
        token_set_ratio: token_set_ratio(query, title),
        token_similarity_sort_ratio: token_similarity_sort_ratio(query, title),
        partial_token_sort_ratio: partial_token_sort_ratio(query, title),
        partial_token_set_ratio: partial_token_set_ratio(query, title),
        partial_token_similarity_sort_ratio: partial_token_similarity_sort_ratio(query, title),
        WRatio: WRatio(query, title),
      };
    });

    console.table(scorerComparison);
  }

  /**
   * Filters an array of data using fuzzy string matching to find items that closely match a query string.
   * Uses the WRatio algorithm from fuzzball for string similarity comparison.
   *
   * @param query - The search string to match against
   * @param data - Array of data objects to search through
   * @param minMatchPercentage - Minimum match percentage (0-100) for a match to be included (default: 55)
   * @returns Array of matching data objects with added fuzzy match metadata
   *
   * @example
   * ```typescript
   * // Example with simple string array
   * const products = [
   *   { title: "Sodium Chloride", price: 29.99 },
   *   { title: "Sodium Hydroxide", price: 39.99 },
   *   { title: "Potassium Chloride", price: 19.99 }
   * ];
   *
   * const matches = this.fuzzyFilter("sodium chloride", products);
   * // Returns: [
   * //   {
   * //     title: "Sodium Chloride",
   * //     price: 29.99,
   * //     _fuzz: { score: 100, idx: 0 }
   * //   },
   * //   {
   * //     title: "Sodium Hydroxide",
   * //     price: 39.99,
   * //     _fuzz: { score: 85, idx: 1 }
   * //   }
   * // ]
   *
   * // Example with custom minMatchPercentage
   * const strictMatches = this.fuzzyFilter("sodium chloride", products, 90);
   * // Returns only exact matches with score >= 90
   *
   * // Example with different data structure
   * const chemicals = [
   *   { name: "NaCl", formula: "Sodium Chloride" },
   *   { name: "NaOH", formula: "Sodium Hydroxide" }
   * ];
   *
   * // Override titleSelector to use formula field
   * this.titleSelector = (data) => data.formula;
   * const formulaMatches = this.fuzzyFilter("sodium chloride", chemicals);
   * ```
   * @source
   */
  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);
  }

  /**
   * Abstract method to select the title from the initial raw search data.
   * This method should be implemented by each supplier to handle their specific
   * data structure.
   *
   * The parameter is typed as `unknown` because callers (`fuzzyFilter`,
   * `groupVariants`, `showFuzzScorerComparisonTable`) accept arbitrary `X[]`
   * arrays — subclasses narrow with a type guard or cast (with a comment
   * explaining why the cast is safe) to their parsed search-result type.
   *
   * @param data - The raw data object to extract the title from
   * @returns The title string to use for fuzzy matching, or undefined
   * @abstract
   * @example
   * ```typescript
   * // Subclass narrows via cast (commented why safe):
   * protected titleSelector(data: unknown): Maybe<string> {
   *   // Safe: queryProducts only stores Cheerio<Element> into queryResults.
   *   return (data as Cheerio<Element>).text();
   * }
   * ```
   * @source
   */
  protected abstract titleSelector(data: unknown): Maybe<string>;

  /**
   * Makes an HTTP GET request and returns the response as a string.
   * Handles request configuration, error handling, and HTML parsing.
   *
   * @param options - The request configuration options
   * @returns Promise resolving to the HTML response as a string or void if request fails
   * @throws TypeError - If the response is not valid HTML content
   *
   * @example
   * ```typescript
   * // Basic GET request
   * const html = await this.httpGetHtml({
   *   path: "/api/products",
   *   params: { search: "sodium" }
   * });
   *
   * // GET request with custom headers
   * const html = await this.httpGetHtml({
   *   path: "/api/products",
   *   headers: {
   *     "Authorization": "Bearer token123",
   *     "Accept": "text/html"
   *   }
   * });
   *
   * // GET request with custom host
   * const html = await this.httpGetHtml({
   *   path: "/products",
   *   host: "api.supplier.com",
   *   params: { limit: 10 }
   * });
   * ```
   * @source
   */
  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();
  }

  /**
   * Makes an HTTP GET request and returns the response as parsed JSON.
   * Handles request configuration, error handling, and JSON parsing.
   *
   * @param options - The request configuration options
   * @returns Promise resolving to the parsed JSON response or void if request fails
   * @throws TypeError - If the response is not valid JSON content
   *
   * @example
   * ```typescript
   * // Basic GET request
   * const data = await supplier.httpGetJson({ path: '/api/products', params: { search: 'sodium' } });
   * ```
   *
   * @example
   * ```typescript
   * // GET request with custom headers
   * const data = await supplier.httpGetJson({
   *   path: '/api/products',
   *   headers: {
   *     'Authorization': 'Bearer token123',
   *     'Accept': 'application/json'
   *   }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // GET request with custom host
   * const data = await supplier.httpGetJson({
   *   path: '/products',
   *   host: 'api.supplier.com',
   *   params: { limit: 10 }
   * });
   * ```
   *
   * @example
   * ```typescript
   * // Error handling
   * try {
   *   const data = await supplier.httpGetJson({ path: '/api/products' });
   *   if (data) {
   *     console.log('Products:', data);
   *   }
   * } catch (error) {
   *   console.error('Failed to fetch products:', error);
   * }
   * ```
   * @source
   */
  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();
  }

  /**
   * Executes a product search query with caching support.
   * First checks the cache for existing results, then falls back to the actual query if needed.
   * The limit parameter is only used for the actual query and doesn't affect caching.
   *
   * @param query - The search term to query products for
   * @param limit - The maximum number of results to return (defaults to instance limit)
   * @returns Promise resolving to array of product builders or void if search fails
   *
   * @example
   * ```typescript
   * // Basic usage with default limit
   * const results = await supplier.queryProductsWithCache("acetone");
   * if (results) {
   *   console.log(`Found ${results.length} products`);
   * }
   * ```
   *
   * @example
   * ```typescript
   * // With custom limit
   * const results = await supplier.queryProductsWithCache("acetone", 10);
   * if (results) {
   *   for (const builder of results) {
   *     const product = await builder.build();
   *     console.log(product.title, product.price);
   *   }
   * }
   * ```
   * @source
   */
  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;
  }

  /**
   * Executes the supplier's search query and returns the results.
   * This method will execute all results concurrently (to the limits set in the supplier
   * class), and resolve to an array of product objects.
   *
   * @remarks
   * This method is used to execute the supplier's search query and return the results.
   * @returns Promise resolving to an array of products
   * @source
   */
  public async *execute(): AsyncGenerator<T, void, undefined> {
    // setup() is not called eagerly here — it's run lazily from the
    // phase-boundary gates inside `queryProductsWithCache` and
    // `getProductData` / `getProductDataWithCache`. A fully cached search
    // never reaches those gates, so setup's token/cookie/permission
    // requests are skipped entirely.
    // Snapshot the user's ignore list once per search. Any product whose
    // exclusion key matches an entry here is dropped before the detail phase
    // runs (see the filter after queryProductsWithCache below).
    this.excludedProductKeys = await loadExcludedProductKeys();
    // Over-fetch by the number of previously-ignored products belonging to
    // this supplier so that, in the worst case where every ignored product
    // appears in the top of the query result set, we still end up with
    // `this.limit` survivors after filtering. The queryProductsWithCache
    // cache invalidates itself when the requested limit exceeds the cached
    // limit, so this is safe.
    const excludedForSupplier = await countExcludedProductsForSupplier(this.supplierName);
    const fetchLimit = this.limit + excludedForSupplier;
    incrementSearchQueryCount(this.supplierName);
    const results = await this.queryProductsWithCache(this.query, fetchLimit);
    if (!results || results.length === 0) {
      this.logger.log(`No query results found`);
      return;
    }
    // Drop any products the user has ignored, then slice back down to the
    // user-visible limit. Uses the same key shape as getProductData so
    // whichever side catches the exclusion first, the check is consistent.
    const survivors: ProductBuilder<T>[] = [];
    for (const builder of results) {
      if (survivors.length >= this.limit) break;
      const rawUrl = builder.get("url");
      if (typeof rawUrl !== "string") {
        survivors.push(builder);
        continue;
      }
      const exclusionUrl = this.href(rawUrl);
      const exclusionKey = getProductExclusionKey(exclusionUrl, this.supplierName);
      if (this.excludedProductKeys.has(exclusionKey)) {
        this.logger.debug("Skipping excluded product (pre-detail)", {
          url: rawUrl,
          exclusionUrl,
          exclusionKey,
        });
        continue;
      }
      survivors.push(builder);
    }
    this.products = survivors;
    const queue = new Queue(this.maxConcurrentRequests, this.minConcurrentCycle);

    // Create an array of promises, each yielding a product as soon as it's ready
    const tasks = this.products.map((product) =>
      queue.run(async () => {
        try {
          this.logger.debug(`Product data for ${this.supplierName}:`, product);
          const builder = await this.getProductData(product);
          if (!builder) return;

          this.logger.debug(`Builder data for ${this.supplierName}:`, builder);
          const finished = await this.finishProduct(builder);
          this.logger.debug(`Finished product data for ${this.supplierName}:`, finished);
          if (finished) {
            return finished;
          }
        } catch (e: unknown) {
          this.logger.error("Error processing product", { error: e, product });
          incrementParseError(this.supplierName);
        }
      }),
    );

    // As each promise resolves, yield the product
    const resultsSet = new Set(tasks);
    while (resultsSet.size > 0) {
      const finished = await Promise.race(resultsSet);
      // Remove the finished promise from the set
      for (const t of resultsSet) {
        if ((await Promise.resolve(t)) === finished) {
          resultsSet.delete(t);
          break;
        }
      }
      if (finished) {
        yield finished;
      }
    }
  }

  /**
   * Abstract method that must be implemented by supplier classes to perform the actual product search.
   * This is the core method that each supplier implements to query their specific API or website.
   *
   * @remarks
   * The implementation should:
   * 1. Make the necessary HTTP requests to the supplier's API/website
   * 2. Parse the response into initial product data
   * 3. Create ProductBuilder instances for each result
   * 4. Set basic product information (title, URL, etc.)
   *
   * The method should not fetch detailed product data - that is handled by getProductData.
   *
   * @todo Whats the difference between this and the finish method? Forgot why I created the other.
   *
   * @param query - The search term to query products for
   * @param limit - The maximum number of results to return
   * @returns Promise resolving to array of ProductBuilder instances or void if search fails
   *
   * @example
   * ```typescript
   * // Example implementation for a JSON API supplier
   * protected async queryProducts(
   *   query: string,
   *   limit: number
   * ): Promise<ProductBuilder<Product>[] | void> {
   *   const response = await this.httpGetJson({
   *     path: '/api/search',
   *     params: {
   *       q: query,
   *       limit,
   *       format: 'json'
   *     }
   *   });
   *
   *   if (!response?.items) return;
   *
   *   return response.items.map(item => {
   *     const builder = new ProductBuilder<Product>(this.baseURL);
   *     builder
   *       .setBasicInfo(item.title, item.url, this.supplierName)
   *       .setPricing(item.price, item.currency)
   *       .setQuantity(item.quantity, item.uom);
   *     return builder;
   *   });
   * }
   * ```
   *
   * @example
   * ```typescript
   * // Example implementation for an HTML scraping supplier
   * protected async queryProducts(
   *   query: string,
   *   limit: number
   * ): Promise<ProductBuilder<Product>[] | void> {
   *   const html = await this.httpGetHtml({
   *     path: '/search',
   *     params: { q: query }
   *   });
   *
   *   if (!html) return;
   *
   *   const $ = cheerio.load(html);
   *   const products: ProductBuilder<Product>[] = [];
   *
   *   $('.product-item').each((_, el) => {
   *     if (products.length >= limit) return false;
   *
   *     const $el = $(el);
   *     const builder = new ProductBuilder<Product>(this.baseURL);
   *     builder
   *       .setBasicInfo(
   *         $el.find('.title').text(),
   *         $el.find('a').attr('href'),
   *         this.supplierName
   *       )
   *       .setPricing(
   *         $el.find('.price').text()
   *       );
   *     products.push(builder);
   *   });
   *
   *   return products;
   * }
   * ```
   * @source
   */
  protected abstract queryProducts(
    query: string,
    limit: number,
  ): Promise<ProductBuilder<T>[] | void>;

  /**
   * Finalizes a partial product by adding computed properties and validating the result.
   * This method:
   * 1. Validates the product has minimal required properties
   * 2. Computes USD price if product is in different currency
   * 3. Calculates base quantity using the unit of measure
   * 4. Ensures the product URL is absolute
   *
   * @param product - The ProductBuilder instance containing the partial product to finalize
   * @returns Promise resolving to a complete Product object or void if validation fails
   *
   * @example
   * ```typescript
   * // Example with a valid partial product
   * const builder = new ProductBuilder<Product>(this.baseURL);
   * builder
   *   .setBasicInfo("Sodium Chloride", "/products/nacl", "ChemSupplier")
   *   .setPricing(29.99, "USD", "$")
   *   .setQuantity(500, "g");
   *
   * const finishedProduct = await this.finishProduct(builder);
   * if (finishedProduct) {
   *   console.log("Finalized product:", {
   *     title: finishedProduct.title,
   *     price: finishedProduct.price,
   *     quantity: finishedProduct.quantity,
   *     uom: finishedProduct.uom,
   *     usdPrice: finishedProduct.usdPrice,
   *     baseQuantity: finishedProduct.baseQuantity
   *   });
   * }
   *
   * // Example with an invalid partial product
   * const invalidBuilder = new ProductBuilder<Product>(this.baseURL);
   * invalidBuilder.setBasicInfo("Sodium Chloride", "/products/nacl", "ChemSupplier");
   * // Missing required fields
   *
   * const invalidProduct = await this.finishProduct(invalidBuilder);
   * if (!invalidProduct) {
   *   console.log("Failed to finalize product - missing required fields");
   * }
   * ```
   * @source
   */
  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;
  }

  /**
   * Takes in either a relative or absolute URL and returns an absolute URL. This is useful for when you aren't
   * sure if the link (retrieved from parsed text, a setting, an element, an anchor value, etc) is absolute or
   * not. Using relative links will result in http://chrome-extension://... being added to the link.
   *
   * @param path - URL object or string
   * @param params - The parameters to add to the URL.
   * @param host - The host to use for overrides (eg: needing to call a different host for an API)
   * @returns absolute URL
   * @example
   * ```typescript
   * this.href('/some/path')
   * // https://supplier_base_url.com/some/path
   *
   * this.href('https://supplier_base_url.com/some/path', null, 'another_host.com')
   * // https://another_host.com/some/path
   *
   * this.href('/some/path', { a: 'b', c: 'd' }, 'another_host.com')
   * // http://another_host.com/some/path?a=b&c=d
   *
   * this.href('https://supplier_base_url.com/some/path')
   * // https://supplier_base_url.com/some/path
   *
   * this.href(new URL('https://supplier_base_url.com/some/path'))
   * // https://supplier_base_url.com/some/path
   *
   * this.href('/some/path', { a: 'b', c: 'd' })
   * // https://supplier_base_url.com/some/path?a=b&c=d
   *
   * this.href('https://supplier_base_url.com/some/path', new URLSearchParams({ a: 'b', c: 'd' }))
   * // https://supplier_base_url.com/some/path?a=b&c=d
   * ```
   * @source
   */
  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();
  }

  /**
   * Retrieves detailed product data for a given product builder.
   * Handles caching of product data and fetches fresh data if not cached.
   *
   * @param product - The ProductBuilder instance to get data for
   * @returns Promise resolving to the updated ProductBuilder or void if fetch fails
   *
   * @example
   * ```typescript
   * const builder = new ProductBuilder<Product>(this.baseURL);
   * builder.setBasicInfo("Acetone", "/products/acetone", "ChemSupplier");
   *
   * const updatedBuilder = await supplier.getProductData(builder);
   * if (updatedBuilder) {
   *   const product = await updatedBuilder.build();
   *   console.log("Product details:", product);
   * }
   * ```
   * @source
   */
  protected async getProductData(product: ProductBuilder<T>): Promise<ProductBuilder<T> | void> {
    const url = product.get("url");
    if (typeof url !== "string") {
      this.logger.error("Invalid URL in product:", { url });
      return undefined;
    }
    // Normalize the URL the same way ProductBuilder.build() does (line 975
    // calls `this.href(this.product.url)`) *only* for the exclusion check,
    // so the md5 matches the absolute URL that the UI's context menu passed
    // to addExcludedProduct. Suppliers often stage relative paths here
    // (e.g. "/products/acetone") which would otherwise hash differently than
    // the absolute URL stored on the built Product.
    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);
    this.logger.debug("[SupplierBase] Product detail cache key:", cacheKey, "for url:", url);
    // Skip products the user has explicitly excluded via the "Ignore Product"
    // context menu. The exclusion key mirrors getProductDataCacheKey's no-params
    // shape, so this check catches ignored entries regardless of supplier.
    if (this.excludedProductKeys.has(cacheKey)) {
      this.logger.debug("Skipping excluded product", { url, cacheKey });
      return undefined;
    }
    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 this.getProductDataWithCache(product, this.getProductData, {});
      } catch (err: unknown) {
        this.logger.error("Error in product detail fetcher:", err);
        incrementParseError(this.supplierName);
        return undefined;
      }
      if (resultBuilder) {
        await this.cache.cacheProductData(cacheKey, resultBuilder.dump());
      }
      return resultBuilder;
    } catch (outerErr: unknown) {
      this.logger.error("Error in getProductDataWithCache:", outerErr);
      incrementParseError(this.supplierName);
      return undefined;
    }
  }

  /**
   * Retrieves product data with caching support.
   * Similar to getProductData but allows for additional parameters to be included in the cache key.
   *
   * @param product - The ProductBuilder instance to get data for
   * @param fetcher - The function to use for fetching product data
   * @param params - Optional parameters to include in the cache key
   * @returns Promise resolving to the updated ProductBuilder or void if fetch fails
   *
   * @example
   * ```typescript
   * const builder = new ProductBuilder<Product>(this.baseURL);
   * builder.setBasicInfo("Acetone", "/products/acetone", "ChemSupplier");
   *
   * // Use custom fetcher with additional params
   * const updatedBuilder = await supplier.getProductDataWithCache(
   *   builder,
   *   async (b) => {
   *     // Custom fetching logic
   *     return b;
   *   },
   *   { version: "2.0" }
   * );
   * ```
   * @source
   */
  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;
    }
  }

  /**
   * Groups variants of a product by their title
   * @param data - Array of product listings from search results
   * @returns Array of product listings with grouped variants
   * @todo Create a generic method for this, the same method is used in
   *       Synthetika and could be of use with LoudWolf.
   * @example
   * ```typescript
   * const results = await this.queryProducts("sodium chloride");
   * const grouped = this.groupVariants(results);
   * // grouped is an array of product listings with grouped variants
   * ```
   * @source
   */
  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);
  }

  /**
   * Internal fetch method with request counting and decorator.
   * Tracks request count and enforces hard limits on HTTP requests.
   *
   * @param args - Arguments to pass to fetchDecorator (usually a Request or URL and options)
   * @returns The response from the fetchDecorator
   * @throws Error if request count exceeds hard limit
   *
   * @example
   * ```typescript
   * // Example usage inside a subclass:
   * const response = await this.fetch(new Request('https://example.com'));
   * if (response.ok) {
   *   const data = await response.json();
   *   console.log(data);
   * }
   * ```
   *
   * @example
   * ```typescript
   * // With custom request options
   * const response = await this.fetch(
   *   new Request('https://example.com', {
   *     headers: { 'Accept': 'application/json' }
   *   })
   * );
   * ```
   * @source
   */
  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");
  }

  /**
   * Whether a thrown fetch error is a retryable WAF cookie-handshake `403`.
   * Gated by `challengeRetryLimit` so only opted-in suppliers retry; we can't
   * inspect the `Set-Cookie` header (fetch-forbidden), so any `403` qualifies
   * once a supplier has opted in.
   * @param error - The error thrown by `fetchDecorator`
   * @returns `true` when the request should be retried
   * @source
   */
  private shouldRetryChallenge(error: unknown): boolean {
    return this.challengeRetryLimit > 0 && error instanceof HttpError && error.status === 403;
  }
}
Copy