Class SupplierAmbeed

Protectedsetup

• setup(): Promise<void>

  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 Promise<void>

  A promise that resolves when the setup is complete.

  Example

  await supplier.setup();
  Copy

ProtectedhttpGetHeaders

• httpGetHeaders(url: string | URL): Promise<Maybe<HeadersInit>>

  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.

  Parameters

  • url: string | URL

    The URL to fetch headers from

  Returns Promise<Maybe<HeadersInit>>

  Promise resolving to the response headers or void if request fails

  Example

  // Basic usage
  const headers = await supplier.httpGetHeaders('https://example.com/product/123');
  if (headers) {
    console.log('Content-Type:', headers['content-type']);
  }
  Copy

  Example

  // 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);
  }
  Copy

ProtectedhttpPost

• httpPost(options: RequestOptions): Promise<Maybe<Response>>

  Sends a POST request to the given URL with the given body and headers. Handles request setup, error handling, and response caching.

  Parameters

  • options: RequestOptions

    The request configuration options

  Returns Promise<Maybe<Response>>

  Promise resolving to the Response object or void if request fails

  Example

  // Basic POST request
  const response = await supplier.httpPost({
    path: '/api/v1/products',
    body: { name: 'Test Chemical' }
  });
  Copy

  Example

  // 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'
    }
  });
  Copy

  Example

  // 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' }
  });
  Copy

  Example

  // 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);
  }
  Copy

ProtectedhttpPostJson

• httpPostJson(params: RequestOptions): Promise<Maybe<JsonValue>>

  Sends a POST request and returns the response as a JSON object.

  Parameters

  • params: RequestOptions

    The parameters for the POST request.

  Returns Promise<Maybe<JsonValue>>

  The response from the POST request as a JSON object.

  Example

  // Basic usage
  const data = await supplier.httpPostJson({
    path: '/api/v1/products',
    body: { name: 'John' }
  });
  Copy

  Example

  // 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);
  }
  Copy

ProtectedhttpPostHtml

• httpPostHtml(options: RequestOptions): Promise<Maybe<string>>

  Sends a POST request and returns the response as a HTML string.

  Parameters

  • options: RequestOptions

    The request configuration options

  Returns Promise<Maybe<string>>

  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

  // Basic usage
  const html = await supplier.httpPostHtml({
    path: '/api/v1/products',
    body: { name: 'John' }
  });
  Copy

ProtectedhttpGet

• httpGet(options: RequestOptions): Promise<Maybe<Response>>

  Sends a GET request to the given URL with the specified options. Handles request setup, error handling, and response caching.

  Parameters

  • options: RequestOptions

    The request configuration options

  Returns Promise<Maybe<Response>>

  Promise resolving to the Response object or void if request fails

  Example

  // Basic GET request
  const response = await supplier.httpGet({
    path: '/products/search',
    params: { query: 'sodium chloride' }
  });
  Copy

  Example

  // GET with custom headers
  const response = await supplier.httpGet({
    path: '/products/search',
    headers: { 'Accept': 'application/json' }
  });
  Copy

  Example

  // GET with custom host
  const response = await supplier.httpGet({
    path: '/products/search',
    host: 'api.example.com',
    params: { category: 'chemicals' }
  });
  Copy

  Example

  // 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);
  }
  Copy

ProtectedfuzzyFilter

• fuzzyFilter<X>(query: string, data: X[], cutoff?: number): X[]

  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.

  Type Parameters

  • X

  Parameters

  • query: string

    The search string to match against
  • data: X[]

    Array of data objects to search through
  • cutoff: number = 40

    Minimum similarity score (0-100) for a match to be included (default: 40)

  Returns X[]

  Array of matching data objects with added fuzzy match metadata

  Example

  // 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 cutoff
  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);
  Copy

ProtectedhttpGetHtml

• httpGetHtml(options: RequestOptions): Promise<Maybe<string>>

  Makes an HTTP GET request and returns the response as a string. Handles request configuration, error handling, and HTML parsing.

  Parameters

  • options: RequestOptions

    The request configuration options

  Returns Promise<Maybe<string>>

  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

  // 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 }
  });
  Copy

ProtectedhttpGetJson

• httpGetJson(options: RequestOptions): Promise<Maybe<JsonValue>>

  Makes an HTTP GET request and returns the response as parsed JSON. Handles request configuration, error handling, and JSON parsing.

  Parameters

  • options: RequestOptions

    The request configuration options

  Returns Promise<Maybe<JsonValue>>

  Promise resolving to the parsed JSON response or void if request fails

  Throws

  TypeError - If the response is not valid JSON content

  Example

  // Basic GET request
  const data = await supplier.httpGetJson({ path: '/api/products', params: { search: 'sodium' } });
  Copy

  Example

  // GET request with custom headers
  const data = await supplier.httpGetJson({
    path: '/api/products',
    headers: {
      'Authorization': 'Bearer token123',
      'Accept': 'application/json'
    }
  });
  Copy

  Example

  // GET request with custom host
  const data = await supplier.httpGetJson({
    path: '/products',
    host: 'api.supplier.com',
    params: { limit: 10 }
  });
  Copy

  Example

  // 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);
  }
  Copy

ProtectedqueryProductsWithCache

• queryProductsWithCache(
      query: string,
      limit?: number,
  ): Promise<void | ProductBuilder<Product>[]>

  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.

  Parameters

  • query: string

    The search term to query products for
  • limit: number = ...

    The maximum number of results to return (defaults to instance limit)

  Returns Promise<void | ProductBuilder<Product>[]>

  Promise resolving to array of product builders or void if search fails

  Example

  // Basic usage with default limit
  const results = await supplier.queryProductsWithCache("acetone");
  if (results) {
    console.log(`Found ${results.length} products`);
  }
  Copy

  Example

  // 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);
    }
  }
  Copy

ProtectedfinishProduct

• finishProduct(product: ProductBuilder<Product>): Promise<Maybe<Product>>

  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

  Parameters

  • product: ProductBuilder<Product>

    The ProductBuilder instance containing the partial product to finalize

  Returns Promise<Maybe<Product>>

  Promise resolving to a complete Product object or void if validation fails

  Example

  // 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");
  }
  Copy

Protectedhref

• href(path: string | URL, params?: Maybe<RequestParams>, host?: string): string

  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.

  Parameters

  • path: string | URL

    URL object or string
  • Optionalparams: Maybe<RequestParams>

    The parameters to add to the URL.
  • Optionalhost: string

    The host to use for overrides (eg: needing to call a different host for an API)

  Returns string

  absolute URL

  Example

  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
  Copy

ProtectedgetProductDataWithCache

• getProductDataWithCache(
      product: ProductBuilder<Product>,
      fetcher: (
          builder: ProductBuilder<Product>,
      ) => Promise<void | ProductBuilder<Product>>,
      params?: Record<string, string>,
  ): Promise<void | ProductBuilder<Product>>

  Retrieves product data with caching support. Similar to getProductData but allows for additional parameters to be included in the cache key.

  Parameters

  • product: ProductBuilder<Product>

    The ProductBuilder instance to get data for
  • fetcher: (builder: ProductBuilder<Product>) => Promise<void | ProductBuilder<Product>>

    The function to use for fetching product data
  • Optionalparams: Record<string, string>

    Optional parameters to include in the cache key

  Returns Promise<void | ProductBuilder<Product>>

  Promise resolving to the updated ProductBuilder or void if fetch fails

  Example

  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" }
  );
  Copy

ProtectedgroupVariants

• groupVariants<R>(data: R[]): R[]

  Groups variants of a product by their title

  Type Parameters

  • R

  Parameters

  • data: R[]

    Array of product listings from search results

  Returns R[]

  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

  const results = await this.queryProducts("sodium chloride");
  const grouped = this.groupVariants(results);
  // grouped is an array of product listings with grouped variants
  Copy

Protectedfetch

• fetch(...args: [input: URL | RequestInfo, init?: RequestInit]): Promise<any>

  Internal fetch method with request counting and decorator. Tracks request count and enforces hard limits on HTTP requests.

  Parameters

  • ...args: [input: URL | RequestInfo, init?: RequestInit]

    Arguments to pass to fetchDecorator (usually a Request or URL and options)

  Returns Promise<any>

  The response from the fetchDecorator

  Throws

  Error if request count exceeds hard limit

  Example

  // 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);
  }
  Copy

  Example

  // With custom request options
  const response = await this.fetch(
    new Request('https://example.com', {
      headers: { 'Accept': 'application/json' }
    })
  );
  Copy

Protectedquery

const supplier = new MySupplier("sodium chloride", 10);
console.log(supplier.query); // "sodium chloride"
Copy

ProtectedbaseSearchParams

class MySupplier extends SupplierBase<Product> {
  constructor() {
    super();
    this.baseSearchParams = {
      format: "json",
      version: "2.0"
    };
  }
}
Copy

Protectedcontroller

const controller = new AbortController();
const supplier = new MySupplier("acetone", 5, controller);

// Later, to cancel all pending requests:
controller.abort();
Copy

Protectedlimit

const supplier = new MySupplier("acetone", 5); // Limit to 5 results
for await (const product of supplier) {
  // Will yield at most 5 products
}
Copy

Protectedproducts

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

ProtectedhttpRequestHardLimit

class MySupplier extends SupplierBase<Product> {
  constructor() {
    super();
    this.httpRequestHardLimit = 100; // Allow more requests
  }
}
Copy

ProtectedrequestCount

await supplier.queryProducts("acetone");
console.log(`Made ${supplier.requestCount} requests`);
if (supplier.requestCount >= supplier.httpRequestHardLimit) {
  console.log("Reached request limit");
}
Copy

ProtectedmaxConcurrentRequests

class MySupplier extends SupplierBase<Product> {
  constructor() {
    super();
    // Process 5 requests at a time
    this.maxConcurrentRequests = 5;
  }
}
Copy

ProtectedminConcurrentCycle

Protectedlogger

ProtectedproductDefaults

Protected Static ReadonlyproductDataCacheKey

Protectedcache